Poga 4dgl User manual

PoGa - 4DGL Portable Game Console

Reference Manual

Document Date: 18th January 2011

Document Revision: 2.0

Portable Game Console PoGa-4DGL Reference Manual

Table of Contents

1. What is PoGa?..........................................................................................................................3

2. System requirements (all the resources/ ownloa s you nee ).................................................4

2.1 Hardware....................................................................................................................................4

2.2 Software ....................................................................................................................................4

2.3 Documents.................................................................................................................................4

3. Creating your first PoGa Program.............................................................................................5

3.1 Your first PoGa Program.............................................................................................................5

3.2 Writing your first PoGa game.....................................................................................................8

3.3 Writing your second PoGa game.............................................................................................1

3.4 Adding Graphics to your program............................................................................................12

3.5 Let’s add graphics to the TextTiler...........................................................................................15

4. A Images/Animations/Vi eos in your game........................................................................20

4.1 Building GCI DEMO .................................................................................................................2

4.2 Building the Tiler Demo...........................................................................................................28

5. PoGa Explorer........................................................................................................................39

5.1 PoGa Screenshot......................................................................................................................39

5.2 Formatting the SD card to PoGa Format .................................................................................4

5.3 Adding Folders.........................................................................................................................42

5.4 Copying programs to the DISK.................................................................................................43

5.5 Deleting programs from the DISK............................................................................................43

6. Inclu ing your game into the PoGa File System.......................................................................44

6.1 Setting PoGa Disk.....................................................................................................................44

6.2 Testing the files on the PoGa Disk............................................................................................51

7. PoGa Sprite E itor..................................................................................................................52

7.1 Making your First Sprite...........................................................................................................53

7.2 Making few more Sprites.........................................................................................................63

8. Creating an controlling sprites..............................................................................................73

Appen ix A: PoGa File System Overview...................................................................................................76

Appen ix B: PoGa Schematic.....................................................................................................................80

Appen ix C: Software/Driver Installation Gui e........................................................................................81

Appen ix D: Microsoft’s ‘User Account Control’ (UAC)..............................................................................85

Proprietary Information.............................................................................................................87

Disclaimer of Warranties & Limitation of Liability.......................................................................87

Portable Game Console PoGa-4DGL Reference Manual

1. What is PoGa?

Playing a computer game is one thing, but have you ever wondered how these games are produced?

•Do you want to learn how to make your own computer games?

•Is it really a 'dark art' practised by gurus working in secret for large companies?

•Do you want the satisfaction of showing your friends cool games that you have created?

4D Systems would like to introduce the PoGa, a Portable Game Development console and 4DGL (4D

Graphics Language), a cost effective way for you to be able to learn all about game development and

programming.

PoGa incorporates a 128 x 128 pixel full colour TFT display, 'standard' game console push button layout for

controlling the game flow, a small loudspeaker for sound effects, and a micro SD card for storing images and

game data. It is driven by the tiny yet powerful GOLDELOX-PoGa custom graphics processor from 4D Labs.

Graphics, text, image, animation and countless more features are built right inside the chip. For portability

the PoGa can be powered for many hours on standard 3xAAA batteries.

The 4D Graphics language provides enough power and flexibility to make some really cool games and learn

the 'art of programming' with a leisurely learning curve.

The 4D Workshop incorporates a text editor, graphics tools, and program down-loader in a neat and easy to

use package.

You can have your first demo game running within minutes and then start to understand how to modify and

improve existing games or use 'building blocks' of code to create your very own games!

The aim of the PoGa is to provide a highly educational game development platform, at the same time

providing lots of fun designing and playing arcade quality games!

Note: The GOLDELOX-PoGa is a close variant of the GOLDELOX-GFX2 chip.

Portable Game Console PoGa-4DGL Reference Manual

2. System requirements (all the resources/ ownloa s you nee )

2.1 Har ware

•PoGa

•4D Programming Cable OR (uUSB-MB5 + USB extension Cable)

•Windows PC

•micro-SD memory card (2gb or above ... optional)

2.2 Software

•PoGa PmmC

•4D Workshop

◦PmmCloader

◦Graphics Composer

◦Sprite Editor

◦PoGa Explorer

•uUSB-MB5 Driver

•4D Programming Cable Driver

2.3 Documents

•PoGa-QuickStart-Guide.pdf

