previous//next//start

Thing Assembly Syntax

Structure

This is the overall structure of a thing definition:

THING

      // the header part:  defines global thing properties like NAME, SCALE etc.

      NAME "Sample Object"

     

      // list of subpart definitions. Each subpart defines one mesh with texturing etc. information

_0:   SRF "Sample Mesh.X"

      PAINT "Sample Texture.JPG"

 

_1:  ...etc.

 

END

 

Statements and Definitions

ALPHA

Used in PAINT statements.

Use this modifier to create a transparent material. The legal argument is a number specifying the opacity between 0 and 1.

Example:

PAINT ALPHA 0.5 "SomeTexture.JPG"

 

AMB

Used in PAINT and LIGHT...END statements.

Sets the ambient component of the light or material. Legal arguments are the red, green and blue values between 0 and 1. If this is used inside an animated LIGHT...END, an additional set of red, green, blue values need to be supplied.

Example:

PAINT AMB 0.5 0.5 0.5 DIFF 0.8 0.2 1 SPEC 1 1 1 POW 75

 

AMOUNT

Used in BILLBOARD..END and HMDECO...END statements.

Determines the number of sprites to be placed in a billboard group or on a single patch. Legal argument is an integer value specifying the desired amount.

Example:

HMDECO

    AMOUNT 75

    ...

 

BILLBOARD...END

Used in subpart definitions, instead of a SRF definition.

This construct creates a single sprite or a group of sprites, always facing to the camera ("billboards"). If more than one sprite is created (AMOUNT > 1), the 3D geometric distribution of the group can be specified ( e.g. SPHERE ). The system will use this shape to simulate correct lighting.

The BILLBOARD...END construct must be followed by a single PAINT statement, specifying a texture file (typically a TGA file with alpha channel ).

The parameters and their usage:

Defines the number of sprites for this object.

Creates a 3D distribution of the sprites in shape of a cone. r is the radius and h the height in centimeters.

Creates a 3D distribution of the sprites in shape of a double cone. r is the radius and h0 and h1 the upper and lower heights in centimeters.

Determines the virtual height of a single sprite in centimeters.

                    This statement causes  the sprites to face the camera.

This statement causes  the sprites to face the camera only around the Y axis.

If specified, the simulated lighting will be deactivated.

Random generator seed for the distribution of multiple sprites. n is an integer value. Same values cause identical distributions.

Creates a 3D distribution of the sprites in shape of a sphere with a radius of r centimeters. The optional argument h can be used to supply a height value, and thus distort the sphere into an ellipsoid.

Determines the virtual width of a single sprite in centimeters.

 

Example:

_1: BILLBOARD

        AMOUNT 50

        SPHERE 100

        ORIENT_XYZ

        WIDTH 100

        HEIGHT 100

    END

    POS 0, 200, 0

    PAINT "SPRITE23.TGA"
 

 

BUMP, BUMP_NM

Used in PAINT statements.

This modifier adds a bump map texture to a textured material. Use BUMP to convert a black/white texture to a normal map. Use BUMP_NM if the texture is already in normal map format (usually a DDS file). If the texture file is stored at its default place in the <BW Tools Installation Folder>\ART folder ( e.g. JPG files in <BW Tools Installation Folder>\ART\JPG etc. ), no path needs to be specified. Otherwise the full directory path must be given.

Samples:

PAINT "SomeTexture.JPG" BUMP "paper.TGA"

PAINT "SomeTexture.JPG" BUMP_NM "paper_nm.DDS"

 

CANBEOPENED

Used in the header part of the thing definition.

Use this statement to make the thing "openable". This activates the POS_OPEN, ROT_OPEN and SCALE_OPEN definitions. Giving a open/close value will linearly interpolate between these and the POS, ROT, SCALE values. The typical use is to make furniture objects "openable", but can also be used for other purposes.

Example:

THING

    NAME "Chest"

    CANBEOPENED

 

DIFF

Used in PAINT and LIGHT...END statements.

Sets the diffuse component of the light or material. Legal arguments are the red, green and blue values between 0 and 1. If this is used inside an animated LIGHT...END, an additional set of red, green, blue values need to be supplied.

Example:

PAINT AMB 0.5 0.5 0.5 DIFF 0.8 0.2 1 SPEC 1 1 1 POW 75

 

