Adding sound, video, fonts, etc. to your game

SkeletonGame provides an built-in asset manager that is driven by a simple YAML file format. On game launch, the asset manager will pre-load all the assets defined in config/asset_list.yaml. The asset_list.yaml, associates files (images, animations, sounds, music, fonts, and lampshows) with “friendly” names, and allows for custom settings for each of these items (e.g., change the default volume of a sound, change the x/y position of a sprite). Once these assets have been loaded, they can be used in code or in other locations by referring to their key (alias).

Looking at an example asset_list.yaml (this is the example that comes with SampleGame), we can disect the components expected to be present:

1. Loader User Interface: The visual layout of the asset loading screen that will be shown while your assets are being pre-loaded (on game launch)
2. LampShows: a mapping of lamp show file names and logical names (i.e., keys) by which they will be defined. Defining a lampshow in this file causes the lampshow to be parsed and validated during asset loading, so if there is in error in the lampshow you will find out immediately instead of when your code eventually goes to play the lampshow.
3. Animations: a list of images and animations to be used in your game; minimally their file names and their logical names (i.e., keys). By including an entry the image or animation will be pre-loaded, ready for use in your game’s mode code. Supported formats include the ‘dmd’ format, many common single frame formats: jpg, gif, png (per pixel alpha supported), and some animation formats such as gif (for animated gifs) and single frame file sequences (e.g., a file range from my_image000.png through my_image029.png would be specified with the file name my_image0%3d.png and all 30 would be loaded as the frames of a single animation).
4. HDFonts: Native system fonts (TTF) and aliases for specific sizes of those fonts
5. Fonts: Bitmap fonts, based on the PyProcGame font format
6. Audio, Music, Voice: Audio files named via key (wav or ogg format).

UserInterface – what the loading bar looks like

Settings in this section modify what the user sees when the game is pre-loading assets.

UserInterface:
  splash_screen: 'loading.png'
  progress_bar:
      x_center: 0.5
      y_center: 0.25
      width: 0.9
      height: 0.10
      border: [255, 0, 255]
      fill: [0,255,0]
  text:
    color: [0,0,128] # no 0/255 Red, 0/255 Green, 128/255 Blue
    y_center: 0.3

The splash_screen is an image file to be shown underneath the information displayed during pre-load. progress_bar defines the size and position of the progress_bar relative to the overall screen size. In the example above the full-width of the bar is 90% (width: 0.9) of the window, and 10% of the height of the window (height: 0.10). It is centered on the X-axis (0.5) and appears in the top 1/4 of the display. The border color of the bar is a bright magenta color (border: [255, 0, 255] –> means 255 of a possible 255 Red, 0 of a possible 255 Green, and 255 of a possible 255 Blue). The filled portion of the bar as loading progresses is shown as Red.

The text portion defines the color of the text used to indicate which file is being loaded, and the y_center defines the height at which the text will appear.

UserInterface:
  splash_screen: 'loading.png'
  progress_bar:
      x_center: 0.5
      y_center: 0.25
      width: 0.9
      height: 0.10
      border: [255, 0, 255]
      fill: [0,255,0]
  text:
    color: [0,0,128] # no 0/255 Red, 0/255 Green, 128/255 Blue
    y_center: 0.3

Those settings together produce the following loading interface for the user; while the text is clearly cut off, thankfully the user only sees this briefly. Note to self: add a font size option!!

Lampshows

lampshow files can be pre-loaded on asset load. The key is name by which you will refer to the lampshow files later when you attempt to play them, and the file is the filename, assumed to be located in the path ./assets/lampshows/

LampShows:
- key: 'attract_show_1'
  file: 'attract_show_1.lampshow'  
- key: 'attract_show_2'
  file: 'attract_show_2.lampshow'

The above example loads two lampshow files, each of which has a key that is simply the name of the file without the .lampshow extension. You can find more information about the lampshow format, here

Animations (and Images)

Both single images and animations are defined in a section called Animations: The minimal information for an entry is typically a filename (file:) and an alias (key:). Code can then refer to the asset by the given alias.

file: can be a single .gif, .png, .jpg, or .dmd file, or can refer to a numeric range of files using the %d operator. Three simple examples are given below:

Animations:
- key: 'chrome'
  file: 'light_texture.png'  
- key: 'dark_chrome'
  file: 'texture.png'  
- key: 'robot'
  file: 't800.png'  
  x_loc: 50 # move the object 50 dots (not pixels!) in

Notice on the third entry (robot) the file there is an additional parameter x_loc which will move the image over 50 ‘dots’ when it is displayed. (y_loc would move the image down, and negative values can be used to move objects in the opposite direction)

Animations as sequences of images:

