AssaultCube Documentation

Map editing - Config files

When you first start a map, be sure to use the /newmap command, rather than editing an existing map. Issuing the newmap command ensures that your map uses the default map settings, rather than using the existing configuration for that map (if it did use the existing configuration, upon 2nd load, the map will become messed up).

Map config files will ONLY be needed if you want to utilize any of the below:

The first step to using any of the above in your map is copying the /config/default_map_settings.cfg file into your /packages/maps folder and then renaming it to the same name as what your map will be called (i.e. foobar.cfg). Whenever your map is loaded, it will look for your maps config file (which it can only find if it's named the same as your map). If it can't find the config file for your map, it will automatically load the default config instead.

Warning: PLEASE be aware when adding custom content to your map, to make sure you use LOWERCASE through out the config file and make sure file names of your custom content also use lower case. If you don't, some operating systems such as Linux, will not load the commands or files due to the fact that an uppercase letter in Linux is counted as a completely different letter to a lower case letter. So it is absolutely vital that the filenames match (even in the file-name extension!)

Warning: Don't use single slashes in the config file to issue commands, as the commands won't work if you do.

Note: You may see "comments" in the config files. Comments are lines of writing in the config file that have had 2 forward-slashes put in front of them. Using comments is a good way to advise the reader of the config file about things in the config file. Comments are ignored by the AssaultCube engine. Below is an example of a comment:
// This is a comment!

Custom textures

When you want to add custom textures to your config file, be sure that the textures tile seamlessly. This means that your texture, when lined up against itself in all directions, should match itself.

Preferably, textures should be 256x256 pixels. But, one cube in AssaultCube is covered by 32x32 texture pixels (for texture scale 1.0), so, as long as the image is a multiple of 32 pixels and doesn't take up too much space, the texture should work fine. If the image is not a multiple of 32 pixels, it will not fit on the cube properly and will be unaligned and look strange. When creating/using custom textures, remember that too much detail/size could make that texture in the map too laggy!

You will notice in the default config a command "texturereset". This ensures that all the textures in your map are always shown in the correct order, so make sure you leave this where it is! Textures are in a numbered list and the "texturereset" command resets that list, so that your map is not using the last maps texture list. The first and second textures in the list are hardcoded as the skymap and water textures.

You are allowed to add new textures anywhere below where it says // Texture #1 Putting it above this will create some problems. If you are just starting your map, it would be fine to replace textures in the list, or slot your textures anywhere between the current texture list. However, if you have already started your map and are just now adding a new texture, it would be wise to place your texture at the very end of the list, so that your map does not get messed up!

To add a new texture, use this format: texture 0 "./raboof/foobar.jpg" on a single line. Replace "raboof" with the folder name and "foobar" with the name of the image. Be sure to put all your content inside a separate folder so that it does not get mixed in with everyone elses content.

Note: All textures MUST be placed inside /packages/textures/.

Warning: There is a texture command in the default config that has the comment "dummy" after it. Do not touch or remove this texture command as it will break some configurations.

Warning: There can only be maximum of 256 textures in your map! Any more won't be loaded.

Custom mapmodels

To use your own custom mapmodels in AssaultCube, all models must be of either md2 or md3 format and be placed inside /packages/models/mapmodels. You will need to create a separate folder for your mapmodel. Inside it, you will need to place the model with the name "tris" (and the .md2 or .md3 extension). You will also need to place the skin in the same folder with the name "skin.jpg".

You will see a command called "mapmodelreset". All mapmodels can be placed below this. The mapmodelreset command ensures that the mapmodels in the numbered list are reset, meaning that everything appears as it should, rather than using the last maps mapmodel numbering.

To add a mapmodel, use this format: mapmodel X Y Z 0 "model-folder" on a single line. Replace "model-folder" with the name of the folder that the mapmodel is in (for example, if the file is in /packages/models/mapmodels/tree, you would put "tree" there).|

Mapmodels use an invisible force to make them feel solid (i.e. you colide against them, rather than falling through them). This invisible force is called a "clip".

Note: The mapmodel number is defined by where the mapmodel is placed inside the mapmodel list, i.e. the 21st mapmodel command will be the 21st mapmodel

Tip: If you define the mapmodel to have 0 clipping of the width/length but give it a height clipping (for example, a clipping of 8 high) then that model will actually take up the width/length of 1 single cube with the height you defined (if you define both to be 0, then it won't be clipped)

Custom skymaps

All skymaps should be placed in their own individual folder (based on the author) inside packages/textures/skymaps/.
Six pieces make up a skymap and should be named as below (replace "foobar" with the name of the skymap):

Look for the part of the config with the commands "loadsky". Delete or "comment out" the current skymap commands there so they don't conflict with your skymap. Then, on a single line, use this format to add your skymap: loadsky "textures/skymaps/foobars-skymaps/foobar1" (where it says "foobars-skymaps", replace that with your folders name, where it says "foobar1", replace that with the skymap name).

Note: There are a selection of skymaps already available for you to use if needed. Just uncomment the one you want (comment the others).

Note: The skymap is hardcoded as the first texture, in the texture list.

Custom fog distances and colours

Fog is used in AssaultCube to help improve performance on some computers. However, it's not completely necessary and as long as it doesn't make your map too laggy and will improve your maps look, then you can make the fog appear at different distances and colours to add to your maps appearance.

To change the distance at which fog will appear, add this command to a single line in your config file: fog X
Replace X with the distance at which you want the fog to start appearing (maximum of 1024, default is 180).

To change the colour of the fog, add this command to a single line in your config file: fogcolour X
Replace X with the appropriate hexadecimal colour code.

Changing the angle shadow stencils are drawn

Changing the angle at which shadows stencils are drawn can have some nice effects on lighting in your map. To change the angle, first experiment in the map by typing "/shadowyaw D" (replace "D" with an angle between 0 and 360). When you have found the appropriate angle you wish to use, simply add the command shadowyaw D to a single line in your configuration file (replacing "D" with an angle between 0 and 360).

Ambient sounds

To enable custom ambient sounds in your map, all sound files must be either .wav or .ogg format. All files need to be put in the /packages/audio/ambience folder. Be sure to put your sound files inside your own individual folder.

You will see a command called "mapsoundreset". All mapsounds can be placed below this. The mapsoundreset command ensures that the mapsounds in the numbered list are reset, meaning that everything sounds as it should, rather than using the last maps sound numbering.

To add sounds to the config file, add this command to a single line: mapsound "raboof/foobar.wav" X
Replace "raboof" with your sounds folder name and replace "foobar.wav" with your sound files name. Replace X with how many times the sound should be allowed to play at once (for example, if there are several of the same sound in one area, this would define how many of them should play at once, as too many might be a bit of an overkill). Using the value "-1" (which is the default) will make it play an unlimited amount of times.

The order that you place the mapsound commands in the config file, determines their slot number (i.e. the first one in the list would be slot 0, the second mapsound command would be slot 1).

Using the "loadnotexture" command

Due to AssaultCube's light-weight approach to gaming, custom content from new custom maps are not downloaded automatically to a players computer system, as content size can be quite big, which is just not appropriate for 56k modem users and users with restricted bandwidth. Because of this, users will have to go and download the content manually. Since the config and map files are downloaded (due to their small sizes), there is a command you can use in the config which will automatically load all textures that aren't found to be a specific already existing texture.

When using this command, the texture that you want to load must be found within the /packages/textures/ folder. To use this feature, add this command to a single line: loadnotexture "raboof/foobar.jpg". Replace "raboof" with the folder name and "foobar" with the name of the image. You will need to have commented-out or deleted the pre-existing "loadnotexture" command.

© Copyright, Rabid Viper Productions
We would be grateful for any donations considered towards AssaultCube