DIR

Used in LIGHT...END statement.

Determines the direction of the light. Legal arguments are x, y and z values between 0 and 1

Example:

LIGHT   

    DIR 0, 1, 0

    ...

 

 

FLAT

Used in the header part of the thing definition.

Declares the object to be flat. During the scaling operation in the background editor, BW Tools will only change the X/Z scaling.

Example:

THING

    FLAT

    ...

 

 

FOV

Used in LIGHT...END statement.

Determines the light cone aperture for spot lights. Legal arguments are two numeric values specifying the inner and outer angle of the light cone in degrees.

Example:

LIGHT

    FOV 45 55

 

GLOSS

Used in PAINT statements.

This modifier adds a gloss map texture to a textured and "bumped" material. The gloss map texture should be black/white. The brightness will modulate the specular reflections. If the texture file is stored at its default place in the <BW Tools Installation Folder>\ART folder ( e.g. JPG files in <BW Tools Installation Folder>\ART\JPG etc. ), no path needs to be specified. Otherwise the full directory path must be given.

Samples:

PAINT "SomeTexture.JPG" BUMP "CarBump.TGA" GLOSS "CarGloss.JPG"

 

HEIGHT

Used in BILLBOARD...END and HMDECO...END statements.

Determines the virtual height of the sprite in centimeters. Legal argument is a single numeric value.

Example:

HMDECO

    HEIGHT 150

    ...

 

HMDECO...END

Used in subpart definitions, instead of a SRF definition.

This construct creates a "heightmap decoration", i.e. a rectangular patch which will cover the ground. As the name implies, if used on a heightmap based terrain, the patch will follow the terrain elevation.

The HMDECO...END construct must be followed by a single PAINT statement, specifying a texture file (typically a TGA file with alpha channel ).

The parameters and their usage:

Number of sprites to create.

Helps to control the distribution of the sprites on a patch by encoding the available spots in a integer number. For this purpose, the patch is partitioned into an imaginary 4x4 grid. Each cell of the grid has an assigned integer value of increasing powers of 2: 1, 2, 4, 8, etc. The coverage value n is the sum of all cell values available for sprites. The default value is 65535, covering all of the patch.

Determines the virtual width of a single sprite in centimeters.

Random generator seed for the distribution of the sprites. n is an integer value. Same values cause identical distributions.

Determines the virtual height of a single sprite in centimeters.

 

Example:

_0:    HMDECO

           AMOUNT 100

           SEED 56

           WIDTH 300

           HEIGHT 200

        END

        PAINT "GRASSOLD.TGA"


 

 

LIGHT...END

Used in the header part of the thing definition.

Use this construct to create a light source to be used in a background. Depending on the supplied parameters, it is possible to create omnidirectional point lights or directional spot lights. The light ranges, colors and dynamics (e.g. flickering) can also be determined in the body of the LIGHT...END statement.

If the thing defining a light contains a subpart with a texture, this texture can be optionally projected, allowing for special effects (see PROJECT).

The parameters and their usage:

Sets the ambient component of the light. Legal arguments are the red, green and blue values between 0 and 1. If this is used inside an animated light, an additional set of red, green, blue values need to be supplied.

Sets the diffuse component of the light. Legal arguments are the red, green and blue values between 0 and 1. If this is used inside an animated light, an additional set of red, green, blue values need to be supplied.

Determines the direction of the light. The arguments x, y and z are the direction normal.

Determines the light cone aperture for spot lights. i and o specify the inner and outer angle of the light cone in degrees respectively.

If specifies, the light will not cast any shadows.

n specifies the distance of the projector from the center of the thing in centimeters.This is a useful option for projected spot lights. The legal argument is a single numeric value specifying a projector offset from the center of the thing in centimeters.

Specifies the offset of the light source in centimeters from the center of the thing.

n is the index number of a textured subpart of the thing. This texture will be projected into the scene.

n is the near starting distance of the light, ne is the near penumbra width, f the end distance and fe the far penumbra width. All values are in centimeters.

Sets the specular component of the light. Legal arguments are the red, green and blue values between 0 and 1. If this is used inside an animated light, an additional set of red, green, blue values need to be supplied.

For tangential spot lights, h and v are the horizontal and vertical rotations in degrees. This requires the TANGENTIAL flag for the whole thing.

