Installing
Ok, first step is to install the whole stuff. First go to the Ambiera homepage and download
IrrEdit, version 1.5. This is the scene editor to create 3d scenes, e.g.
Stunt Marble Racers levels. Extract the .zip file you just downloaded to a place of your choice. You should now start it and play
around, also take a look at the IrrEdit tutorials on ambiera.com.
For further understanding of the physics behind Stunt Marble Racers you could also take a look at tutorial 3 and tutorial 4 of the
Bulletbyte IrrODE Tutorials and the
ODE manual.
Now you need to install all the plugins that you downloaded in the Edit Pack file. Copy IrrOdEdit.dll and plugBULLETBYTEin.dll to the "plugins" subdirectory of the folder you extracted IrrEdit to. Now copy all files found under <EditPack>/Resources to <IrrEdit Folder>/resources. Now you can start IrrEdit and you should see this screen:
Creating a template
The next step is to go to the Tools/Options dialog of IrrEdit and change the working directory to the
directory you installed Stunt Marble Racers in. After changing this setting you have to restart IrrEdit.
The scene files created with IrrEdit will use relative paths to the chosen working directory for all resources
it needs. Now go to the "open file" dialog of IrrEdit and open one of the level files that you got
with Stunt Marble Racers. The level files can be found under <Stunt Marble Racers Folder>/data/levels.
In this folder there is another subfolder for every level. Go to the folder of Training_1 and open the
level.xml file. This is the scene file. Every folder under data/levels that contains a level must have a
file with this name. After you have opened the level file IrrEdit should look like this:
On the left side of the IrrEdit window you see the SceneGraph Explorer. This section shows you which elements your scene has. Now save the file under a differnt subfolder, e.g. <Stunt Marble Racers Folder>/data/levels/test with the name "level.xml". We use this file as a template to create a level of our own. Now go through the scene graph and remove everything except the world, the player1, the player2, the player3, the player4, the checkpoints, the Light and the Preview nodes and it's subtrees. Your scene graph should now look like this:
Now I'll explain this scene graph:- the root node is parent to all nodes in the scene.
- the Startup Skybox is the background skybox.
- the world node contains all objects of the dynamic world, aka "the level"
- the player1 subtree holds a marble and some nodes needed for the physical representation. I'll go into detail later on.
- the player2 subtree holds the marble for player 2
- the player3 subtree holds the marble for player 3
- the player4 subtree holds the marble for player 4
- the checkpoints subtree holds all checkpoints of the level. There must at least be two checkpoints in each level.
- Finally the Preview checkpoint defines the path of the preview camera in the level selection dialog of Stunt Marble Racers.
Details on the "Player" subtrees
In our example you can see four of these nodes, "player1" to "player4". These subtrees define the marbles that are controlled by the players. To have a valid level at least the "player1" subtree must be present (which would make our level single player only).
The "player<number of player> node must be of type CIrrOdeBody. This tells the physics engine of the game that this is a dynamic object that can be moved. It must have a subnode of type Animated Mesh that represents the marble that is actually shown by the graphics engine. The body can also have subnodes of the type CIrrOdeKlangNode which adds sound to the marble. There are two of these nodes in our template, one for the rolling sound and one for the sound of the marble hitting something. Under the Animated Mesh scene node there must be three more nodes. One of type CIrrOdeGeomSphere that tells the physics engine that this is a marble (could be a box as well, although this wouldn't make much sense), one node of type Camera that tells the graphics engine the initial position of the camera and an (optional) CManagedShadow node that adds a shadow to the marble during gameplay.
Details on the "checkpoints" subtrees
The checkpoints subtree contains the checkpoints the marbles must pass for completing a lap. The checkpoints are represented by nodes of type Animated Mesh with three subnodes: one of type CIrrOdeGeomTrimesh, one of type CManagedShadow and one of type RespawnNode. The CIrrOdeGeomTrimesh node tells the phyics engine to use the actual 3D model for collision detection, the CManagedShadow node adds another shadow to the checkpoint and the RespawnNode identifies the node as checkpoint and defines the position of the marble in case a player respawns.
Details on the "preview" subtree
The "Preview" subtree defines the path the preview cam in the level select and hiscore dialog of Stunt Marble Racers should follow. It is a node of type Preview as parent and nodes of type PreviewPoint as children defining the actual path. The preview nodes are shown as pink boxes in the 3D window of IrrEdit and are connected with a pink line showing the camera path.
Modifying the level
OK, in IrrEdit you can modify levels by adding objects. It is not a 3D editor but a scene editor, so you can't create your 3D models here. For that you need other software, e.g. Blender or Wings3D (my favorite). For this example we simply use one of the models that come along with Stunt Marble Racers. Got IrrEdit still running? If not, I hope you saved the template we craeted in the previous chapter.
static environment
Now we need to add a model for our racetrack. Go to the "Edit/Insert" menu and insert an Animated Mesh. In the "File Open" dialog appearing now go to the "<Stunt Marble Racers install directory>/data/levels/race_2 folder, select the oval.3ds file and click the Open button to insert the model. The next thing we do is adjust the position to (0,0,0) and set the scale to (25,25,25). These two value can be set in the "Attributes" tab of the "Properties" section on the left side of the window. Now switch to the material tab. You'll see that there are 5 materials there, but no textures. Now we need to load the textures. Use the "add" button of the "Textures" section to do this. Play around with the materials like explained on the Ambiera homepage. If you are done with this you add a "CIrrOdeGeomTrimesh" node and make it child of the animated mesh. Now make the Animated Mesh child of the world node, otherwise it will have no effect in our physics simulation, i.e. you would simply fall through. Switch to the "Attributes" tab of the "Properties" section. Now we will define the physical surface parameters of our racetrack.
If you take a closer look at the "node specific" part of the list you will see that there are an awful lot of parameters. But don't worry: most of these are the same parameters that can individually be set for all of the 5 materials our Animated Mesh has. First find the "name" value. This is the name of the surface parameters you give to the first material. In our case this is the outside of the wall, so we will simply call it "wall". Now set the checkbox for "mode_bounce" which means that the wall is going to be bouncy. Now enter, let's say, 200 in the "mu" and 0.75 in the "bounce" value fields. This makes sure that there is not enough tracktion to climb up the wall, because the player's not supposed to be there. Now scroll down and enter the name "wall" in the fields "name_mat4" and "name_mat5" now check the "useDefines_mat4" and "useDefines_mat5" fields. This will make quite a lot of the edit fields disappear. From now on for materials 4 and 5 the parameters you enter for material 1 will be used, the first one you gave the name "wall" and the only "wall" where the "useDefined" field is not checked.
There are still surface parameters for 2 materials missing. First let edit the road. In out example the road is material number 3. First we'll assign a name to it. Edit the "name_mat3" value to "road". This is not important in our example, but if you have various textures assigned to different parts of the road you can assign the same parameters this way. The road is not supposed to be bouncy, so we keep the "mode_bounce_mat3" unchecked and just enter 2000 in "mu_mat_3". This is a value that has proven to be OK for the road. The last material we have is the grass. We'll make it bouncy by checking the "mode_bounce_mat2" edit and enter "0.75" in "bounce_mat2". Now for the special part: we don't want the marble to reach high velocity on the grass, so we have to check the "damps_mat2" field. Now four new edit fields appear. First we'll assign a "mu" of "200" to the material. Next we put both "linearDamping_mat2" and "angularDamping_mat2" to "0.005". This will give additional linear and angular damping of 0.5 percent to an object moving on the grass, e.g. the marbles. Next we enter "15" into the "maxLinearVel_mat2" and "6" into the "maxAngularVel_mat2" fields. After this is done two new values appear. These new values, "maxLVelDamping" and "maxAVelDamping" define an additional damping that is applied to any object moving on our grass material if it's velocity exceeds the maximum values of 15 and 6. Let's assign "0.01" to both of these values. One last thing to do: you can see one node of type "RespawnNode" as child of every checkpoint. This node identifies it's parent as a checkpoint, and the attribute "Num" defines the order of the checkpoints. Step through all of the "RespawnNodes" and make sure these values are correct. Checkpoints with a lower "Num" values must be passed before checkpoints with a higher one. Now you should move the checkpoints to appropriate positions on the racetrack. Last thing to do for this step is to move the marble nodes ("player1" and "player2") to their starting positions.
Now the level is ready for a first test play. Start Stunt Marble Racers, go to the "single race" dialog and search for the new track. As we have stored it in a subdirectory called "test" in the "<Stunt Marble Racers Folder>/data/levels" folder it is shown as "test" on the bottom of the list.
preview path
The next step we'll do is add a preview path for the level preview in the "single race" and "hiscore" dialogs. As we haven't removed the subtree with the parent of type "Preview" we just delete all of it's children except for one. This node will be the start of the camera's path, so move it to a position you like. Now clone this node and move it to the next appropriate position for the preview path. Redo this step until you have a preview that you think is good. You will notice that these children of type "PreviewPoint" are connected with a line. This is an approximation of the path the camera will go. You should make sure that two following nodes of the path are not located too close to each other, because the preview cam might behave strange otherwise. When you are finished with yout path start Stunt Marble Racers again and watch the preview. As said before the path shown in IrrEdit is just an approximation, so you should watch one lap of preview in order to see if it's OK. Now a simple level is finished.
dynamic environment
But we don't just want a simple level, do we? We will add some dynamic content as well, I would say let's add some bales of straw and a wall connected to the environment using a hinge. First we'll do the straw. Insert an "Animated Mesh". Use the "box.3ds" file located in "data/levels/objects". Use "straw.jpg" located in "data/levels/race_5" as texture for it's only material (I know I should clean some things up in the directory structure ;) ). Now add a "CIrrOdeBody" node. Make the "Animated Mesh" child of this node. Now we need to tell our physics engine of the shape of our new object, so we insert a node of type "CIrrOdeGeomBox" and make it child of the Animated Mesh. Now we take the Animated Mesh and make it child of the world node to add it to the physics simulation. Maybe we should resize our bale of straw, set the "Scale" attribute to (2,2,2). Now we have to define the surface parameters of our bale. Let's say we give "500" as "mu" value, make it bouncy with "0.5" (don't forget to check the "mode_bounce" flag). In order to make the bale a bit nicer we add a node of type "CManagedShadow" as child of our Animated Mesh. Set the "shadow level" attribute to "3". This way the shadow will only be drawn if the player has selected full shadows in Stunt Marble Racers' options menu. For some sound we add a node of type "CIrrOdeKlangNode" as child of our object's body node. Set the filename to "data/sounds/wall.ogg", the min distance to "15" and the "max distance" to 100. We want the sound to be played when the object hits something, so we check the "CollisionSound" attribute and enter "3" as minimum force and "50" as maximum force. Now move the bale of straw to an appropriate position, start Stunt Marble Racers and play around a little bit. We can create a wall of bales of straw by simply cloning the body of our object. Be sure that you move the body, not one of it's children to the new position.
One last dynamic thing we add is a hatch that swings open when a player hits it. For this we make another clone of one of the bales. Move the CIrrOdeBody node to another position on the road and change the scale of the Animated Mesh ((0.25, 5, 10) seems to be an idea). Now add a node of type "CIrrOdeJointHinge" to the scene. Make it child of the "CIrrOdeBody" node. Move the hinge up a little bit and you're done. You should just check the axis parameter (there is a thin line coming out from the CIrrOdeJointHinge node that shows the axis), and maybe modify the Hi- and LoStop. Play around a little bit with it, and refer to the ODE manual for detailed information about the parameters.
the "info.xml" file
Every level should have a file called "info.xml" with additional information. This file must be located in the same folder as the "level.xml" file containing the actual level. Here is a demo "info.xml" file:
<levelInfo>
<name>EditPack Demo Level</name>
<pos>05</pos>
<info>
This is the demo level for the Stunt Marble Racers edit pack. Just modify
this level with your own ideas and you're ready to go.
</info>
</levelInfo>
The <levelInfo> node is the root node of the file. It must (or should) have three child nodes. <name> defines the level's name
that is displayed in the level selection lists, <pos> defines the position the level should have in these lists and finally
<info> can provide some more information about the level. Be sure to keep the text in this node short enough for the dialogs
to display the information, as these GUI elements do not scroll. If this "info.xml" file is missing the name of the subdirectory
containing the level file will be used as name in the lists, and it will be on the last position of the list.