Animations:
- key: 't800-war'
  file: 'explosion1_64x48/explosion1_%04d.png'
  frame_time : 2
- key : 'flames'
  file: 'flames/flame_%03d.png'
  frame_time : 3
  repeatAnim : True
  composite_op: 'blacksrc' # make the black in the image transparent  

For example, suppose there are 91 images called explosion1_0000.png through explosion1_0090.png and these images should be treated as consecutive frames of an animation. If all these files are placed in ./assets/dmd/explosion1_64x48/ (just to reduce clutter), specifying the file: 'explosion1_%04d.png' will load a file ./assets/dmd/explosion1_64x48/explosion1_0000.png as the first frame, ./assets/dmd/explosion1_64x48/explosion1_0001.png and so on until the first consecutive file number is not found. You can’t skip numbers in the middle, and you cannot skip the first (0) filename. The %04d means 4 digits, padded with zeros to the left (so 0000, 0001, …). %2d means numbers up to two digits, but without the zero padding, so 1, 2, 3, ..9, 10.

You can also use .mp4 files that contain animations. More documentation about their use is forthcoming.

frame_time: indicates how many times the frame will be shown before it advances to the next frame (note the default system framerate is 30 frames per second, and this can be changed in your config.yaml file). By default, the frame_time is 1.

repeatAnim: indicates whether or not the animation should loop, playing over and over again. If omitted, the default is False. (Notice that True and False are indicated with a leading capital letters, as in Python itself).

compositeOp: 'blacksrc' can be indicated to cause the framework to treat black (0,0,0) pixels as transparent. There is also a 'magentasrc' (255,0,255) and 'greensrc' (0,255,0). For PNG files, per-pixel alpha transparency and whole image alpha transparency is supported, so saving images as PNG files with per-pixel alpha (RGBA/32bpp) eliminates the need for using compositeOp.

Sounds

The Audio: category allows the definition of music and sounds. Use .wav or .ogg (Ogg Vorbis) file formats. MP3 is not recommended at this time.

The following example should be straight forward.

Audio:
  Music:
    - key: 'base-music-bgm'
      file: 'mitch murder - terminator theme.ogg'
      volume: 0.5
    - key: 'sonic'
      file: 'mitch murder - green hill zone theme.ogg'         
  Effects:
    - key: 'ball_saved'
      file: 'AutoFire.ogg'
    - key: 'sling'
      file: 'MENU B_Select.wav'   
    - key: 'target'
      file: 'MENU B_Back.wav'   
    - key: 'target_bank'
      file: 'ALERT_Appear.wav'   
  Voice:
    - key: 'ss_successV'
      file: 'DirectHit1.ogg'
      volume: 0.8
    - key: 'ss_missV'
      file: 'YouMissed2.ogg'
      volume: 0.8

• Music files are expected to be found in ./assets/sound/music
• Effects (sound effects) are expected in ./assets/sound/sfx
• Voice (call-outs) are expected in ./assets/sound/voice

Fonts

True Type and Open Type Fonts (ttf and otf) can be used in the framework. The list of the entries of “HD” fonts should occur under the Font category

Fonts:
    HDFonts:
      + key: 'Tiny7'
        file: 'Oswald-Heavy.ttf'
        size: 14
        # NOTE: if you want to use a system font, instead of file use the following tag style
        # systemName: "consolas"
      + key: 'Font_7x5'
        file: 'Oswald-Heavy.ttf'
        size: 14
      + key: 'score_inactive'
        file: 'Oswald-Light.ttf'
        size: 32

The key defines an alias for the specific type face and the size of the font when rendered. The font may be specified as a filename or a system name, however using systemName will require a user to install a font onto his/her machine before use, which is far more intrusive. If using filename, the path is assumed to be ./assets/fonts/

Font “Styles”

Font styles may be defined within the font category as well, and should appear at the same depth as the HDFonts category

Fonts:
  FontStyles:
  - key: weird
    interior_color: [0,0,128]
    line_width: 1
    line_color: [255,0,128]
  - key: blueish
    interior_color: [0,0,255]
    line_width: 1
    line_color: [0,0,128]
  HDFonts:
    [...omitted for length...]

In the example above there are two styles defined: weird will fill the text rendered in a medium blue ([0,0,128] as R,G,B), has a line_width (aka border) of 1 and the line_color is a reddish purple ([255,0,128]).

SkeletonGame Requirements:

SkeletonGame requires a few conventions in your asset_list, that allow you to tweak/customize certain properties. You must be sure you define a few things:

• A Font or HDFont named: tilt-font-big, tilt-font-small, settings-font-small, high_score_entry_inits, high_score_entry_msg high_score_entry_letters
• TODO: Flesh out the complete list, for here!
• something else that’s vital…