•PoGa-Kit-Construction-and-Assembly-Guide-revXX.pdf

•PoGa-4DGL-Portable-Game-Console-Reference-Manual-revXX.pdf

•GOLDELOX-PoGa-4DGL-Internal-Functions-revXX.pdf

•4DGL-Programmers-Reference-Manual-revXX.pdf

Note: Refer to Appen ix C for Installation Guide.

Note: mico-SD card is also referred as uSD card.

Note: You will need a separate USB A-to-miniB cable to use with the uUSB-MB5 module.

Note: The minimum size memory card you will need for the PoGa-Disk is 2Gb. To format the card and to

add your games and applications you will need to use the PoGa-Explorer software tool that's included in the

4D Workshop3 IDE.

Portable Game Console PoGa-4DGL Reference Manual

3. Creating your first PoGa Program

All of the example program files used in this section can be found at ‘All Users\Shared Documents\4D

Labs\PoGa Intro\’ folder (XP) or ‘Users\Public\Documents\4D Labs\PoGa Intro\’ folder (Vista and Windows

7).

3.1 Your first PoGa Program

Fire up WorkShop

Click Start, Programs, 4D Workshop 3 IDE, Workshop

Start a new Program

'New' Icon in the Tool bar

Portable Game Console PoGa-4DGL Reference Manual

Click ‘New’ Icon or “New” in the File menu; Select ‘4DGL program’, if necessary. This will create a program

with an empty shell, the 1st line is the platform type and will be filled in for you, if necessary, change this to

PoGa-Goldelox by using the ‘Platform’ Combobox in the middle immediately above the editor.

A some housekeeping co e

For this first example we simply need a main function and end function.

func main()

endfunc

A the co e

func main()

print("Hello world\n") ;

repeat

forever

endfunc

Notice that print uses ‘standard’ C escape characters, it doesn’t really do anything here it’s just to show that

it can be used.

The ‘repeat’ and ‘forever’ is just to keep the program running in an endless loop, rather than exit back to

the PmmC or menu program.

Run it

If you haven’t connected your PoGa to the computer, do it now.

Select the com port using the combobox to the left of the traffic light.

Choose the Platform

Choose the Com Port

Portable Game Console PoGa-4DGL Reference Manual

Now Press F9 which will compile your program, download it to your PoGa and start running it. You could

also have clicked on “Comp’nLoad” which is the same thing.

Save the program with the file name 'helloworld.4dg'

Snazzy it up

Move the cursor and insert a new line before the ‘print’ statement, type “txt_” and press Ctrl-Space, this

will bring up a list of all the functions starting with “txt_”, select “txt_Height” either by positioning the

cursor and pressing Enter, or by clicking with the mouse.

Keep typing until your code looks like the following.

func main()

txt_Height(2);

txt_Bold(ON);

txt_ talic(ON);

txt_MoveCursor(3, 3);

txt_FGcolour(WH TE);

print("Hello world\n") ;

repeat

forever

endfunc

Since you have used WHITE as a color you need to tell the compiler where to locate the definition of

WHITE, so insert the following line after the platform statement.

#inherit "4DGL_16bitColours.fnc"

If you want to have a look inside ‘4DGL_16bitColours.fnc’, just right click the filename and select ‘Open File

at Cursor’. Now press F9 again and see what is displayed this time.

You may Save As with a different name, like 'helloworld2.4dg'

Click Comp'nLoad button

Portable Game Console PoGa-4DGL Reference Manual

3.2 Writing your first PoGa game

Start a new Program

Click on the ‘New’ Icon again, the file type should be ‘4DGL program’, since that’s what you created last

time, then click OK. The platform should be PoGa-Goldelox, since that’s what we selected last time.

We are going to write a simple target shooting game, so lets start by including the color definitions and

adding some constants.

#inherit "4DGL_16bitColours.fnc"

#constant LineLen 5 // length of each crosshair line

#constant BoomPause 100 // pause between each expanding circle for the kaboom function

#constant TgtSize 4 // distance from centre-point to start of crosshair lines

#constant ndent 20 // ndent must be >= Linelen + TgtSize so cursor stays within

display area

And some global variables.

var xtgt, ytgt ; // position of the red circle (target)

var xcross, ycross ; // crosshair position

var xcrosso, ycrosso ; // old crosshair position

We’ll need some effects to be displayed when the target is hit.

// a sequence to show that we 'hit' the target