Used to create animated lights. Possible values for t are:

  • STEADY: Non-animated.
  • SINUS FAST, SINUS NORMAL or SINUS SLOW: Sinusoidal change between the specified light values.
  • RANDOM FAST, RANDOM NORMAL or RANDOM SLOW: Random jumps between the specified light values.

 

Sample point light:

LIGHT

    POS    0, 50, 0

    RANGE 10 1 2000 50    // near, near edge, far, far edge

    DIFF 0.6 0.2 0.0

    SPEC 0.5 0.5 0.5

END

Sample spot light:

LIGHT

    DIR 0, 1, 0

    RANGE 10 1 2000 50    // near, near edge, far, far edge

    FOV 45 55             // light cone inner angle, outer angle

    DIFF 1,1,1

    SPEC 1,1,1
END
 

 

NAME

Used in the header part of the thing definition.

Use this to give a name to your thing. This name will be the name displayed in the background editor and need not to be identical to the thing file name.

Example:

THING

    NAME "Chair"

 

NOCULL

Used in subpart definitions.

If defined, the mesh of the specified subpart will not be culled, i.e. the polygons will also be visible from the "wrong" side.

Example:

_0:    SRF "Leaf.3ds"

       NOCULL

 

NONORGANIC

Used in SRF definitions.

Use this modifier to change the automatic tangent vector calculation to be hard-edged ("nonorganic")

Example:

SRF "BigAngularBox.X" NONORGANIC

 

NOSHADOW

Used in the header part of the thing definition and in LIGHT...END definitions.

If used as header, the object will not have a shadow. If used inside a LIGHT...END construct, the light will not cast any shadows.

Example:

THING

    NOSHADOW

 

NOZBUF

Used in subpart definitions.

If defined, the polygons of the specified will be rendered while ignoring the Z buffer.

Example:

_0:    SRF "head.3ds"

       NOZBUF

 

NOZWRITE

Used in subpart definitions.

If defined, the polygons of the specified will be rendered without writing to the Z buffer

Example:

_0:    SRF "head.3ds"

       NOZWRITE

 

OFFSET

Used in LIGHT...END statement.

This is a useful option for projected spot lights. The legal argument is a single numeric value specifying a projector offset from the center of the thing in centimeters.

Example:

LIGHT

    PROJECT 0

    OFFSET -100

 

ORGANIC

Used in SRF definitions.

Use this modifier to change the automatic tangent vector calculation to be soft-edged ("organic")

Example:

SRF "Apple.X" ORGANIC

 

 

ORIGIN

Used in subpart definitions.

The origin specifies a new pivot point for the subpart. If this is not specified, the geometric center will be used. Legal values are three numbers defining x, y and z offsets from the center in centimeters.

Example:

_0:    ORIGIN 0 10 0

       SRF "SomeObj.3ds"

 

PAINT

Used in subpart definitions.

This statement determines the material of the subpart. There are several variants of usage:

A material file, created with the material editor and stored in <BW Tools Installation Folder>\Resources\Materials folder, can be specified like this:

PAINT "ShinyRed.material"

or

PAINT "Ground\Tiling A.material"

Please observe that the immediate folder name containing the material must be supplied, but not the full path.

                    An untextured material can be created by specifying the ambient, diffuse and specular RGB components:

PAINT AMB 0.5 0.5 0.5 DIFF 0.8 0.2 1 SPEC 1 1 1 POW 75

If the texture files are stored at their default places in the <BW Tools Installation Folder>\ART folder ( e.g. JPG files in <BW Tools Installation Folder>\ART\JPG etc. ), no path needs to be specified. Otherwise the full directory path must be given.

The system supports BMP, JPG, PNG, TGA and DDS file formats.

There are many possible combinations. Here are some examples...

Simple texture mapping (diffuse map)

PAINT "SomeTexture.JPG"

Texture map with additional material properties

PAINT "SomeTexture.JPG" DIFF 1 0 0 SPEC 1 1 1 POW 50

Texture map with bump map texture. The bump map is a black/white height map

PAINT "SomeTexture.JPG" BUMP "Scratches.TGA"

Texture map with bump map texture. The bump map is a normal map.

PAINT "SomeTexture.JPG" BUMP_NM "paper_nm.DDS"

