Custom Avatars
Note that this guide is specific to version 1.2.0 of the game. From version 1.3.0 the avatar format changed. See here for an updated guide.
From version 1.2.0 custom avatars can be added to the golf game in a similar way to custom golf balls. If you've read the custom ball guide you should have some idea of what to expect, but all the relative points will be covered here too.
Avatars are composed of several files. They require an image atlas containing the frames which make up the sprite animation. They also need a sprite sheet description, as used by all crogine sprites, which describe the frame and animation details. They also need an avatar description file which tells the golf game which sprite sheet to use, as well as metadata used to synchronise avatars across a network game. The first section of the guide covers creating these assets. The second section covers some optional enhancements which can be added to avatars.
Sprite sheet images should contain all the frames needed to display 4 animations. These animations are
- Idle - Wood club
- Idle - Iron club
- Swing - Wood club
- Swing Iron club
Each frame in the animation should be 64 pixels wide by 96 pixels high.
This guide won't cover the topic of drawing and animating the sprites themselves - software like Aseprite or Pyxeledit have vast friendly communities who are willing to help out if you are new to creating and animating pixel art sprites. Once you have your artwork completed you need to create a sprite definition file, which is a text file with the file extension .spt. Sprite definition files have the following layout:
spritesheet player01
{
src="assets/golf/images/player01.png"
sprite wood
{
bounds = 0,96,64,96
animation idle
{
frame = 0,96,64,96
loop = true
framerate = 30
}
animation swing
{
frame = 0,96,64,96
frame = 64,96,64,96
frame = 128,96,64,96
frame = 192,96,64,96
frame = 256,96,64,96
frame = 320,96,64,96
frame = 384,96,64,96
frame = 448,96,64,96
frame = 512,96,64,96
frame = 576,96,64,96
frame = 640,96,64,96
frame = 704,96,64,96
frame = 768,96,64,96
event = 0,5
loop = false
framerate = 12
}
}
sprite iron
{
bounds = 0,96,64,96
animation idle
{
frame = 0,96,64,96
loop = true
framerate = 30
}
animation swing
{
frame = 0,96,64,96
frame = 64,96,64,96
frame = 128,96,64,96
frame = 192,96,64,96
frame = 256,96,64,96
frame = 320,96,64,96
frame = 384,96,64,96
frame = 448,96,64,96
frame = 512,96,64,96
frame = 576,96,64,96
frame = 640,96,64,96
frame = 704,96,64,96
frame = 768,96,64,96
event = 0,5
loop = false
framerate = 12
}
}
}
The file opens with a declaration that it is a sprite sheet named player01. The text format, used by crogine, denotes sets of 'objects' which are contained within a pair of opening and close braces. Each object can have one or more properties, denoted by <name> = <value>. Objects can also have further objects within them. spritesheet itself is an object and it has one property src which describes the location in the assets directory of the sprite sheet image. It also has two child objects, both of the type sprite, which have the names wood and iron. These objects each then contain the properties which make up the sprite seen in game. It is important to note that the sprites for an avatar must be specifically named wood and iron else they will not be loaded.
The sprite bounds property describes the left,bottom corner in pixel coordinates of the default frame, followed by the width and height. All frame values start counting from the bottom left of the image containing the avatar graphics. Each sprite in the sprite sheet should have two animation objects, named idle and swing. These objects contain frame properties describing each frame making up the animation, in the order in which they should be displayed. The event property is a comma separated list of event ID and frame number. The event ID of 0 tells the game to play the club swing sound, and frame number 5 says the sound should be played when the animation reaches frame 5. You can adjust the frame number to match your animation as appropriate. The loop property is false, stating that the animation should not loop. Finally the framerate property tells the game how fast to play the animation, in frames per second.
In general the sprite sheet image is placed in the assets/golf/images directory and the sprite sheet description is placed in the assets/golf/sprites directory, although these can be anywhere as long as it's within assets and the src property points to the correct image location.
Once both of the sprite files are created an avatar definition file needs to be put in the assets/golf/avatars directory - this is the only place they can be saved, as the game searches only this directory for avatars. The avatar definition file is also a text document, with the file extension .avt. The format of the file is as follows:
avatar
{
sprite = "assets/golf/sprites/player01.spt" //path to the sprite sheet for the avatar
audio = "assets/golf/sound/avatars/player01.xas" //path to the optional audioscape file for the avatar
uid = 10 //see below
}
Each avatar file requires a unique ID associated with it - this is used to synchronise avatars across network games. The number should be between 0 and 255, and not have the same value as another avatar in the the current directory. If an exisiting UID is already loaded then the avatar file will be skipped when VGA Golf loads, printing a message to the console warning which UID was duplicated.
For more detailed information on this file see avatar_format.md in the mod_kit available from itch.io or in the mod_kit directory of the repository. However, once you have these three files this should be enough to see your avatar in game. To further enhance your avatars you can add custom audio, as well as allow players to choose colours for their avatar in-game:
Avatars can also have custom audio files associated with them, however these are optional. To add audio to an avatar you need to create an AudioScape, which is a text file containing information about audio files that the game can read, so it knows how they should be played. Audioscape files for an avatar look for specific emitter names, an example AudioScape would look like this:
audioscape player01
{
emitter bunker
{
path = "assets/golf/sound/avatars/bunker01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter fairway
{
path = "assets/golf/sound/avatars/fairway01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter green
{
path = "assets/golf/sound/avatars/green01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter hook
{
path = "assets/golf/sound/avatars/hook01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter rough
{
path = "assets/golf/sound/avatars/rough01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter scrub
{
path = "assets/golf/sound/avatars/scrub01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter slice
{
path = "assets/golf/sound/avatars/slice01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
emitter water
{
path = "assets/golf/sound/avatars/water01.wav"
streaming = false
volume = 0.6
mixer_channel = 3
attenuation = 0.06
looped = false
}
}
Note that the format is the same as a sprite sheet or avatar definition file, although audioscape files are saved with the extension .xas. Each of these emitters are optional, the game will play a fallback sound if an emitter is not defined. Emitters are also selected at random between the avatar and in-game announcer, so the avatar sounds many not play every time for a specific event. Sound files should be short and in stereo to be heard correctly. Usually you would choose an appropriate vocal for the event at hand, ie a celebratory cheer when landing on the green, or a groan for landing in a bunker or the water. Whichever you decide to choose is of course entirely up to you. Once you have created the audioscape and relevant audio files, make sure to place them somewhere in the assets directory, preferably in the sound sub-directory. To load the audioscape in game, make sure to add a reference to it to the .avt file (see above).
To allow players to customise the colours of their avatars, an extra step needs to be taken when creating the sprite images used for the avatar. In the sprite sheet image above you may question why the avatar appears very grey instead of colourful. It is true that by default any colours you use to create your sprite will appear in game, but using specially selected grey values will 'key' in custom colours chosen by the player at run time.
There are four colour keys available, each with a light and dark variant:
- Bottom - the bottom half of clothing
- Top - the top half of clothing
- Skin - the avatar's skin tone
- Hair - the avatar's hair colour
To enable one or more of these keys use one of the following light/dark grey colours (RGB)
- (10,10,10) - (0,0,0)
- (40,40,40) - (30,30,30)
- (70,70,70) - (60,60,60)
- (100,100,100) - (90,90,90)
When the game runs it will replaces any grey pixels with the colour chosen by the player in the avatar customisation menu. As well as the avatar sprites, 'Top' and 'Bottom' colours are also used on the player labels, seen when putting in a multiplayer game.
If you create any custom avatars, please share them via itch or Twitter!