Map Config and Scripting
Introduction
Once you've created a *.cfg file for your map:
- Start Sauerbraten
- Enter edit mode by pressing the E key
- and at the console, type newmap
- Before editing anything, type: savemap mapnamehere
- Be sure that the name you save your map as, is the same name as your map.cfg file you created earlier.
- Finally, to put those new textures to work, at the console, type map mapnamehere
- This will reload your map, and load your configuration file as well.
When you want to share your maps with own CFG with others you should package the content and distribute this package to everybody. Then they should simply need to extract to their own Sauerbraten folder, find everything in place (nothing overwritten) and ready to go. Then just meet on any server and load the map, it will look fine. If you use the coop-edit mode to transfer a map, then only the geometry is passed and the map name will be unknown to you -- there is no way any but default_map_settings.cfg will be loaded. So either get some free webspace to put your maps on, email them to your friends or get an account on Quadropolis (the semi-official download site for Sauerbraten).
Basic uses
Each map will first load default_map_settings.cfg and then any package CFG and last the specific map CFG. So a map called metl4.ogz will call metl4.cfg.
The first need for such a specific map configuration file will most likely arise when you want to have a special skybox background. For this enter
loadsky "skyname" //loadsky "ik2k/env/iklake" //loadsky "socksy/mars"
Where skyname is the path to the 6 required images for a skybox. For example, loadsky "yourname/skyname" will try to load /packages/yourname/skyname_lf, skyname_rt, skyname_ft, skyname_bk, skyname_dn, and skyname_up.
Second, the fog cut-off distance, and fog color can be applied. For this enter
fog 2500 // the fog value can be set from 1 to 100000 as needed fogcolour 16777215 //this is the max setting. This is also a hex parameter, 0XRRGGBB.
Third, you might want some ambient lighting. For this use ambient 15 Can be set from 1 to 255 Be careful with the ambient option, as it reduces the texture contrast. To help converting RGB to HEX values, this RGB & Hex Converter popped up on the forum.
Cross-Platform
Beware that your filenames and CFG files must match in all spelling of filenames; especially capitalization has been problematic. For music OGG or MIDI are good formats for cross-platform friendliness, PNG textures also travel well.
Textures
The first thing to understand here is, the default map configuration is already in place. Unless you want to add new textures to your map, you do not need this part of a map.cfg Sauerbraten has a very large texture list by default. For the beginner mappers, this shoudl do fine. For the ones that need to add new textures, do the following:
To explain the meaning of this parameter(s), the line " texture 0 "dg/trail_in.jpg" " for example. The first number after the word texture, stands for the type of texture it will be used as. There are several different types, but for now we'll just use type 0. the part of the line in "" is telling the engine where the texture is located. You must name this directory yourself. When working with a new texture list, you should never add to an original Sauerbraten directory. Create your new directory withing the packages directory.
Start your map after creating this part of the maps .cfg file. You do not want to retexture anything. The first thing to add to the texture list section of a map.cfg file, is :
texturereset
This tells the engine to reset from the default configuration, and use the map.cfg for the texture list. After you reset the texture list, you need to add your own. The first 2 slots are "reserved" for the engine, and must be in every map.cfg file you use new textures with :
texture 0 "ik2k/ik_sky_day_back.jpg" texture 0 "golgotha/water2d.jpg"
From this point on, you can add as many textures as you want ( up to 2^16 or 65,536 ) You could also list the same texture more than once, to have rotated versions, by adding a number AFTER the texture name:
texture 0 "dg/trail_in.jpg" 0 // 0 = none, 1 = 90 CW, 2 = 180, 3 = 270 CW, 4 = X-axis flip, 5 = Y-axis flip
Shaders
Shaders are post processing effects applied to textures. They are used to provide added realism and depth to flat textures.
You define a shader with:
setshader x set*param index x y z w
You define textures to use as "maps" for the shaders using the following:
texture 0 "texturename" // default texture texture d "texturename" // decal texture texture n "texturename" // normal map texture s "texturename" // specular map texture g "texturename" // glow map texture z "texturename" // depth (parallax) map texture u "texturename" // undefined (currently used for sphere maps)
The following list was compiled from CVS sauerbraten after the 2006-12-04 "gui" edition release. Then the supported texture shaders were, check your local documentation and CFG files (data/stdshader.cfg):
===shader=== | ===description=== |
stdworld | null shader; no params; uses 0 only |
decalworld | decal shader; no params; uses 0, d |
glowworld | glow map shader; setpixelparam 0 r g b; uses 0, g |
pulseworld | pulse shader; setvertexparam 1 x; uses 0 |
pulseglowworld | pulsing glow map shader; setpixelparam 0 r g b, setvertexparam 1 x; uses 0, g |
metalworld | sphere map shader; setpixelparam 0 r g b; uses 0, u |
bumpworld | normal map shader; no params; uses 0, n |
bumpspecworld | normal map shader with spec; setpixelparam 1 r g b; uses 0, n |
bumpspecmapworld | normal, spec map shader; setpixelparam 1 r g b; uses 0, n, s |
bumpspecmapglowworld | normal, spec, glow map shader; setpixelparam 0 r g b, setpixelparam 1 r g b; uses 0, n, s, g |
bumpspecparallaxworld | normal, parallax map shader with spec; setpixelparam 1 r g b, setpixelparam 2 x y; uses 0, n, z |
bumpspecmapparallaxworld | normal, parallax, spec map shader; setpixelparam 1 r g b, setpixelparam 2 x y; uses 0, n, s, z |
bumpspecmapparallaxglowworld | normal, parallax, glow, spec map shader; setpixelparam 0 r g b; setpixelparam 1 r g b, setpixelparam 2 x y; uses 0, n, s, g, z |
preliminary copy from IRC log:
[19:40] <KaiserTodretter> bumpmaps are greyscale images that basically say what the heights of the different parts of a texture are [19:40] <KaiserTodretter> white being high spots and black being low spots [19:41] <KaiserTodretter> bumpmaps make a texture appear not flat and distorts the texture in a way that it actually looks 3D [19:42] <KaiserTodretter> normal maps are made from bumpmaps and are used to determined at what angles you will see the specularity of a texture [19:43] <KaiserTodretter> the specularity can either be a constant set in the map config or a specmap texture can be made to show what parts of the texture are shiney and what parts are dull [19:43] <KaiserTodretter> the last thing you can add is glowmaps [19:43] <KaiserTodretter> they dont actually 'emit' light to their surroundings [19:44] <KaiserTodretter> but they are lit up even if there is no light on them [19:44] <KaiserTodretter> you probably also noticed how as you move by certain textures you can see some shine on them and it changes as you move by [19:45] <KaiserTodretter> that is the spec and normal maps [19:45] <devoid> ok [19:45] <devoid> they make the "shine" effect ? [19:45] <devoid> ill experiment some more [19:46] <KaiserTodretter> the 'shine' itself comes from the specularity [19:46] <KaiserTodretter> however using normal maps with that will make the shine appear at the correct angles [19:46] <devoid> so, does it involve alot of work to make a set of such textures? or is it pretty easy if you got the hang of it ? [19:47] <KaiserTodretter> otherwise it will appear as if the texture is perfectly flat [19:47] <KaiserTodretter> some are time consuming [19:47] <devoid> well thx for the tips
Sound
use the commands
music package_path/file.ogg music package_path/file.mp3 // and/or snd_index = registersound package_path/file.wav snd_index = registersound package_path/file.mp3 level_trigger_42 = [ sound $snd_index ] // and/or // only WAVs allowed ATM, so do not add an extension! mapsound package_path/file_one mapsound package_path/file_two 255 mapsound package_path/file_two 128 mapsound package_path/file_two 100 mapsound package_path/file_three 2
to add individual sound fx to your map. The mapsound fills indexed slots for usage with sound-entities.
// X R F newent sound 1 128 64
This would load the second slot (1st = 0) "X" onto that entity. At a radius of 128 you'd start/stop hearing it ... smaller than 64 and it'd be at full volume (see CFG).
Triggers
Defining trigger actions - for SP maps only - is a vast field. You can basically define any scripting action inside a trigger alias, this will be parsed when the player enters the space of the trigger entity.
Read the section about Entity Types to understand what the tie-up with mapmodels is all about.
You can start off trying out triggers with simple echo commands, then start scripting the action you'd like to happen.
To see how doors work you can look at packages/models/doors/door_01/md3.cfg - and of course a map that has doors ;) A simplistic form of a secret's counter - can be found on the Trigger 101 page.
Try finding out how maps do stuff if you want to start using triggers yourself. Then try "faking" the action by calling your script by hand. Finally select an index for this action, say 42, then you'll simply need to place this scripting inside a
level_trigger_42 = [ // your code here ]
alias and place triggers with tag 42 into the right places. To modify a placed triggers (default menu only has 0-8) tag :
entproperty 3 +30 entproperty 3 +2 entproperty 3 -1