func kaboom()

var i ;

for (i := 1;i < ndent;i++)

gfx_CircleFilled(xtgt, ytgt,i, RAND());

beep(i*210,BoomPause/2) ; // beep as we go

pause(BoomPause) ;

A routine to move the crosshairs around the screen.

func writescreen()

// erase old crosshairs

gfx_Line(xcrosso-TgtSize-LineLen,ycrosso,xcrosso-TgtSize,ycrosso,BLACK) ;

gfx_Line(xcrosso+TgtSize,ycrosso,xcrosso+TgtSize+LineLen,ycrosso,BLACK) ;

gfx_Line(xcrosso,ycrosso-TgtSize-LineLen,xcrosso,ycrosso-TgtSize,BLACK) ;

gfx_Line(xcrosso,ycrosso+TgtSize,xcrosso,ycrosso+TgtSize+LineLen,BLACK) ;

gfx_CircleFilled(xtgt, ytgt,TgtSize-1, RED); // incase crosshairs were covering it

// Write new crosshairs

gfx_Line(xcross-TgtSize-LineLen,ycross,xcross-TgtSize,ycross,WH TE) ;

gfx_Line(xcross+TgtSize,ycross,xcross+TgtSize+LineLen,ycross,WH TE) ;

gfx_Line(xcross,ycross-TgtSize-LineLen,xcross,ycross-TgtSize,WH TE) ;

gfx_Line(xcross,ycross+TgtSize,xcross,ycross+TgtSize+LineLen,WH TE) ;

endfunc

Note that we erase the old crosshairs by redrawing them in BLACK before drawing the new crosshairs in

white.

Portable Game Console PoGa-4DGL Reference Manual

And now the main function, compile and download, saving it as 'Target.4dg'.

func main()

var i, newgame;

SEED(peekB(SYSTEM_T MER_LO)) ;

newgame := 1 ;

while(1)

if (newgame == 1) // if this is a new game

xcross := 63 ; // set crosshairs to screen centre

ycross := 63 ;

xcrosso := 63 ;

ycrosso := 63 ;

xtgt := (ABS(RAND()) % (128 - 2* ndent)) + ndent ; // make rand pos for the tgt

ytgt := (ABS(RAND()) % (128 - 2* ndent)) + ndent ;

gfx_Cls(); // clear the screen

newgame := 0 ; // new game now set, clear newgame flag

endif

writescreen() ; // update display with crosshair and target

xcrosso := xcross ; // save current crosshair, needed so we can erase old position

ycrosso := ycross ;

while((i := joystick()) == 0) ; // read the joystick value

pause(50) ; // pause a little bit, so we get autorepeat

if ((i == UP) && (ycross != ndent)) // move crosshair if within bounds

ycross := ycross -1 ;

else if ((i == DOWN) && (ycross != 128- ndent-1))

ycross := ycross +1 ;

else if ((i == R GHT) && (xcross != 128- ndent-1))

xcross := xcross +1;

else if ((i == LEFT) && (xcross != ndent))

xcross := xcross -1;

else if (i == BTNB) // else see if it was the fire button

beep(20,200) ;

if ((xcross == xtgt) && (ycross == ytgt)) // if cross is same as the target

kaboom() ; // do the kaboom sequence

newgame := 1 ; // set flag so we start a new game

endif

wend // loop forever

endfunc

A snapshot of the 'Target.4dg'.

Portable Game Console PoGa-4DGL Reference Manual

3.3 Writing your secon PoGa game

Start a new Program

Click on the ‘New’ Icon again, the file type should be ‘4DGL program’, since that’s what you created last

time, then click OK. The platform should be PoGa-Goldelox, since that’s what we selected last time.

We are going to write a computer version of the classic ’15 puzzle’, so lets start by including the color

definitions and adding some constants.

#inherit "4DGL_16bitColours.fnc"

#constant TileSX 32 // pixel width of each Slider

#constant TileSY 32 // pixel height of each Slider

#constant TileNX 4 // Number of Tiles in X direction

#constant TileNY 4 // Number of Tiles in Y direction

And some initialised global variables.

var chars[16] := ['A','B','C','D','E','F','G','H',' ','J','K','L','M','N','O','P'] ;

var posn[16] := [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] ;

See the program snapshot below.

Portable Game Console PoGa-4DGL Reference Manual

And now the main function.

func main()

