Mod structure tutorial

Mirrored from here structure asci code doesn't work here, please press edit to see it

---

1. Introduction

There are many people out there, who like to customize the game. But most of them don't know how to do it properly. In this HOWTO I will try to give some instructions how to create a mod in a structured way and then put it into a package, that can be used by other people.

2. Warsow directories

Let's have a look at warsows folder structures.

The first folder we know is the warsow installation directory. It looks like this:

   warsow-install-directory
   |
   |-- libs
   |
   |-- docs
   |
   |-- basewsw
   |   |
   |   |-- ....
   |   |-- data0_10.pk3
   |    -- ....
   |
    -- (binaries)

We notice the big file data0_10.pk3 in the basewsw directory. We will need it later.

Warsow creates another directory, when it is first launched. We call it the warsow-user directory.

This directory is located at

• on windows: %APPDATA%/Warsow 1.0
• on unix: $HOME/.warsow-1.0

It looks like this:

   warsow-user-directory
   |
    -- basewsw

Notice: warsow-user-directory will override files from warsow-install-directory. This means: If a file exists in both directories, warsow will use the one from the warsow-user-directory.

We don't want to touch the warsow install directory, so we use the user directory.

We also don't want to mess with the basewsw directory, because we don't want to break anything, when we just want to play the game.

3. Make a mod

So before we start modding, we create a new directory next to the basewsw directory and call it mymod-dev. Now we extract data0_10.pk3 to mymod-dev

The folder structure now looks like this:

   warsow-user-directory
   |
   |-- basewsw
   |   |
   |    -- ....
   |
    -- mymod-dev
       |
       |-- fonts
       |-- gfx
       |-- huds
       |-- levelshots
       |-- minimaps
       |-- models
       |-- navigation
       |-- profiles
       |-- progs
       |-- scripts
       |-- sounds
       |-- textures
       |-- ui
       |-- video

Each of these subdirectories contains stuff, that can be modified.

Now we can start modding. [do lots of laborious stuff here] Let's say we have changed some decals. Now we want to see how this looks ingame. We have to tell warsow to use the mymod-dev directory. We do this by typing this to the console:

> fs_game mymod-dev 

The contents in the mymod-dev directory will override those in the basewsw directory.

4. Package the mod

When we have finished our mod, we want to use it in real games or share it with other people. For that purpose we will create a pk3-package.

First we create another directory and call it mymod. Then we copy ONLY the files we changed and we KEEP the folder structure.

• If we are on windows, we need to copy everything over and then delete what we didn't change.

• If we are on unix, we can use cp --parents like this:

> [mymod-dev]$ cp --parents gfx/decals/* ../mymod

The structure should now look like this:

   warsow-user-directory
   |
   |-- basewsw
   |   |
   |    -- ....
   |
   |-- mymod-dev
   |   |
   |    -- ....
   |
    -- mymod
       |
        -- gfx
           |
            -- decals
               |
               |-- d_blade_hit.jpg
               |-- d_bullet_hit.jpg
               |-- d_electrobolt_hit.tga
               |-- d_explode_hit_2_depth.tga
               |-- d_explode_hit_2_norm.tga
               |-- d_explode_hit_2.tga
               |-- d_explode_hit.jpg
               |-- d_instagun_hit.tga
               |-- d_plasma_hit.tga
                -- shadow.tga

We use our favorite compression tool and put all the files from the mymod directory in it. Then we let it create a ZIP file. It is important that we have a zip archive, because warsow can only read this format. Now we change the file extension from zip to pk3.

IMPORTANT: the filename MUST be higher than data0_10.pk3 (not start with a, b, c or d).

The filename SHOULD be like: mod_(modname)_(version).pk3 where (version) is 000 for our first release, 001 for the second and so on. In our case we name it mod_mymod_000.pk3

We copy our package to the basewsw folder and see if everything is correct in game. If yes, we are ready to release our mod to the public!

5. Clean up

Let's have a look at our directory now:

   warsow-user-directory
   |
   |-- basewsw
   |   |
   |   |-- ....
   |   |-- mod_mymod_000.pk3
   |    -- ....
   |
   |-- mymod-dev
   |   |
   |   |-- fonts
   |   |-- gfx*
   |   |   |
   |   |    -- decals*
   |   |
   |   |-- huds
   |   |-- levelshots
   |   |-- minimaps
   |   |-- models
   |   |-- navigation
   |   |-- profiles
   |   |-- progs
   |   |-- scripts
   |   |-- sounds
   |   |-- textures
   |   |-- ui
   |    -- video
   |
    -- mymod
       |
       |-- mod_mymod_000.pk3
       |
        -- gfx
           |
            -- decals
               |
               |-- d_blade_hit.jpg
               |-- d_bullet_hit.jpg
               |-- d_electrobolt_hit.tga
               |-- d_explode_hit_2_depth.tga
               |-- d_explode_hit_2_norm.tga
               |-- d_explode_hit_2.tga
               |-- d_explode_hit.jpg
               |-- d_instagun_hit.tga
               |-- d_plasma_hit.tga
                -- shadow.tga

The only thing we can delete definitely is the mymod/gfx directory. We also want to save our package mymod/mod_mymod_000.pk3. We can either leave it where it is or move it to another place and delete the mymod directory. Now we have to make some decisions, which of the other files we want to keep.

• Do we want to actually USE our mod? If no, delete basewsw/mod_mymod_000.pk3.

• Do we want to extend our mod? If no, delete everything in mymod-dev that was not changed.

• Do we want to develop our mod further? If no, delete the mymod-dev directory.