This page is a stub for the Iron Horse documentation. Our game engine, Iron Horse, is not open source (maybe not yet). So, if you are here, chances are this page won’t be of any interest to you.

1. Integrating a new scene

Add a player character to your scene

  • Create a 3D object (by convention, use an ico-sphere) used to represent the PC.
  • Match the object name to the PC name (CLARIFY)
  • Also match the mesh name to the PC name
  • Move the PC to layer 3.
Now we need to configure physics for our character:
  • In information bar (menu bar at top of blender window), switch from ‘Blender Render’ (may be ‘Cycles Render’) to ‘Blender game’
  • Select the PC object
  • Go to physics tab in properties
  • Set physics type to ‘Dynamic’.
  • Set mass to 50 (kg) or something meaningful.
  • Now re-set physics type to ‘Character’ and check the box reading ‘Actor’

Add the scene file to your XCode project.

The path to a scene file should look like this:

../2.5x/scenes/PrSceneName.blend

  • The 2.5x folder can be located anywhere. “2.5x” is used to let the exporter know that Blender 2.5x or later (typically, 2.6x) is used to process the file.
  • The scenes and assets subfolders are used to distinguish scenes from assets, as these are processed in a different way.
  • Pr is a 2 letter prefix used to identify some of the resources used by the runtime and should be consistent for all scenes that belong to the same game.
  • Scene is the name of the scene you have created.
Provide a setup class for the PC character
  • This must be added to the main XCode project and defines some of the characteristics of the PC character (e.g., speed). As an example, see SpKagamiSetup.

Advanced operations

Force assets to rebuild

Assets should be re-exported whenever the underlying blend file has changed. However forcing a rebuild may be necessary under some circumstances.

Wherever assets are found, a build folder with a file named timestamps.txt will be created. To force all assets to rebuild, search for ‘timestamps.txt’ and delete it wherever it occurs, then rebuild. If the problem persists, you can try deleting the content of such ‘build’ folders.

Caveats

Blender executable not found

The blender exe should be under a directory with following path:

/Applications/blender-2.6x

Where ‘x‘ is the blender minor version number (single digit). The latest available version will be used. So you may have both blender 2.63 and blender.2.65 in your Applications directory, like this:

/Applications/blender-2.63
/Applications/blender-2.65

Then blender 2.65 would be used to export files.

Asset read errors

  • File format may have changed without version number being updated. If so, all assets need rebuilding.

Asset not found

  • If you renamed an asset but only changed capitalisation, the asset may not be found. In this case, delete the content of the relevant build folder and rebuild.
  • A typical case is when the asset expected to act as ‘PC’ (player character) was not found (see above section, Add a player character to your scene).
    This error may occur for several reasons…
    • Because no PC asset was added to the XCode project.
    • Because no object was added to the scene to indicate the location of the PC.
    • Because the PC object in the scene is not on layer 2.
Asset type errors
  • Asset type errors will occur when same name datablocks are defined in the blender file. For example, a material may have the same name as a 3D object, or an object may have same name as the world node.
    This is a problem because the exporter may only export a single file per asset name, and the engine runtime retrieves data-blocks by name.
    This is a bug.
    For now, make sure all your assets have distinct names.
Actor setup class not found
  • This error will occur if no setup class matching the actor type was provided.
  • A more common case is when the actor mesh name does not match the actor’s type. For example, a ‘Troll’ actor should use a mesh named ‘Troll’.
    If you leave the mesh name as something like Icosphere.001 or similar, the actor setup class name will be derived from this, causing an error.

Output looks incorrect

Meshes with more than 65536 vertices may not display correctly.

Error upon trying to move the PC

Likely, physics are incorrectly setup, e.g. you forgot to define the actor’s mass.