Difference between revisions of "Terrain Creation Guide"

Revision as of 10:49, 5 September 2022

Background and Prerequisites

This guide will explain how to create your own custom terrains which you can then play just as you would other randomly-generated terrains such as Forest, Cheese etc. See the wkTerrainSync page for more info on how to play additional terrains. wkTerrainSync is a module that allows you to play additional terrains offline and in online multiplayer.

A terrain comprises the background elements (the sky colour gradient, the mountains and falling debris), a repeating land texture, a soil texture (revealed when terrain is destroyed), the grass textures (for the upper and lower parts of the terrain), the bridge (comprising a left, middle and right part) and up to 32 custom objects to be placed randomly. These objects can be configured to appear on the floor, ceiling or side of the terrain.

Terrains are stored under the DATA\Level folder of your Worms install directory. Each terrain has its own folder containing 2 files: 'Level.dir' and 'TEXT.img'.

'TEXT.img' is a small icon representing the terrain in the in-game land generator.

'Level.dir' is an archive file (similar to a zip) that contains all of the terrain images and config files.

The image files in Level.dir are in two formats that you can't edit directly; .IMG files for images, .SPR files for animated sprites. .SPR files are accompanied by a .SPD text file containing parameters for the .SPR file (number of frames, frame width, frame height etc).

The WA Directory Editor utility (SpriteEditor.exe) is able to take your image assets (in .BMP [Indexed palette, OS/2] format), convert them to .IMG/.SPR and then produce a Level.dir file usable in the game. It is also able to extract assets from existing level.dir files although the program is a bit buggy and some files may not extract.

Sprite Editor converts your BMP files to .IMG/.SPR files based on the filename. EG, 'soil.img.bmp' will convert to the IMG file 'soil.img'. 'debris.spr.bmp' and 'debris.spr.spd' will convert to the .SPR file 'debris.spr'.

Download and extract these terrain guide files: https://www.tus-wa.com/files/file-2229 This has an 'EXAMPLE TERRAIN' folder containing examples of the core assets required for all terrains and 4 example custom objects. It also contains the standalone SpriteEditor.exe for convenience or you can download it from the link above.

Check out the EasyTerrain Utility which allows you to use a template image containing all of your image assets to automatically create the files necessary for Sprite Editor to create a terrain.

Core Files (required)

NOTE: For convenience, there's a '_UPDATE INDEX AND LEVEL.DIR FILES.bat' script in the EXAMPLE TERRAIN folder. When all of your files have been created, run this to automatically build the 'index.txt' and 'Level.dir.txt' before compiling the final Level.dir file.

Custom Object Files

You need at least 1 object for the terrain to work and can have a maximum of 32 objects (excluding the core objects above).

There are 3 types of object placement in the game; floor, ceiling and side.

Your objects can have any file name but the name must end with '.img.bmp' (including file extension). EG, toaster.img.bmp. If making a lot of objects it's a good idea to name them based on object type, EG, 'obj-floor-toaster.img.bmp', 'obj-ceiling-knife.img.bmp', 'obj-side-fork.img.bmp'.

Each custom object you create must be accompanied by an .INF file. EG, the object 'obj-floor-toaster.img.bmp' would have the .INF file 'obj-floor-toaster.inf'

The INF file contains a list of numbers representing internal parameters that describe the properties of your object, EG:

5
0
0
1
1
3

In order, this is what the values represent for each line :

Custom object dimensions can vary but the height and width values must be divisible by 4 if you wish to use .IMG compression in Sprite Editor (recommended as this reduces file size significantly). If dimensions aren't divisible by 4 and you have IMG compression enabled, the object will appear corrupt in-game likely due to a bug in Sprite Editor.

All images must be saved in BMP (Indexed palette, OS/2) format for SpriteEditor to convert, or you'll get an error.

Debris

The background falling debris (debris.spr) is a static image file containing all animation frames stacked vertically. The game renders this many times in the background to create the debris effect and it animates each instance of debris at a slightly different frame rate. This doesn't seem to be configurable although you can control the overall speed of your animation by lengthening or shortening the number of frames in your animation.

You can use ffmpeg to extract all frames from an animation/movie file (such as a .gif or .mp4) and then use ImageMagick to stack them vertically to create your image file. Example commands below :

- ffmpeg.exe -i "input-animation.mp4" img%04d.png  [extracts all frames to .png files]
- magick.exe img*.png -append animation.png  [merges all frames vertically, outputting to 'animation.png']

Palette

Worms uses indexed palettes for all assets. The first colour (which can be any colour) represents transparency and must be the same for all assets used.

The game allows for a palette of up to 112 usable colours (excluding transparency) to be shared by the sky gradient, the core objects and custom objects. Your terrain won't load if it goes beyond 112 colours.

The game engine will manage the palettes found in your terrain objects. So you could have an object with a 10 colour palette, another with 23 etc and the game will aggregate and de-duplicate the colours. You could also index your project down to the optimum palette for all objects and have the same 113 colour palette (112 usable) for everything.