var i, j, xp, yp, xn, yn, newgame;

SEED(peekB(SYSTEM_T MER_LO)) ;

newgame := 1 ;

while(1)

if (newgame == 1)

for(i := 0; i < 16; i++) // randomise sliders

SWAP(&posn[i],&posn[ABS(RAND() % 16)]) ;

for(j := 0; j < TileNX; j++)

if (posn[i*TileNY+j] == 15)

gfx_RectangleFilled(j*TileSX,i*TileSY,(j+1)*TileSX-1,(i+1)*TileSY-

1,BLACK);

yp := i ;

xp := j ;

else

pokeB(TEXT_XMAG,3) ;

pokeB(TEXT_YMAG,3) ;

gfx_MoveTo(j*TileSX, i*TileSY) ;

print([CHR] chars[posn[i*TileNY+j]]);

endif

newgame := 0 ;

endif

yn := yp ;

xn := xp ;

while((i := joystick()) == 0) ; // read the joystick value

pause(200) ;

if ((i == UP) && (yp != 0)) // move slider if within bounds

yn := yp -1 ;

else if ((i == DOWN) && (yp != TileNY-1))

yn := yp +1 ;

else if ((i == R GHT) && (xp != TileNX-1))

xn := xp +1;

else if ((i == LEFT) && (xp != 0))

xn := xp -1;

endif

if ((yn != yp) || (xn != xp)) // if sucessful move, reorder board

gfx_RectangleFilled(xn*TileSX,yn*TileSY,(xn+1)*TileSX-1,(yn+1)*TileSY-1,BLACK) ;

gfx_MoveTo(xp*TileSX, yp*TileSY) ;

pokeB(TEXT_XMAG,3) ;

pokeB(TEXT_YMAG,3) ;

print([CHR] chars[posn[yn*TileNY+xn]]);

SWAP(&posn[yn*TileNY+xn],&posn[yp*TileNY+xp]) ;

yp := yn ;

xp := xn ;

endif

j := 0 ; // check for everything in correct order

for(i := 0; i < 16; i++)

if (i != posn[i]) j := 1 ;

gfx_MoveTo(xp*TileSX, yp*TileSY) ;

pokeB(TEXT_XMAG,3) ;

pokeB(TEXT_YMAG,3) ;

print([CHR] chars[15]);

beep(20,1000) ;

pause(1000) ; // wait for beep to end

newgame := 1 ;

endif

wend

endfunc

Now compile and download this, saving it as TextTiler.

Portable Game Console PoGa-4DGL Reference Manual

3.4 A ing Graphics to your program

Start Graphics Composer

Select Tools, Graphics Composer from the Workshop menu. Graphics Composer will start and begin a new

graphics project.

Note: If you get a ‘User Account Control’ message when starting Graphics composer, please refer to

Appendix D.

A a graphic

Click Add on the bottom left.

Navigate to C:\Documents and Settings\All Users\Documents\4D Labs\PoGa Intro\Target-Vid\Images and

add Explode- 2-june.gif.

Portable Game Console PoGa-4DGL Reference Manual

Buil the graphics output

Insert an ‘empty’ uSD card into your computer, Click on the chip icon. Save the GCS as EXPLODE.

Select ‘4DGL – uSD Raw – GCI at Specified offset’ as the build type.

Select the drive you inserted the uSD card into and a sector offset of .

Click OK, this will convert the Explode- 2-june.gif file into a video and save it to the uSD card.

Click the Chip icon

Portable Game Console PoGa-4DGL Reference Manual

Change TARGET to inclu e a Movie when the target is hit.

Open Target.4DG in workshop (if it isn’t still open).

Add the following code at the start of the main procedure (immediately after the vars) .

repeat

pause(200);

gfx_Cls();

if(media_ nit()) break; // initialise and test the uSD card

putstr("No Disk");

forever

Change the KaBoom function as follows.

func kaboom()

beep(200,2000) ;

gfx_Set(CL PP NG,ON) ;

media_SetSector(0,0);

media_Video(xtgt-39,ytgt-60) ;

endfunc

Remove the uSD card from your computer and insert it into your PoGa.

Save this as TARGET-VID and compile and download.

Note: For an in depth treatment of Graphics composer See section 4.2.

Portable Game Console PoGa-4DGL Reference Manual

3.5 Let’s a graphics to the TextTiler

Click on the ‘New’ Icon in Graphics composer.

