Project Organization

Directory Structure

After you create and build a new Plasmacore project you will have the following directory structure:

 

  bin/  -

Contains native layer executables that are copied to build product folders as appropriate.
  build/  - Contains automatically generated, intermediate build files.
  build.xml  - The ANT system build file that builds the projects.  Type "ant" by itself to see a menu of all the options.
  data/  - Stores general data files for your game, including "settings.txt" that the system uses to determine display resolution.  Any files you place in here will be bundled with your game.  You may create additional subdirectories as desired.
  dist_mac  - Contains the distributable build products for a Mac build.
  dist_windows  - Contains the distributable build products for a Windows build.
  images/  - Any PNG and JPG images you place here will be bundled with your game.  You may create additional subdirectories as desired.
  include/  - Contains C++ includes necessary when cross-compiling a Plasmacore Project into C++ (currently only supported on iPhone).  Even when cross-compiling you will not need to work directly with this folder.
  project_iphone/  - Contains the Xcode (Mac only) project for Plasmacore iPhone builds.
  sounds/
sounds/iphone
sounds/windows
sounds/mac		  - Any sounds and music files you place here will be bundled with your game (exception: iPhone, where sound files must be individually included as project resources).  See Resources, below, for more info.  You may create additional subdirectories as desired, although these are ignored in the iPhone build.
  src/  - Contains the Slag source code for your Plasmacore game.  After creating a starter project, src/ will contain "game.slag" (the primary application), "plasmacore.slag" (containing the Slag-side code that implements Plasmacore), and "standard.slag" (the Slag language standard library).
  upgrade/  - Whenever you want to upgrade project "game_x" to a new version, place the "new_project" folder into "game_x/upgrade" (so that there exists "game_x/upgrade/new_project/..." and run "ant" in the "game_x" base folder to upgrade.

Resources

In general Plasmacore resources must be placed in the appropriate folder.  They are zipped up, bundled with the game distributable, and loaded in different ways depending on the platform.

Images

  • Place all PNG and JPG images in the images/ directory of your project.
  • Nested subdirectories are allowed.
  • Partial filepath matching is used when loading.  If your image is "images/backgrounds/bg1.png", you can create an Image(...) object in Plasmacore with the full name or any of the following: "bg1", "bg1.png", "backgrounds/bg1", "backgrounds/bg1.png", etc.
  • Filenames are case sensitive in Plasmacore - "bg1.png" is different than "BG1.png".
  • To have transparent parts in your images you must edit them that way and same them in PNG format.  In Photoshop if you paste an image onto a new layer and then erase parts of it, those parts become transparent when you save it.
  • We use Photoshop for our image editing; GIMP is a free alternative.

 

Sounds

  • Place the sound and music files that are common for all platforms into the sounds/ directory of your project.  A file "sounds/explosion.wav" may be loaded as Sound("sounds/explosion.wav") or just Sound("explosion").
  • Place all the windows-specific sound files into the sounds/windows directory.  You do not include the "windows" part of the path at runtime, so "sounds/windows/music/level1.ogg" would be loaded as Sound("sounds/music/level1.ogg") or just Sound("level1").  The same applies to specific Mac ("sounds/mac/") and iPhone ("sounds/iphone") sounds.
  • When building for iPhone you must add each sound you're using as a resource to the Xcode project.
  • Nested subdirectories are allowed (and ignored on iPhone).
  • Partial filepath matching is used when loading as with images.
  • Filenames are case sensitive - "music1.mp3" is different than "Music1.mp3".
  • For Windows builds, use OGG or MP3 for music and WAV for sound effects.
  • For Mac use any combination of MP3, M4A, and WAV.
  • For iPhone use M4A for music (larger than MP3 but uses less processor time to decode) and WAV files for sound effects.  Consider using 22,050 Hz, mono music for M4A (less memory, less time spent processing than a 44,100 Hz stereo file).  WAV files must be 30 seconds or less.
  • A command line tool that will convert files into M4A format is described here.  For other audio editing tasks take a look at Audacity.
  • For game sound effects we recommend soundsnap.com.

 

Data

  • Data files besides images and sounds should be placed in the data/ folder of your project.
  • Partial filepath matching is used when loading, as with images and sounds.
  • Filenames are case sensitive.
  • Used a DataFile object to load a data file.
  • The data/ directory contains a file called settings.txt.  Read more below.

 

Settings

Edit your project's data/settings.txt file to change project settings.  Right now only one setting is supported:

display_size 1024 768
Sets the display resolution of your game to 1024x768 (or whatever resolution you desire). Currently you cannot programmatically choose or change resolution. Games on iPhone are hard-coded to use 320x480.