4.16.3.2 Syntax

Written by numerous Crystal Space developers. Extensive Texinfo typesetting performed by Eric Sunshine, [email protected].

Basic Syntax Elements

number

A general number.

pos-number

A general positive number.

integer

A general integer.

pos-integer

A positive integer (> 0).

number..number

A numeric range. For example, `0..1' represents a number between 0 and 1.

name

A name identifier. An unquoted string provided that it contains no punctuation or whitespace; otherwise delimited by double quotes.

string

A string delimited by double quotes. Special characters are escaped with a backslash.

Number List

number-list => number [ `,' number ] ...

Boolean Value

yes => `yes' | `true' | `on' | `1'
no => `no' | `false' | `off' | `'
yes-no => yes | no

Color Description

red => 0..1
green => 0..1
blue => 0..1
gray => 0..1
color-grayscale => gray
color-general => red `,' green `,' blue
color => color-grayscale | color-general

Vectors and Coordinates

Note that the x-axis points to the right, the y-axis points up, and the z-axis points forward.

x => number
y => number
z => number
u => number
v => number
vector-2d => x `,' z
vector-3d => x `,' y `,' z
vector-4d => x `,' y `,' z `,' r
vertex-idx => integer
coordinate => vector-3d
coordinate-2d => vector-2d
texture-coordinate => u `,' v

Object Names

sector-name => name
light-name => name
col-name => name
texture-name => name
material-name => name
mesh-name => name
meshfact-name => name
library-name => name
file-name => name
plugin-name => name
plugin-shortname => name
cache-name => name
priority-name => name

Attributes and Numbers

radius => pos-number
angle => number
keyname => string
keyvalue => string

Visibility Culling

Sidenote: the `CULLER' statement is going to be obsolete in the future.

