View source for Terrain Creation Guide

{{ParentArticle|[[Guides, FAQs, and ReadMes]] or [[Missions]]}}

== 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 essentially a single image containing the animation frames stacked vertically along with some parameter information which is supplied by an accompanying .SPD text file (number of frames, frame width, frame height etc). 

The [[WA directory editor|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 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 contains the "Cosmic" terrain including all asset files. It also includes the "_back.spr" and "back2.spr" files supported by wkTerrainSync for dual layer, larger background support. 

Check out the [https://github.com/nizikawa-worms/EasyTerrain 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) ==

{| class="wikitable" width="75%" border="1" cellpadding="2" cellspacing="0" style="margin-top: 0.5em;"
|-
! File Name
! Info
|-
| text.img || The main texture of your terrain. Dimensions: 256 x 256
|-
| soil.img || The soil texture revealed when land is destroyed.  Dimensions: 256 x 256 
|-
| back.spr || The background mountains image.  Dimensions: 640 x 160. Despite being an .SPR file, this is a single image and the background cannot be animated.
|-
| back.spd || The sprite parameters file required to create back.spr. Edit width/height parameters as necessary. 
|-
| bridge.img || The flat part of the bridge. Dimensions: 64 pixels wide, variable height.
|-
| bridge-l.img || The left part of the bridge. Dimensions: 64 pixels wide, variable height.
|-
| bridge-r.img || The right part of the bridge. Dimensions: 64 pixels wide, variable height.
|-
| debris.spr || This is the animated falling debris. It's a single image containing all of the animation frames stacked vertically. Dimensions vary depending on content.
|-
| debris.spd || This is a parameters text file required to create the debris.spr file.  Adjust frame width, height, number of frames and animation flags accordingly. See the Debris section below for info on the parameters.
|-
| gradient.img || The sky gradient image. Dimensions: 8 x 916. Stock terrains use 16 colours for this but more or less can be used.
|-
| grass.img || Contains the top and bottom terrain grass and the edge colour you see when objects and land are destroyed. Open the example grass.img.bmp to see how this is divided up. Width is 136 pixels. Height is variable (typically around 16 pixels in stock terrains).
|-
| Index.txt || A list of the custom object filenames to be used on the terrain (excluding the above assets). No file extensions. Maximum of 32 objects. See 'Custom Object Files' below.
|-
| Level.dir.txt || This is used by SpriteEditor.exe to compile the final Level.dir file. It's a simple list of all files to include. NOTE: .SPD files are not included. The utility uses the .SPD and .BMP to create the .SPR file
|-
|}

'''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 :

{| class="wikitable" width="75%" border="1" cellpadding="2" cellspacing="0" style="margin-top: 0.5em;"
|-
! eg_value
! Info
|-
| 5 || Can be 1 to 10. This value affects the chance of an object being placed and is relative to the values of other objects.  EG, by setting all objects to 5, you can increase or decrease the values for objects that appear too little or too much (smaller objects or objects with a narrow base will typically have more places to appear in the terrain)
|-
| 0 || Specifies whether the object is in front or behind the terrain. 0 = behind, 1 = in front
|-
| 0 || Specifies whether the soil texture appears when the object is destroyed. 0 = none, 1 = soil
|-
| 1 || Enables or disables collision for the object.  1 = enabled.  0 = disabled
|-
| 1 || Specifies whether other custom objects can be placed onto this one. 0 = Yes, 1 = No
|-
| 3 || Location type of object. 0/1 = side of the terrain, 2 = ceiling, 3 = floor (0 or 1 indicate which side of your object is to be fixed to the side of the terrain, left [0] or right [1])
|-
|}

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. 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.  Note that there 2 types of BMP format; 'Windows BMP' and 'OS/2 BMP'.  They are different, and SpriteEditor will only accept OS/2 BMPs.

== Debris ==

The background falling debris (debris.spr) is an image file containing all animation frames stacked vertically.  The game renders many instances of this sprite to create the background falling debris effect.  Each instance of the debris is animated at a randomly assigned frame rate within a calculated range. The FPS range (frames per second) is calculated as between : '''TotalFrames/5 and TotalFrames*9/20'''  [Confirmed by Deadcode].  So this means that the FPS of your debris is linked to the number of frames in your animation.  For example, a 40-frame debris sprite will spawn instances of debris that have a random FPS between 8 and 18, but a 100-frame debris sprite will have an FPS between 20 and 45.  Keep this in mind when creating debris.

The debris.spr file is created by combining the debris.spr.bmp image file and the debris.spr.spd text file.  This .SPD text file contains parameters for the animation which are listed below.  Adjust these as required for your debris sprite :

{| class="wikitable" width="75%" border="1" cellpadding="2" cellspacing="0" style="margin-top: 0.5em;"
|-
! Parameter
! Info
|-
| frames = 50 || This is the total number of frames to include in the animation
|-
| height = 80 || This is the height of each frame
|-
| width = 100 || This is the width of each frame
|-
| framerate = 0 || This has no affect on the frame rate for debris, unlike other sprites used in the game. [Confirmed by Deadcode]. Leave as 0
|-
| flags = 1 || This controls the behavior of the animation playback; 0 = play once and stop, 1 = continuously loop, 2 = play forwards then backwards then stop, 3 = continuously play forwards then backwards (ping pong)
|-
|}


If you want to extract frames from an existing video / animation file (such as a .gif or .mp4), you can use ffmpeg to extract all frames and then use [https://imagemagick.org 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 in the palette of any image represents transparency in the game.  This can be any colour but it must be the same colour for all images used.'''  The default Team 17 terrains use black (0,0,0) as the first palette colour to represent transparency.

To avoid confusion in this section, when talking about the number of colours for an object, this will EXCLUDE transparency.  For example, a 10-colour sky gradient implies that the 'gradient.img.bmp' file actually has an 11-colour palette (including transparency as the first colour).

'''The game allows for a palette of up to 112 unique colours to be shared by all of your terrain 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 10 colours, another with 23 etc and the game will aggregate and de-duplicate the colours to build the palette. You could also index your entire project down to the optimum palette for all objects and have the same 112 colours for every object, although this is not advisable if you plan to convert your terrain maps to PNG.

If you want your terrain to be more compatible with PNG map conversion (you probably should!), it is recommended that all foreground terrain textures and objects share 96 colours, and all background elements (sky gradient, debris, and background layer) use these same 96 colours plus a dedicated extra 16 colours, totaling 112 colours.  This is because with PNG's, the sky gradient and background are changed for stock versions which will need additional colours and by taking this approach, you at least allow for the replacement sky gradient to be drawn perfectly.  If your terrain foreground objects use 112 colours, you can expect an ugly looking sky gradient when converting to PNG as the game will attempt to draw it with the colours available.

== 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

[[file:level dir thing.png|thumb|left|400px|If you did the steps for SpriteEditor.exe correctly after making [https://github.com/nizikawa-worms/EasyTerrain EasyTerrain Utility], your output folder should look something similar to this, '''especially that Level.dir file'''.]]
<br style="clear:both" />

== 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).
 - CHECK the "Recreate all .SPR/.IMGs" option (a precaution to ensure any existing files are re-created)
 - 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.

[[File:Text img file location after easyterrain.png|thumb|left|400px|If you use the [https://github.com/nizikawa-worms/EasyTerrain EasyTerrain Utility], you should use the Sprite Editor (left) provided to generate the "TEXT.img" file (middle, circled) from your BMP file named "text" (right)]]
<br style="clear:both" />

== Extracting Assets from an existing Level.dir file ==

SpriteEditor.exe may be used to extract assets from existing level.dir files, including the default terrains created by Team 17.  NOTE: 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.

 - 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.

== 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 [https://www.tus-wa.com/forums/files-comments/file-120-water-colour-editor-33387/?action=dlattach;attach=195994 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.

----