Creating games

Until the editor is created, this is how to create games.

• fonts - Fonts used in the game (currently one font is used for everything, but this will change). I advise renaming the fonts to make them all lowercase otherwise linux systems like the gp2x might have problems loading them. The fonts folder sits outside your game folder.
• game.ini - General game options (start zone, screen size etc).
• objects.xml - All objects used in the game. Every element in the game is an object.
• actions.xml - The list of all actions that can be performed in the game. An action is what happens when an object is used.
• images - All images for the game objects. Can be various formats, but png is probably best as you'll almost certainly want to be using some transparency. Each object can have it's own image file, or can be included in a tileset with others. The Hero is always a separate file. A special image is 'icon' (no extension), which is a 16×16 graphic that will be shown in the game selector.
• music - Background music. Various formats can be used depending on what SDL_Mixer supports on your particular platform, but only ogg and mp3 have been tested. Ogg will work much better on the gp2x than mp3. Midi should work, but you'll need the timidity libs on the gp2x.
• save - Where the saved game files go. This folder must exist, even if it is empty. Currently there can only be one save per game.
• sounds - All sound effects. Again, the formats you can use depend on what SDL_Mixer supports on your platform, but these are sounds not music so mp3, mod, and midi won't work (oggs should be fine though, but they will be fully loaded into memory and not streamed like the background music so keep them small). Only wav and ogg have been tested.
• zones - Contains the .map and .ini files for each zone (every separate area is a zone). Each zone must have a .map and .ini.
• cutscenes - Images used for cutscenes. Graphics are automatically resized to fit the game window. A special cutscene graphic is 'title' (with no extension), which is displayed at the continue/new screen.

[general]
#any text with spaces must be enclosed in ""

#game and author names displayed at start and on CACK game selector
game_name="Demo game" # will default to game folder name if missing
game_author=Woogal # will default to unknown if missing

#custom text to be displayed when exit button is pressed. Will default to
#these values if missing
exit_message="Exit current game?"
exit_yes=Yes
exit_no=No

#initial zone must exist
initial_zone=houseupstairs  
#Optional action to be performed after initial zone is loaded
initial_action="1" # quotes needed so numbers can be read as a string

#Font details. If missing will default back to these settings
font=dejavusans.ttf          
font_size=12
font_style=normal # enclose multiple values in "" (eg, "italic bold")

#Font colour in hex
font_color=0xffffff          

#The text background can also have an alpha channel,
#so the format is RGBA
font_background=0x00000080   

#Text to be displayed on inventory screen
inventory_name=Bag

[video]
#Area size is the size of the zones on the screen. These settings
#will place a 160x120 window in the centre of a 320x240 display.
area_width=160              
area_height=120

#On windows, this changes the size of the window. The gp2x will
#scale the screen size to fit onto the physical screen (eg,
#set the screen size to 160x120 to make all graphics 2x). 
screen_width=320            
screen_height=240          

[sound]
#Default sound to play when using objects. Also plays when an
#object has no action.
default_use_sound=noaction.wav
default_use_volume=70

Everything in CACK is made up of objects. The Hero, all zone tiles, and even inventory items are all objects and should be listed in objects.xml. The Hero is always object 0 unless set in the starting zone ini. The xml isn't checked for errors, so CACK will crash if the xml is incorrect. All attributes should be contained in ” (x=“0” is right, x=0 is wrong), and all tags should be closed (if a tag doesn't contain anything (like walkable) then the tag can be closed like this <walkable/>). All object tags are optional apart from the name.

<object id="7">
  <name>name</name>
  <walkable/>
  <image x="0" y="0">image.png</image>
</object>

Object tags reference (italics = optional attribute)

• <name> – Displayed when the object is in the inventory.
• <image x y h frames> – Without any attributes, the whole image is used as the object graphic (the Hero must be done in this way). With attributes, x and y specify the 16×16 block to be used as the top left corner of the tile. h is the height of the tile in blocks. frames is the number of frames in the animated tile (see Graphics below for more info on tiles and animation).
• <description> – Appears in the bottom bar when the Hero stands next to or on top of the object.
• <walkable> – Specifies that the Hero can move over the object.
• <ambient vol> – The sound effect to play in the background when the Hero approaches the object. If there are more than one objects in the current zone with the same ambient sound, then the centre point is determined so there is only ever one sound playing (eg, in the demo game the water outside in the bottom left corner contains several objects with the water sound. The sound will appear to come from the center of the water area).
• <use user action> – The action to be performed when this object is used by object user. user -1 means the action is automatically triggered if the object is walked on (handy for random monsters appearing or walking sounds), user 0 is the Hero and any other value means an item from the inventory is being used. An object can contain several use tags as an object can be used by several users. action can also be a list with elements seperated by ; (eg. “1;2;3;4”). This will cause a random action from the list to be performed. Setting an action of -1 means no action will be performed. This only makes sense for random actions (eg. ”-1;-1;-1;-1;10”. 1 in 5 times action 10 will be triggered, 4 times out of 5 nothing will happen.)