culler => `CULLER' `(' mesh-name `)' cullerp => `CULLERP' `(' plugin-name `)'

Key

Use the `KEY' feature to attach arbitrary game data to any Crystal Space object. Crystal Space will only store these key/value pairs with objects but doesn't otherwise use them. You can iterate over these keys in the code.

key => `KEY' `(' keyname `,' keyvalue `)'

Fog

density => number
fog-desc => `FOG' `(' color `,' density `)'
alpha-nr => `' | `25' | `50' | `75'
alpha => `ALPHA' `(' alpha-nr `)'

Matrices, Vectors, Scalers, and Angles

vector => `V' `(' vector-3d `)'
matrix-scaler => number
matrix-x-scaler => matrix-scaler
matrix-y-scaler => matrix-scaler
matrix-z-scaler => matrix-scaler
stated-matrix-x-scaler => `SCALE_X' `(' matrix-x-scaler `)'
stated-matrix-y-scaler => `SCALE_Y' `(' matrix-y-scaler `)'
stated-matrix-z-scaler => `SCALE_Z' `(' matrix-z-scaler `)'
complex-matrix-scaler => stated-matrix-x-scaler
        | stated-matrix-y-scaler
        | stated-matrix-z-scaler
full-matrix-scaler => matrix-x-scaler `,' matrix-y-scaler `,' matrix-z-scaler
uniform-matrix-scaler => matrix-scaler
simple-matrix-scaler => `SCALE' `(' uniform-matrix-scaler | full-matrix-scaler `)'
compound-matrix-scaler => simple-matrix-scaler | complex-matrix-scaler

rotation-x-angle => angle
rotation-y-angle => angle
rotation-z-angle => angle
rotation-x-matrix => `ROT_X' `(' rotation-x-angle `)'
rotation-y-matrix => `ROT_Y' `(' rotation-y-angle `)'
rotation-z-matrix => `ROT_Z' `(' rotation-z-angle `)'
complex-rotation-matrix => rotation-x-matrix | rotation-y-matrix | rotation-z-matrix
rotation-angles => rotation-x-angle `,' rotation-y-angle `,' rotation-z-angle
simple-rotation-matrix => `ROT' `(' rotation-angles `)'

rotation-matrix => simple-rotation-matrix | complex-rotation-matrix
complex-matrix => rotation-matrix | compound-matrix-scaler
simple-scaled-matrix => uniform-matrix-scaler
normal-matrix => vector-3d `,' vector-3d `,' vector-3d
identity-matrix => `IDENTITY'
matrix-type => identity-matrix
        | normal-matrix
        | simple-scaled-matrix
        | complex-matrix
matrix => `MATRIX' `(' [ matrix-type ... ] `)'

move-comp => matrix | vector
move => `MOVE' `(' [ move-comp ... ] `)'
hardmove => `HARDMOVE' `(' [ move-comp ... ] `)'

Lights

It is recommended to use the new syntax for lights.

dynamic-flag => `' | `1'
light-oldsyntax => coordinate `:' radius `,' color-general `,' dynamic-flag

light-center => `CENTER' `(' coordinate `)'
light-radius => `RADIUS' `(' radius `)'
light-color => `COLOR' `(' color `)'
light-dynamic => `DYNAMIC' `(' `)'
light-halo => `HALO' `(' `)'
light-comp => light-center
        | light-radius
        | light-dynamic
        | light-color
        | light-halo
light-newsyntax => [ light-comp ... ]

light => `LIGHT' light-name `(' light-oldsyntax | light-newsyntax `)'

Collection Objects

Note that collection objects are NOT hierarchical objects. A collection object is just one object that represents a group of other objects.

col-mesh => `MESH' `(' mesh-name `)'
col-collection => `COLLECTION' `(' col-name `)'
col-light => `LIGHT' `(' light-name `)'
col-sector => `SECTOR' `(' sector-name `)'
collection-comp => col-collection
        | col-light
        | col-sector
        | col-mesh
collection => `COLLECTION' col-name `(' [ collection-comp ... ] `)'

Materials and Textures

material => `MATERIAL' `(' material-name `)'
texture => `TEXTURE' `(' texture-name `)'

Material and Texture Description

transparent => `TRANSPARENT' `(' color `)'
procedural => `PROCEDURAL' `(' `)'
tex2d => `FOR_2D' `(' yes-no `)'
tex3d => `FOR_3D' `(' yes-no `)'
persistent => `PERSISTENT' `(' `)'
filter => `FILTER' `(' ... `)'
mipmap => `MIPMAP' `(' yes-no `)'
dither => `DITHER' `(' yes-no `)'
texture-file => `FILE' `(' file-name `)'

texture-desc-comp => transparent
        | filter
        | mipmap
        | dither
        | file
        | procedural
        | tex2d
        | tex3d
        | persistent
texture-desc => `TEXTURE' texture-name `(' [ texture-desc-comp ... ] `)'

material-desc-comp => texture
        | `COLOR' `(' color `)'
        | `DIFFUSE' `(' number `)'
        | `AMBIENT' `(' number `)'
        | `REFLECTION' `(' number `)'
material-desc => `MATERIAL' material-name `(' [ material-desc-comp ... ] `)'

LOD

lod-level => `LEVEL' `(' number `)'
lod-comp => lod-level
lod => `LOD' `(' [ lod-comp ... ] `)'

Mesh Objects

Important note! This documentation explains ONLY the basic mesh object and factory parsing. It does NOT describe the parsing that is done by the loader plugin itself. So this means that everything inside the `PARAMS' blocks is not documented in this document. Documentation for this will follow later in the mesh object plugin documentation.

plugin => `PLUGIN' `(' string `)'
params => `PARAMS' `(' string `)' paramsfile => `PARAMSFILE' `(' file-name `)' mesh-nolighting => `NOLIGHTING' `(' `)'
mesh-noshadows => `NOSHADOWS' `(' `)'
mesh-invisible => `INVISIBLE' `(' `)'
mesh-detail => `DETAIL' `(' `)'
mesh-zfill => `ZFILL' `(' `)'
mesh-znone => `ZNONE' `(' `)'
mesh-zuse => `ZUSE' `(' `)'
mesh-ztest => `ZTEST' `(' `)'
mesh-camera => `CAMERA' `(' `)'
mesh-convex => `CONVEX' `(' `)'
mesh-priority => `PRIORITY' `(' priority-name `)'
mesh-lmcache => `LMCACHE' `(' cache-name `)'

mesh-comp => plugin
        | addon
        | key
        | params
        | paramsfile
        | mesh
        | move
        | hardmove
        | lod
        | mesh
        | meshref
        | mesh-nolighting
        | mesh-noshadows
        | mesh-invisible
        | mesh-detail
        | mesh-zfill
        | mesh-znone
        | mesh-zuse
        | mesh-ztest
        | mesh-camera
        | mesh-convex
        | mesh-priority
        | mesh-lmcache
mesh => `MESHOBJ' mesh-name `(' [ mesh-comp ... ] `)'
meshlib => `MESHLIB' mesh-name `(' [ mesh-comp ... `)'

meshref-factory => `FACTORY' `(' meshfact-name `)'
meshref-comp => meshref-factory
        | addon
        | key
        | move
        | hardmove
        | lod
        | mesh-nolighting
        | mesh-noshadows
        | mesh-invisible
        | mesh-detail
        | mesh-zfill
        | mesh-znone
        | mesh-zuse
        | mesh-ztest
        | mesh-camera
        | mesh-convex
        | mesh-priority
meshref => `MESHREF' mesh-name `(' [ meshref-comp ... ] `)'

Mesh Object Factories

meshfact-file => `FILE' `(' file-name `)'
meshfact-comp => plugin
        | addon
        | params
        | paramsfile
        | meshfact-file
        | meshfact
        | move
        | hardmove
        | lod
        | material
meshfact => `MESHFACT' meshfact-name `(' [ meshfact-comp ... ] `)'

Nodes

position => `POSITION' `(' coordinate `)'
node-comp => position | key
node => `NODE' `(' [ node-comp ... ] `)'

Sectors

sector-comp => addon
        | culler
        | cullerp
        | light
        | mesh
        | meshref
        | meshlib
        | fog-desc
        | key
        | node
sector => `SECTOR' sector-name `(' [ sector-comp ... ] `)'

Texture List

textures-comp => texture-desc
textures => `TEXTURES' `(' [ textures-comp ... ] `)'

Material List

materials-comp => material-desc
materials => `MATERIALS' `(' [ materials-comp ... ] `)'

Material Groupings

Sometimes you want things of the same type but with different materials on it. This is where material groupings come in handy. The final name of a texture in a `MAT_SET' expression will be `mat-set-name_texture-name'. The materials will be merged into the global texture list. You should define a `MAT_SET' after `TEXTURES' since the latter command clears the internal list first.

mat-set-name => name
material-set => `MAT_SET' mat-set-name `(' materials `)'

Library

library => `LIBRARY' library-name `(' file-name `)'

Starting Position

start-sector => `SECTOR' `(' sector-name `)'
start-position => `POSITION' `(' coordinate `)'
start-up => `UP' `(' vector-3d `)'
start-forward => `FORWARD' `(' vector-3d `)'
start-comp => start-sector
        | start-position
        | start-up
        | start-forward
start-newsyntax => [ start-comp ... ]
start-oldsyntax => sector-name `,' coordinate
start => `START' `(' start-oldsyntax | start-newsyntax `)'

For Loader Plug-Ins

plugin-id => plugin-name | plugin-shortname
plugin-spec => `PLUGIN' `(' plugin-id `)'
plugin-params => `PARAMS' `(' ... `)'
plugin-comp => `PLUGIN' plugin-shortname `(' plugin-name `)'
plugins => `PLUGINS' `(' [ plugin-comp ... ] `)'

Add-ons

Same remark as for mesh objects: the stuff that is inside the `PARAMS' block is not documented here.

addon-comp => plugin-spec | plugin-params
addon => `ADDON' `(' [ addon-comp ... ] `)'

Sounds

sound-file => `FILE' `(' file-name `)'
sound => `SOUND' [ file-name ] `(' [ sound-file ] `)'
sounds => `SOUNDS' `(' [ sound ... ] `)'

Settings

setting-ambient => `AMBIENT' `(' color `)'
setting-clearzbuf => `CLEARZBUF' `(' yes-no `)'
setting-clearscreen => `CLEARSCREEN' `(' yes-no `)'
setting-lightmapcellsize => `LIGHTMAPCELLSIZE' `(' pos-integer `)'
setting-maxlightmapsize => `MAXLIGHTMAPSIZE' `(' pos-integer `,' pos-integer `)'
settings-comp => setting-ambient
        | setting-clearzbuf
        | setting-clearscreen
        | setting-lightmapcellsize
        | setting-maxlightmapsize
settings => `SETTINGS' `(' [ settings-comp ... ] `)'

World

world-comp => textures
        | materials
        | library
        | addon
        | material-set
        | sounds
        | plugins
        | sector
        | meshfact
        | collection
        | start
        | key
        | settings
world => `WORLD' `(' [ world-comp ... ] `)'

Library File

library-comp => textures
        | materials
        | meshfact
        | addon
        | meshobj
        | meshref
        | sounds
        | plugins
library => `LIBRARY' `(' [ library-comp ... ] `)'

This document was generated using texi2html 1.76.