Start A Mod

Directory

The first thing to do when first creating a mod is to create the directory for the mod to sit under. This directory should be created in the globalmods directory (see the appropriate section in Introduction - Modding Basics).

The directory you create will identify all of your files as belonging to your mod, so make it a meaningful name. It is also important to make sure that it is a unique name so have a look at the Current Mods section to ensure that you have not stolen the name of an existing mod.

Under this directory you should then create a data directory that will contain all of the data files for your mod.

Once your directories are created you should have a directory structure like:-

 data                     - Scorched3D data directory
   |
   +-> globalmods         - Mod root directory
          |
          +-> yourmod     - Your mod**
                 |
                 +->data  - Your mod's data directory

 ** change yourmod to be the name of your mod.

Mod Info

The next step in creating a mod is to write the modinfo.xml file. This file contains the name and description for your mod, an icon for your mod and information on which versions of Scorched3D your mod is compatible with. It may also optionaly contain information about how to start single player games for your mod offline (more on this later).

Each mod must contain a modinfo.xml file. Without this file Scorched3D will ignore the mod when it starts up.

The modinfo.xml file should be placed in your mod's data directory. Here is an example of the modinfo.xml file contents, descriptions are in yellow:

<modinfo>
	<main>
		<shortdescription>Your Short Description Here</shortdescription>
		* A short description of your mod
		<description>Your Long Description Here</description>
		* A Long description of your mod
		<icon>data/myicon.bmp</icon> 
		* An icon for your mod, this file should exist in your mod data directory
		<url>http://www.yoururl.com</url>
		* A URL of your mod's home page
		<protocolversion>dj</protocolversion>
		* The Scorched3D version your mod is compatible with 
	</main>
</modinfo>

The icon section of the modinfo.xml file allows you to specify the name of the icon for your mod. This icon must be placed in your mod's data directory and should be a bmp file 32x32 pixels in size 24bit color.

Once your modinfo.xml and icon files are created you should have a directory structure like:-

 data                                - Scorched3D data directory
   |
   +-> globalmods                    - Mod root directory
          |
          +-> yourmod                - Your mod
                 |
                 +->data             - Your mod's data directory
                     |
                     +->modinfo.xml  - Your modinfo.xml file
                     |
                     +->myicon.bmp   - Your icon

Scorched3D Version

The version of Scorched3D is identified by two parts a game version and a protocol version. When you run Scorched3D you will see a version in the title bar, for example Version 41.1 (dj). The version number after the word Version is the game version (in this case 41.1). The version word in the brackets is the protocol version (in this case dj).

The game version is a user readable identifier that allows people that play the game to know what version of the game they are playing, and if they need to update the game.

The protocol version is a machine readable identifier that tells the Scorched3D client and server which versions of the game are compatible with each other. Since the protocol version also changes when the format of any Scorched3D files changes it is also used as the identifier to determine which mods are compatible with a given version of Scorched3D.

When creating your modinfo.xml file you must make sure that it has the correct Scorched3D protocol version in the <protocolversion> section. The <protocolversion> must match the protocol version of the Scorched3D system you are using.

Any mods that have an older protocol version will be ignored and will not be loaded.

Single Player Menu Items

If you want people to be able to play single player games of your mod you need to add another section to the modinfo.xml file. Each <game> section in the modinfo.xml file specfies one type of single player game the user will be able to select, descriptions are in yellow:

 <modinfo>

       ....

 	<game>
 		<shortdescription>Start an target practice game.</shortdescription>
		* A short description of your single player option
 		<description>Play a practice level against targets that don't fire back.</description>
		* A long description of your single player option
 		<icon>data/target.bmp</icon>
		* An icon for your single player game (see mod <icon> for more details)
 		<gamefile>data/singletarget.xml</gamefile>
		* Points to the Scorched3D game settings file that specifies all of the settings for this game.
 	</game>
 <modinfo>

When running the Scorched3D client you should now be able to choose your mod for a single player game. Each of the <game> sections you have defined in your modinfo.xml file will appear as an option for you to choose. Choosing an option will run Scorched3D with the settings defined in the <gamefile> section.

The Mod Files

You now have your mod setup and can start adding content to it. Content is made via adding files into your mod's data directory. However, in order to change or add anything you're going to have to know where it is. A brief rundown of the main modding files/directories and what they contain is as follows:

 data                     - Scorched3D data directory
   |
   +-> globalmods         - Mod root directory
          |
          +-> yourmod     - Your mod**
                 |
                 +->data  - Your mod's data directory
                      +
                      |
          modinfo.xml - Defines menu icons/text for the mod and game version it runs on
                      |
          accessories.xml - File containing all the item/weapons for the game
                      |
          ainames.txt - Contains the names for the bots 
                      |
          landscapes.xml - File containing basic landscape data
                      |
          playernames.txt - Initial names of players (when they first log on)
                      |
          singletarget.xml - Default target practice game settings
                      |
          singleeasy.xml - Default easy difficulty single player game settings
                      |
          singlenormal.xml - Default normal difficulty single player game settings
                      |
          singlehard.xml - Default hard difficulty single player game settings
                      |
          tankais.xml - File containing parameters for the ai players
                      |
          tanks.xml - What tank models to use and their projectiles
                      |
          tanktypes.xml - Defines custom attributes for tanks if desired
                      |
          textureset.xml - Definitions for the textures used in explosion and napalm animations
                      |
          windows.xml - Definitions for all the GUI windows in game
                      |
                      +-->meshes/* - Boid models used by the mod
                      |
                      +-->textures/* - All weapon icons, explosion textures or landscape textures used by the mod
                      |
                      +-->wav/* - All custom sounds used by the mod
                      |
                      +-->windows/* - GUI windows and other menu images
                      |
                      +-->accessories/* - All models used by the mod besides tanks and boids
                      |
                      +-->landscapes/* - All the heightmaps, pictures and xml files for landscapes
                                |
                          ambientsound*.xml - Stores ambient sound groupings
                                |
                          boids*.xml - Definitions for boids (birds and flying objects)
                                | 
                          defn*.xml - Info regarding the shape of a landscape
                                |
                          events*.xml - Controls events which occur on the landscapes
                                |
                          place*.xml - Info regarding placement of the landscape objects
                                |
                          tex*.xml - Defines all the texture layouts that are used by the landscapes

For files with no documentation (yes I am getting to it!!) it is possible to look at the engine files in the data directory (scorched3d/data) or in the apoc mod (scorched3d/data/globalmods/apoc) for examples.

Testing Your Mod

After you've constructed your mod, it's time to test it.

To test your mod, run Scorched 3D and choose "Local Game", then choose "Mod: Custom" and choose your mod in the "Mod Settings" drop-down list. If your mod is not in this list then either you have not made a modinfo.xml file in the correct location or it's contents are incorrect.

After you've finalized your mod and become confident in it, you can start a LAN or online server with it. You will need to enable the "Mod Download Speed" setting on the server (e.g. 10000) to allow people to download the mod when they connect, or they will not be able to play.