For stock Team 17 terrains, the sky 'gradient.img.bmp' uses a 17 colour palette (16 usable). The remaining objects use the same palette of 97 colours (96 usable). Whilst this seems to indicate that the sky palette is separate, it is in fact just part of the shared 112 colours allowed for terrains by the game. More or less colours could be used for the sky, and the colours used by the sky can be used in terrain objects.

If you intend to generate PNG's from your custom terrain, it is recommended to ensure that your foreground terrain textures and objects don't take up the full 112 colours; it's better to use around 100 maximum and dedicate the rest of the colours to your background elements. This is because with PNG's, the sky gradient and background are changed for stock versions which need more colours. This allows the game to draw the background sky gradient more smoothly because you have left room for them in the palette.

Creating the Level.dir File

When all of your BMP objects are saved, and all .INF and .SPD files have been created/updated, update the 'Index.txt' and 'Level.dir.txt' files either manually or by running the script.

You're then ready to create the final Level.dir file :

- Open SpriteEditor.exe
- UNCHECK the "Compress .SPR files" and "Opaque .IMGs" options (they are checked by default).
- CHECK the "Recreate all .SPR/.IMGs" option (a precaution to ensure any existing files are re-created)
- Select "Reconstruct from log"
- Select your 'Level.dir.txt' file.
- The utility will convert all of your BMP assets into IMG's and .SPR's
- Select "Save-As" and save the file as Level.dir

Creating the Terrain Icon (TEXT.img)

The TEXT.img file is the icon that accompanies your Level.dir file. It must be 64 x 64 and 17 colours (the first colour will be used for transparency). Be sure it does have a 17 colour palette, even if the image uses less colours, otherwise crashes may occur on the land generator screen.

- Create your icon image and save it somewhere on your computer as "TEXT.img.bmp"
- In the same location, create a text file called "icon.txt" and edit it to contain only the following text on the top line: TEXT.img
- Open SpriteEditor.exe 
- UNCHECK the "Compress .SPR files" and "Opaque .IMGs" options (they are checked by default).
- Select "Reconstruct from log"
- Open the "icon.txt" file you created. This will immediately create the corresponding TEXT.img file. 
- Close SpriteEditor

You now have the Level.dir and TEXT.img files for your terrain. Create a subfolder within 'DATA\Level' giving it the name of your terrain and copy over the 2 files. You can now play the terrain.

Extracting Assets from an existing Level.dir file

SpriteEditor.exe can be used to extract assets from existing level.dir files, including the default terrains created by Team 17.

- Open SpriteEditor.exe
- Select Open and navigate to a Level.dir file
- Select 'Extract, convert, log' and select a folder to extract the contents to.
- You may also select individual assets to extract.
- The utility is buggy/incomplete, you may have problems extracting from level.dir's that the utility creates. It seems to extract fine from the default level.dir files created by Team 17.

Custom Terrain Water Colour

The wkTerrainSync module supports loading an alternate 'Water.dir' file for your terrain allowing you to customise the water colour.

Use the Water Colour Editor v2 utility to create the new 'Water.dir' file for your terrain. This is a modified version of Water_color_editor that supports the smoother water animation introduced in 3.8. Once you're happy with how the water looks in the utility, simply save the new 'Water.dir' file inside your terrain directory (alongside the Level.dir and TEXT.img files).

Tips and Tutorials

For better playability, ensure the terrain texture (text.img) can be easily distinguished from the background (back.spr) and the soil texture (soil.img). Also check the edge colour held in 'grass.img' that is revealed as terrain and objects are damaged. This needs to be distinguishable from the background and soil, particularly as the terrain gets destroyed leaving tiny bits of land, sometimes individual pixels.

If you find an object always appears too low (embedded) in the terrain, try increasing the height of the object canvas slightly (not the object itself), adding more transparency at the bottom of the image. By increasing further you can make objects appear off the ground.

If using Photoshop to create the sky gradient, when indexing down use the 'Pattern' dither rather than 'Diffusion' dither, it produces smoother results.

It's generally best to avoid text on objects. The game randomly flips objects horizontally so there's a 50/50 chance of it being readable.

VIDEO: Photoshop: How to reduce the colours used in an object without losing too much quality, in this case from 63 to 25. Shows how you can specify which colours are included in the reduced palette for more control.

VIDEO: How to index down all image assets in Photoshop to achieve the final 97-colour palette. Force the first colour to black (or whichever transparency colour you have chosen) then you can force additional colours for objects you think need more palette space.

VIDEO: How to index individual objects against the final (saved) palette, then set the background to the transparency colour (black in this case) and make any other adjustments to the object before saving out to BMP

VIDEO: How to create a sky gradient in Photoshop and index down to 17 colours.

VIDEO: The new Pattern Preview feature in Photoshop can be used to easily create seamless (repeating) terrain textures.

VIDEO: For terrains with lots of objects/colours, the Match Colour feature in Photoshop is useful to help keep all objects within the 97 colour limit

VIDEO: How to index your terrain icon image in Photoshop and create the Icon.img with Sprite Editor