A a graphic

Click Add on the bottom left. Navigate to C:\Documents and Settings\All Users\Documents\4D Labs\PoGa

Intro\15Puzzle-GFX\Images and add PoGaDog.bmp.

Portable Game Console PoGa-4DGL Reference Manual

Mo ify it

Check ‘Tiled’ under ‘Image Attributes’ and change the tile width and height to 32

Buil the graphics output

Insert an ‘empty’ uSD card into your computer , Click on the chip icon. Save the GCS as POGADOGTILED.

Select ‘4DGL – uSD Raw – GCI at Specified offset’ as the build type.

Select the drive you inserted the uSD card into and a sector offset of .

Click OK, this will convert the PoGaDog.bmp file into a video of the bitmap cut up into 32x32 tiles and save

it to the uSD card.

Check the 'Tiled'check box

Portable Game Console PoGa-4DGL Reference Manual

Mo ify the TextTiler program

Open TextTiler.4DG in workshop (if it isn’t still open).

Add the following code at the start of the main procedure (immediately after the vars) .

if(media_ nit() == 0) // initialise and test the uSD card

print("No uSD CARD\n");

while(1);

endif

for(i := 0; i < TileNY; i++)

for(j := 0; j < TileNX; j++)

media_VideoFrame(j*TileSX, i*TileSY, i*TileNY+j);

pause(2000) ;

This shows the puzzle as it will look when complete, just in case it looks too messed up to understand when

it is randomised.

Replace the Initial tile writing at line 46 (if using the sample code, or approximately line 37 if cutting and

pasting from this doc).

pokeB(TEXT_XMAG,3) ;

pokeB(TEXT_YMAG,3) ;

gfx_MoveTo(j*TileSX, i*TileSY) ;

print([CHR] chars[posn[i*TileNY+j]]);

With

media_VideoFrame(j*TileSX, i*TileSY, posn[i*TileNY+j]);

Portable Game Console PoGa-4DGL Reference Manual

Replace the updated tile writing at line 67 (if using the sample code, or approximately line 58 if cutting and

pasting from this doc). Maybe shorten here.

gfx_MoveTo(xp*TileSX, yp*TileSY) ;

pokeB(TEXT_XMAG,3) ;

pokeB(TEXT_YMAG,3) ;

print([CHR] chars[posn[yn*TileNY+xn]]);

With,

media_VideoFrame(xp*TileSX, yp*TileSY, posn[yn*TileNY+xn]);

Replace the final tile writing at line 78 (if using the sample code, or approximately line 68 if cutting and

pasting from this doc). Maybe shorten here.

gfx_MoveTo(xp*TileSX, yp*TileSY) ;

pokeB(TEXT_XMAG,3) ;

pokeB(TEXT_YMAG,3) ;

print([CHR] chars[15]);

With,

media_VideoFrame(j*TileSX, i*TileSY, posn[i*TileNY+j]);

Portable Game Console PoGa-4DGL Reference Manual

Remove the uSD card from your computer and insert it into your PoGa.

Save this as GFXTiler and compile and download.

Note: You can cut and paste the programs from the test boxes in this chapter or find them in the ‘All

Users\Shared Documents\4D Labs\PoGa Intro\’ folder (XP) or ‘Users\Public\Documents\4D Labs\PoGa

Intro\’ folder (Vista and Windows 7).

Portable Game Console PoGa-4DGL Reference Manual

4. A Images/Animations/Vi eos in your game

Up to 256 images/movies/animations can be stored within each PoGa file space and referenced with a

special index list. For each PoGa file, storage of up to 396 sectors (2, 27,52 bytes) is available and can be

accessed using the SelectGCIimage function. The position of each image entry is also saved, allowing you to

build an entire screen of objects using the Graphics Composer as a WYSIWYG format. The information here

is a description of how this can be achieved by taking you through the steps that were taken to create the

GCI file for the GCI_Demo.

4.1 Building GCI DEMO

Note: The GCI_Demo.4DG example demonstrates the use of the me ia_SelectGCIimage function.

From the Workshop toolbar, select the Graphics composer tool.

When the graphics Composer opens, select New from the File menu. Now, navigate to the project folder

and add the required bitmaps and animations to the project by holding the left shift key down while clicking

on each of the file names so we select them all.

PoGa 4DGL User manual

Popular Game Console manuals by other brands