September 27, 2011

Tutorial: Resources and system configuration

This tutorial explains how to setup various system stuff, where to find resources like textures and objects within the filesystem and how to configure and import them

The configuration file
A single config file named "config.r3c" holds virtually all the information to setup the engine. It is located in the engine root directory (where "revert3d.exe" is stored). The file format is "r3c", which is a readable text format that is widely used by REVERT3D. You can open the file using a text editor like notepad to see its content. In version 0.8.1b, it should look something like this:

COMMENTS = Path configuration (Relative to root directory)
TEXTURES = data\tex\
OBJECTS = data\obj\
MAPS = data\maps\
TEMP = data\temp\
USER = data\user\
SCRIPTS = data\scripts\


The structure should be quite easy to understand: "[PATHS]" is the name of the section, while the following keywords (no brackets) are the stuff to be configured:

KEYWORD = value

The combination of section/keyword has to be unique. Theres just one "TEXTURES" key in "PATHS" - On the other hand, there is a "COMMENTS" key in nearly every section. Also, be careful not to store information in the wrong section, since the engine will look for the keys in specific sections!
Most of the informations contained in this file will or should not be changed at all, but some can be useful to customize your project. Here comes a brief description:

Section/Key Description
[PATHS]Path configuration for all kinds of resources. These are alwaysrelative to the engines root directory! You should not do any changeshere afterwards. First set up the configuration, THEN start creatingmaps and stuff!
COMMENTS Just some comments about the content of this section
TEXTURESRelative path where to store and search for textures (Example: "data\textures") - These directories may have subdirectories to structurize your content
OBJECTS... same for objects
MAPS... maps
TEMP... temporary files / mainly used by the system as a cache
SCRIPTS... script sourcecode files
USER... "user files" (free for anything that doesn't fit to one of the other categories)
 [DEFAULT_TEXTURES]  Default textures which will be used by the editor when nothing else was selected
WALLSRelative path to default texture file for walls
FLOOR ... same for the floor
CEILING ... ceiling
[CAMERA] Camera configuration (which is more or less obsolete by now)
PLAYERHEIGHTHeight of the camera in units above the floor
[ENGINECORE]This configures the desired engine speed - Its a good idea not to change this ^^
TARGETLOGICRATEThe target rate of logic cycles
TARGETFRAMERATE... frame render cycles / fps
BASESCRIPTRelative path to base script (into script directory). This will be executed each time a map is loaded and can be used to do init stuff
EDITORSCRIPTEditor script which will execute on specific editor events. This is where the editor creates the player and scene FX object when creating a map
EDITORCOLORSDefault color scheme for script editor. Values: BOW (black on white) or WOB (white on black)
[DEFAULT_FILTERS]This section defines the default texture filter used for each subdirectory into your textures folder. The system works hierachically, causing all subdirectories to inherit their parents texture filter if nothing other was defined. By default, all textures will use "TEXFILTER_MIPMAP". Possible values are TEXFILTER_MIPMAP (generates hardware mipmaps),TEXFILTER_LINEAR (linear filter), TEXFILTER_NEAREST(pixelize!)
%ROOT%Special constant defining the texture root directory
EDITORThis would be used for all textures inside the "Editor" subdir
GUI... same for the "gui" subdir
MAPS\OBJECTS... "objects" subdir inside "maps" subdir

The textures directory
This directory contains four subdirectories used by the system, which may not be renamed or moved. Here we go:
\editor (Icons and graphics used by the scene editor)
\fonts (Textures containing bitmap fontsets)
\gui (GUI graphics like button and window textures)
\sys (System graphics like markers and symbols)

There also has to be a texture named "dummy.bmp" right in the texture root directory. This is the "dummy texture" which will be used when no other texture has been selected, the selected texture is broken or not available anymore. This texture traditionally contains the REVERT3D logo.

Adding textures
This is pretty easy: Just put them somewhere in your textures directory and they will be available in the texture browser next time you start the editor. Currently supported formats are bmp and tga - More formats will be introduced in the future.

Adding objects
Same like adding textures: Just make sure to put them into the specified objects directory. The R3D object editor will automatically do this for you when creating new objects - But more on this soon in an upcoming tutorial!

Adding maps
Maps will be automatically saved to the specified maps directory when using the scene editor. However, you could also just put a map there manually. If the map contains textures which are not available, the dummy texture will be used instead. Missing objects can cause some trouble but it should at least load the map geometry without any problems.

General notes on adding resources
You should try to structurize your directories right from the start since it'll be hard to move them afterwards when there are objects,maps and textures referencing each other in specific locations! Creating subdirectories for specific stuff like objects and maps will help you to keep your resources "clean".

No comments:

Post a Comment