### Scene Files November 9, 2001 This document describes the LWSC version 3 file format for 3D scenes used by LightWave® 6.0 and later. At this point, it's an incomplete rough draft that's missing descriptions of most of the keywords. But the introductory information will allow you to parse the file at least, and the semantics of most of the keywords can be deduced. If you've worked with version 1 of the format (version 2 was an unreleased interim format), version 3 will seem quite familiar. Scene files are still text files containing keyword-value pairs. The most important difference is in the way keyframe data is stored, but obviously there are many others comprising features not available in LightWave® prior to 6.0. Item Numbers When a scene file needs to refer to specific items to establish item relationships (parenting, for example), it uses item numbers. Items are numbered in the order in which they appear in the file, starting with 0. Item numbers can be written in one of two ways, depending on which keyword they're used with. In general, if the type of the item (object, bone, light, camera) can be determined from the keyword alone, the item number will simply be the ordinal, written as a decimal integer. When the keyword can be used with items of more than one type, the item number is an unsigned integer written as an 8-digit hexadecimal string, the format produced by the C-language `"%8X"` print format specifier, and the high bits identify the item type. The first hex digit (most significant 4 bits) of the hex item number string identifies the item type. 1 - Object 2 - Light 3 - Camera 4 - Bone The other digits make up the item number, except in the case of bones. For bones, the next 3 digits (bits 16-27) are the bone number and the last 4 digits (bits 0-15) are the object number for the object the bone belongs to. Some examples: `10000000` - the first object `20000000` - the first light `4024000A` - the 37th bone (24 hex) in the 11th object (0A hex) Blocks Information in a scene file is organized into blocks, the ASCII text analog of the chunks described in the IFF specification. Each block consists of an identifier or name followed by some data. The format of the data is determined by the block name. Block names resemble C-style identifiers. In particular, they never contain spaces or other non-alphanumeric characters. A single-line block is delimited by the newline that terminates the line. Multiline blocks are delimited by curly braces (the { and } characters, ASCII codes 123 and 125). The name of a multiline block follows the opening curly brace on the same line. The curly brace and the name are separated by a single space. The data follows on one or more subsequent lines. Each line of data is indented using two spaces. The closing brace is on a line by itself and is not indented. Individual data elements are separated from each other by a single space. String data elements are enclosed in double quotes and may contain spaces. Blocks can be nested. In other words, the data of a block can include other blocks. A block that contains nested blocks is always a multiline block. At each nesting level, the indention of the data is incremented by two additional spaces.
       SingleLineBlock data
       { MultiLineBlock
         data
         { NestedMultiLineBlock
           data
         }
       }
Envelopes An envelope defines a function of time. For any animation time, an envelope's parameters can be combined to generate a value at that time. Envelopes are used to store position coordinates, rotation angles, scale factors, camera zoom, light intensity, texture parameters, and anything else that can vary over time. The envelope function is a piecewise polynomial curve. The function is tabulated at specific points, called keys. The curve segment between two adjacent keys is called a span, and values on the span are calculated by interpolating between the keys. The interpolation can be linear, cubic, or stepped, and it can be different for each span. The value of the function before the first key and after the last key is calculated by extrapolation. In scene files, an envelope is stored in a block named `Envelope` that contains one or more nested `Key` blocks and one `Behaviors` block.
       { Envelope
         nkeys
         Key value time spantype p1 p2 p3 p4 p5 p6
         Key ...
         Behaviors pre post
       }
  > The `nkeys` value is an integer, the number of `Key` blocks in the envelope. Envelopes must contain at least one `Key` block. The contents of a `Key` block are as follows. `value` The key value, a floating-point number. The units and limits of the value depend on what parameter the envelope represents. `time` The time in seconds, a float. This can be negative, zero or positive. Keys are listed in the envelope in increasing time order. `spantype` The curve type, an integer. This determines the kind of interpolation that will be performed on the span between this key and the previous key, and also indicates what interpolation parameters are stored for the key. 0 - TCB (Kochanek-Bartels) 1 - Hermite 2 - 1D Bezier (obsolete, equivalent to Hermite) 3 - Linear 4 - Stepped 5 - 2D Bezier `p1...p6` Curve parameters. The data depends on the span type. TCB, Hermite, 1D Bezier The first three parameters are tension, continuity and bias. The fourth and fifth parameters are the incoming and outgoing tangents. The sixth parameter is ignored and should be 0. Use the first three to evaluate TCB spans, and the other two to evaluate Hermite spans. 2D Bezier The first two parameters are the incoming time and value, and the second two are the outgoing time and value. The `Behaviors` block contains two integers. `pre, post` Pre- and post-behaviors. These determine how the envelope is extrapolated at times before the first key and after the last one. 0 - Reset Sets the value to 0.0. 1 - Constant Sets the value to the value at the nearest key. 2 - Repeat Repeats the interval between the first and last keys (the primary interval). 3 - Oscillate Like Repeat, but alternating copies of the primary interval are time-reversed. 4 - Offset Repeat Like Repeat, but offset by the difference between the values of the first and last keys. 5 - Linear Linearly extrapolates the value based on the tangent at the nearest key. The source code in the sample/envelope directory of the LightWave® plug-in SDK demonstrates how envelopes are evaluated. Scene `FirstFrame nfirst LastFrame nlast FrameStep nstep` The frame range and step size for rendering. In the simplest case, the first frame and frame step are 1, and the last frame is the number of frames to be rendered. `PreviewFirstFrame nfirst PreviewLastFrame nlast PreviewFrameStep nstep` The frame range and step size for previewing. These may be unrelated to the values for rendering. They also control the visible ranges of certain interface elements, for example the frame slider in the main window. `CurrentFrame nframe` The frame displayed in the interface when the scene is loaded. `FramesPerSecond gframes` This controls the duration of each frame. Objects `LoadObjectLayer nlayer sfilename` Begins a group of statements about an object. The layer number is the index recorded in the LAYR chunk of the object file. `ShowObject nvisibility ncolor` Determines how the object is displayed in the interface. The visibility codes are 0 - hidden 1 - bounding box 2 - vertices only 3 - wireframe 4 - front face wireframe 5 - shaded solid 6 - textured shaded solid The color used to draw bounding boxes, vertices and wireframes can be one of the following.
  > 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14
The default visibility and color are stored in the config file. If they haven't been altered by the user, they are textured shaded solid (6) and cyan (3) in LightWave® 6.5. `ObjectMotion NumChannels nchannels Channel nindex { Envelope ...` The `ObjectMotion` keyword signals the start of the motion information for the object. Motions are stored in envelopes, one for each motion channel. There are 9 standard channels, numbered from 0 to 8. 0, 1, 2 - (x, y, z) position 3, 4, 5 - (heading, pitch, bank) rotation 6, 7, 8 - (sx, sy, sz) scale factors along each axis The values of all of these are relative to the object's parent, if it has one. `UseBonesFrom 1` . `Plugin sclass nlistpos sname EndPlugin` Lists an object plug-in. The class can be `MorphAmount MorphTarget MorphSurfaces MTSEMorphing` . `DisplacementMaps { TextureBlock ...` . `ClipMaps { TextureBlock ...` . `ObjectDissolve` . `DistanceDissolve` . `MaxDissolveDistance` . `AffectedByFog` . `UnseenByRays` . `UnseenByCamera` . `ShadowOptions` . `ExcludeLight` . `PolygonEdgeFlags` . `PolygonEdgeThickness` . `PolygonEdgeColor` . `PolygonEdgesZScale` . `EdgeNominalDistance` .