Texture map with bump and gloss map textures

PAINT "SomeTexture.JPG" BUMP "Scratches.TGA" GLOSS "Shiny.bmp"

Transparent texture

PAINT ALPHA 0.5 "SomeTexture.JPG"

 

PARSYS...END

Used in subpart definitions, instead of a SRF definition.

This is a rather complex construct for the creation of particle systems, traditionally used for fire, smoke etc. effects. The PARSYS...END construct must be followed by a single PAINT statement, specifying a texture file (typically a TGA file with alpha channel ).

The parameters and their usage:

Number of simultaneously active particles.

If the used particle sprite has an alpha channel, you can change the blending operation with this modifier. Otherwise the black parts of the texture will be rendered as transparent.

The emit position will be between -x/-y/-z and x/y/z

n is the particle emit rate in particles/second. f is a normalized percentual variation factor between 0 and 1.

This specifies the color of a particle at the end of its life cycle. A color between the r0g0b0a0 and r1g1b1a1 will be randomly assigned.

n is the size of a particle in centimeters  at the end of its life cycle. f is a normalized percentual variation factor between 0 and 1.

The gravity vector. Typically 0 -1 0.

n is the lifetime of a particle in seconds. f is a normalized percentual variation factor between 0 and 1.

n is the size of a particle in centimeters. f is a normalized percentual variation factor between 0 and 1. Use this statement instead of STARTSIZE/ENDSIZE if the size of a particle doesn't change over its lifetime.

The spawn direction for new particles. The system will randomly choose a value between x0y0z0 and x1y1z1.

This specifies the color of a particle at the beginning of its life cycle. A color between the r0g0b0a0 and r1g1b1a1 will be randomly assigned.

n is the size of a particle in centimeters  at the beginning of its life cycle. f is a normalized percentual variation factor between 0 and 1.

Example:

_0: PARSYS

        AMOUNT 100

        GRAVITY 0 -1 0

        EMITRATE 10 0.2

        LIFETIME 1 0.1

        SIZE 30 0.1

        STARTCOLOR 1 1 1 1 , 0.8 0.8 0.2 0.8

        ENDCOLOR 0.8 0 0 0.5 , 0 0 0 0

        SPAWNDIR 0 50 0 , 0 50 0

        EMITRADIUS 1 1 1

    END

    PAINT "SMOKE.JPG"

 

POS

Used in subpart definitions and in the header part of the thing definition.

This statement determines the relative offset a subpart in centimeters from the center of the thing. Legal arguments are three numbers for x, y and z dimensions.

If used in the header part, the whole thing itself will be translated.

Example:

_0:    POS 0 10 0

       SRF "SomeMesh.SRX"

 

POS_OPEN

Used in subpart definitions.

This statement determines the relative offset a subpart in centimeters from the center of the thing for open/close factor = 1. In other words, the open/close factor is the linear interpolation factor between POS and POS_OPEN.

The thing must have a CANBEOPENED statement in its header.

Example:

_0:    POS 0 10 0

       POS_OPEN 0 110 0

       SRF "SlidingDoor.SRX"

 

POW

Used in PAINT statements.

Sets the power value for the specular component of the material, determining the sharpness of the reflection. Legal argument is a single numeric value. Use higher values for sharper reflections.

Example:

PAINT AMB 0.5 0.5 0.5 DIFF 0.8 0.2 1 SPEC 1 1 1 POW 75

 

PRELIT      

Used in subpart definitions.

Turns off the lighting for the given subpart. This can be useful for simulating light-emitting objects.

Example:

_0:    SRF "TheLight.3DS"

       PAINT AMB 1 1 1

       PRELIT

 

ROT

Used in subpart definitions and in the header part of the thing definition.

This statement determines the rotation of the subpart around a pivot point. Legal arguments are three numbers specifying the rotation degrees around x, y and z axes. The pivot point is the center of the subpart, unless an ORIGIN statement is used.

If used in the header part, the whole thing itself will be rotated.

Example:

_0:    ROT 45 0 0

       SRF "SomeMesh.SRX"

 

ROT_OPEN

Used in subpart definitions.

This statement determines the rotation of the subpart around a pivot point for open/close factor = 1. In other words, the open/close factor is the linear interpolation factor between ROT and ROT_OPEN.