An action is performed when an object is used or when a trigger is walked over (see Zones below).

<action id="0">
  <sound vol="20">sound.wav</sound>
  <usetext>
    <p>Page 1 of text.</p>
    <p>Page 2 of text.</p>
  </usetext>
  <inventorydel id="40"/>
  <inventoryadd id="41"/>
</action>

Action tags reference (italics = optional attribute)

• <sound vol> – The sound to be played when the action is performed. Set this to default to play the default sound set in game.ini.
• <usetext> – Contains a collection of p tags.
• <p speaker smallspeaker x y w h> – Text to be displayed. x y w h set the size of the textbox. If the size is greater than the area size (see game.ini above) then the box will shrink to fit the area. speaker references an object id, and sets which graphic will be displayed with the text. smallspeaker=“1” will display a normal size graphic instead of the default double size. smallspeaker will be automatically set if the usetext size is greater than the area size and has to be shrunk. Each p will display on a new screen.
• <inventoryadd id> – Adds the object into the inventory.
• <inventorydel id> – Removes one instance of the object from the inventory.
• <teleport zone x y action dir> – Teleports to zone at position x,y. If action is set, then the action will be performed once the teleport is complete. Optional dir sets the hero facing direction (0:right, 1:down, 2:left, 3:up). If dir isn't set then the facing direction remains the same as before the teleport.
• <change from to> – Changes the object at position from to the new object id to. from format is “zonename.x,y”. !this in place of zonename will modify the current zone. !this can also be used in place of x and y to refer to the x and y positions of the object being used. +,- can be used as offsets from the object position. eg, ”!this.!this+1,!this” refers to the object to the right of the object being used (x+1). ”!this” is a shortcut for ”!this.!this,!this”, or in other words the object being used.
• <doaction id delay> – Perform the action id. id can also be a list with elements seperated by ; (eg. “1;2;3;4”). This will cause a random action from the list to be performed. Setting an action of -1 means no action will be performed. This only makes sense for random actions (eg. ”-1;-1;-1;-1;10”. 1 in 5 times action 10 will be triggered, 4 times out of 5 nothing will happen). If delay is set, the action is performed after delay milliseconds. Delayed change actions shouldn't use the !this shortcuts as the hero may not be standing at the same position/zone when the action is finally performed.
• <changehero id> – Change the hero object to id, which only effects the hero appearance.
• <cutscene image transition duration> – Display an image for the specified duration. Images are scaled (up or down) to fill the screen. Duration is the number of seconds to display the image after the transition has completed. Duration=“user” will wait for input from the user instead. Transition is one of fade (fade from/to black), xfade (crossfade between images), pxwipe (a wipe effect I first saw in Project X by Team 17), wipeleft, wiperight, wipeup, wipedown (normal wipes), slideleft, slideright, slideup, slidedown (normal slides).

Zones can be any size (not tested huge zones do I don't know if there's an upper limit other than memory). Each zone has a .ini and a .map.

.ini

[general]
#width and height of zone in 16x16 pixel blocks
width=30
height=20
#The hero values below are only used if this is a starting zone
#Starting position of the Hero.
hero_x=2
hero_y=2
#object id of the hero.
hero_id=90
#facing direction of the hero (0:right, 1:down, 2:left, 3:up).
#Defaults to 0
hero_dir=3
[sound]
#Background sound. Constantly plays
ambient=zone1.wav
ambient_volume=7

#Background music
music=zone1.ogg
music_volume=50

.map

The maps are a grid of object IDs.

01,01,01,01
01,02,02,01
01,02,02,01
01,01,01,01

The width and height must match the values set in the .ini. After the main map data comes the list of triggers. A trigger is a block on the map which will perform an action if the block is walked on. The trigger list is x,y,action with one trigger per line. Action is either a single action id or a list as with use and doaction above. With any map positioning (triggers, teleports, changes etc.) 0,0 is the top left block.

The Hero graphic should contain the Hero facing (from the top) right, down, left, up. The height of every position should be the same (but can be any height) and the width must be 16. The Hero can have 1, 2, 4, 8, or 16 frames of animation. The frames should be placed alongside each other (so if there are 4 frame the final graphic will be 64 pixels wide). The graphic should be something like a png so the background can be transparent.

All other object images can either be seperate files like the Hero, or can be collected together in tilesets. In a tileset, all images should be placed on a 16×16 pixel grid. The Hero is the only image that can have it's base placed over other images, so all object images should make sure they include a background in the base block (eg, a tree trunk should also include the floor in it's base block). Objects taller than 16 pixels can have transparency on the pixels above 16 as these will overlap the blocks above on the map. If the height of an object image is not a multiple of 16, then it's bottom should be aligned on the grid, not it's top. Objects can also have animated tiles, and the animation will loop every second. CACK plays at 30fps, so there can be up to 30 frames of animation. Animation is done in the same way as the Hero, with each frame placed in the tileset to the right of the last.

If separate images are used instead of a tileset, then the height and number of frames are automatically calculated from the width and height of the image and don't need to be entered into objects.xml.