Navigation
Community
Configuring
Creating
FAQ - General
Info for Sauerbraten Users
Introduction
Known Issues
Main Page
Notes
Playing
Troubleshooting

Creating >

### Textures

Textures can be defined, for maps and for models, using the Cube 2 commands as documented there, but 'translated' into JavaScript. For example, texture n sometex.png would be Map.texture("n", "sometext.png");, and md5skin somemesh sometexture.png would be Map.md5Skin("somemesh", "sometexture.png");. See the existing assets for examples.

## Using textures in your maps

There are 2 things you need to do to use textures:

- First you need to add the texture packs as dependencies to the asset. This is done on the website. Without this, the texture packs won't be downloaded for people that don't have them yet. (But it will work for people that already have them, even if you don't do this, so be careful.)
- Then you need to define the textures in the map script. The commands generally look like this:
  Library.include('textures/gk/concrete3/');
  You can copy them from an existing map. Or cloning that map (or using the map creation wizard) will get both the dependencies and the map script stuff.

## Clarifications to the Cube 2 documentation

- For world geometry (cube) textures (Map.texture), if a diffuse ("0" or "c", usually with name ending in _cc) texture has an alpha channel, the alpha channel is used as a specularity map. So you don't need to define a specularity map explicitly. Likewise, if a normal map ("n", usually with name ending in _nm) has an alpha channel, the alpha channel is used as a height (parallax) map.
- For model textures (Map.md5Skin, etc.), alpha channels are not used in such a way. For specularity maps, they can be used as part of a masks texture as described in the md5skin documentation in Cube 2. Heightmaps can't be used in model textures.
- You can compress textures, using DDS files or the <compress> tag on the texture. Note however that compressed textures have the limitation that, if you want a specularity map, it must be in the alpha channel, and not as a separate texture. The same holds for height maps. (The reason is that the engine always places specularity maps and height maps as alpha channels - that is how they are actually stored on the graphics card. When given two separate textures - diffuse and specularity, or normal and height - the engine will combine them manually. The problem is then that compressed textures cannot be manipulated by the engine in such a manual way. Instead, you must do the combining in the external tool that creates the compressed texture).

- The engine is fairly smart about fallbacks and secondary textures. For example, if you define a primary texture as "<dds>mytex.jpg", and a specularity map as "mytex_spec.jpg", then the engine will try to load mytex.dds, if it can (most modern graphics cards can). An alpha channel, if present in the dds file, will be used as a specularity map - so the command to use "mytex_spec.jpg" will be ignored, as it should (again, this is due to it not being possible to combine compressed images). If, on the other hand, the dds isn't used (the hardware doesn't support it, or it isn't present), then "mytex_spec.jpg" will be used as a specularity map, as you would expect (for which, behind the scenes it will be placed in the alpha channel by the engine).

## Additional Syntensity Functionality

- Your texture scripts can convert JPEG2000 files into PNG format, using
  Map.convertJP2toPNG('path/to/original.jp2');
  The output file will have extension .png.
  The conversion is only done if the original is newer than the output, or the output doesn't exist (so this is done only once each time the original changes).
- You can combine two textures into one, with the second placed in the alpha channel of the new image, using
  Map.combineImages('path/to/primary.ext', 'path/to/secondary.ext', 'path/to/combined.ext');
  For example,
  Map.combineImages('textures/rock_cc.png', textures/rock_sc.png', 'textures/rock_ccsc.png');
  The conversion is only done if at least one of the originals is newer than the output, or the output doesn't exist (so this is done only once each time at least one of the originals changes).
- A typical usage of these commands is as follows (this is automatically created by tools/create_tex_config.py). This decompresses diffuse and a specularity textures from JPEG2000 into PNG format, combines them into one file (the specularity placed into the alpha channel), and creates a DDS of that file. The final texture can then be used as "<dds>textures/rock_ccsc.png".

- Map.convertJP2toPNG('textures/rock_cc.jp2');
- Map.convertJP2toPNG('textures/rock_sc.jp2');
- Map.combineImages('textures/rock_cc.png', textures/rock_sc.png', 'textures/rock_ccsc.png');

Updated on Oct 26, 2009 by Alon Zakai (Version 9)