The thing must have a CANBEOPENED statement in its header.

Example:

_0:    ROT 0 0 0

       ROT_OPEN 0 120 0

       SRF "Door.SRX"

 

SCALE

Used in subpart definitions and in the header part of the thing definition.

This state determines the scaling of the subpart. Legal arguments are three numbers specifying the x, y and z direction scaling.

If used in the header part, the whole thing itself will be scaled.

Example:

_0:    SCALE 1 2 1

       SRF "SomeObject.3DS"

 

SCALE_OPEN

Used in subpart definitions.

This statement determines the scaling of the subpart  for open/close factor = 1. In other words, the open/close factor is the linear interpolation factor between SCALE and SCALE_OPEN.

The thing must have a CANBEOPENED statement in its header.

Example:

_0:    SCALE 1 2 1

       SCALE_OPEN 1 1 1

       SRF "SomeObject.3DS"

 

 

SPEC

Used in PAINT and LIGHT...END statements.

Sets the specular component of the light or material. Legal arguments are the red, green and blue values between 0 and 1. If this is used inside an animated LIGHT...END, an additional set of red, green, blue values need to be supplied.

Example:

PAINT AMB 0.5 0.5 0.5 DIFF 0.8 0.2 1 SPEC 1 1 1 POW 75

 

SRF

Used in subpart definitions.

This statement determines the geometry of the subpart. There are two main variants of usage:

If the mesh files are stored at their default places in the <BW Tools Installation Folder>\ART folder ( e.g. 3DS files in <BW Tools Installation Folder>\ART\3DS etc.), no path needs to be specified. Otherwise the full directory path must be given.

The system supports X, SRX and 3DS file formats. A file must contain a single mesh without transformations.

Two special modifiers are available:

  • KEEPDIM: This is a flag to instruct the assembly compiler to use the original dimensions of a mesh file. If this flag is not specified, the system will fit the mesh into a box with standard dimensions (100 cm x 100 cm x 100 cm ).
  • KEEPNORMAL: This is a flag to instruct the assembly compiler to use the original vertex normals of a mesh file. If this flag is not specified, the system will automatically recreate the normals.

Example:

SRF "SomeMesh.3DS" KEEPDIM

 

These are meshes created algorithmically by the system. These objects are always fitted into a box with standard dimensions (100 cm x 100 cm x 100 cm ).

Creates a cube

Example:

SRF "*BOX"

 

Creates a cylinder

Example:

SRF "*CYLINDER"

 

Creates four quadrilaterals arranged as a frame

Example:

SRF "*FRAME"

 

Creates a generalized cylinder, i.e. a 3D line with thickness. The first argument is the number of the total points and must be >= 2. Then the list of point x, y and z coordinates follow. The next argument is the radius, defining the thickness. Axial tile size determine the tiling steps along the cylinder. Smoothing flag can be 0 or 1. The final value is a quality parameter between 0 and 100.

Example:

SRF "*GENCYL(3, 0,0,0 ,0,50,0, 50,70,0, 10, 30, 0, 75)"

 

Creates a quadrilateral

Example:

SRF "*QUAD"

 

Creates a sphere

Example:

SRF "*SPHERE"

 

Creates a 3D text object.

The first argument is the text itself. The additional arguments can be used to modify the font.

Example:

SRF "*TEXT(Hello World,Times New Roman,16)"

 

 

TANGENTIAL

Used in the header part of the thing definition.

If this is specified, the the will automatically change its orientation to be tangential to the walls etc. Useful for paintings, windows and similar.

Example:

THING

    NAME "Mona Lisa"

    TANGENTIAL

 

TEXMAPMOD

Used in subpart definitions.

This statement allows the manipulation of the texture mapping coordinates by offsetting and scaling. It requires four numeric arguments specifying u-scale, v-scale, u-offset and v-offset.

Example:

_0:    SRF "SomeBody.3ds"

       PAINT "SomeTexture.JPG"

       TEXMAPMOD 1 2 0 0

 

WIDTH

Used in BILLBOARD...END and HMDECO...END statements.

Determines the virtual width of the sprite in centimeters. Legal argument is a single numeric value.

Example:

HMDECO

    WIDTH 150

    ...

previous//next//start


Would you like to provide us with your comments on this topic?