TeslaRel410/dpl3-revive/spec/SCN_FORMAT.md

.SCN scene format

Reverse-engineered from DPL3/EXAMPLES/FLYK.C (the flythrough viewer) and DPL3/MATRIX.C. .SCN is plain text, one command per line, whitespace- delimited. Comments start with // or #. It assembles a world by referencing models (.B2Z) and textures (.SVT) by name — it embeds no geometry itself.

Core commands (the FLYK subset)

These cover the overwhelming majority of every scene on the disk (STATIC alone is ~5,000 of ~9,000 command lines):

Command	Arguments	Meaning
FOG	z0 z1 r g b	linear fog: start/end distance + colour
BACKGND	r g b	background / clear colour
AMBIENT	r g b	ambient light
LIGHT	r g b ax ay az	directional light: colour + orientation angles (deg)
STATIC	name scale x y z ax ay az	place a model instance
DYNAMIC	name scale splinefile t0 dt	model that follows a camera-path spline
SSTATIC	(as STATIC)	static variant
SCROLL	texname u0 v0 du dv	UV drift on a TEXTURE entity (see below)

Colours are floats in 0..1. Distances/positions are world units. Angles are in degrees. name is resolved to a geometry file by search path (see Resolution).

Instance transform

From FLYK.C + MATRIX.C. DPL uses a row-vector convention — a point is a row and transforms as p' = p · M, with translation in the bottom row of the matrix and each op post-multiplied (M = M · op). STATIC builds:

M = Rz(az) · Rx(ax) · Ry(ay) · Scale(s) · Translate(x, y, z)
p_world = [x y z 1] · M

so a point is rotated (Z, then X, then Y), scaled, then translated into place. Rotation matrices (row-vector form, c=cos, s=sin):

Rz = [ c  s  0 0]   Rx = [1  0  0 0]   Ry = [c  0 -s 0]
     [-s  c  0 0]        [0  c  s 0]        [0  1  0 0]
     [ 0  0  1 0]        [0 -s  c 0]        [s  0  c 0]
     [ 0  0  0 1]        [0  0  0 1]        [0  0  0 1]

LIGHT's three angles orient a directional light the same way (Rz·Rx·Ry).

Asset resolution

• Models: name → <name>.B2Z (also .BIZ/.V2Z), found on a search path (originally the GEOMETRY env var; here: index of the archive by basename).

• Materials & textures (authoritative): a geogroup carries a material name (e.g. redrock_mtl). The real definition lives in the model's .V2Z source (the verbose text twin of the binary .B2Z — magic DIV-VIZ2), which inlines its material library:

  TEXTURE(NAME=redrock_tex) { MAP {"rocknoiz"} ... }
  MATERIAL(NAME=redrock_mtl) { TEXTURE {redrock_tex}  DIFFUSE {0.743, 0.216, 0.202} }
  

  So a material = a texture (→ <map>.SVT) modulated by a DIFFUSE colour. The final surface colour is texel × diffuse × lighting. Material names are scoped per model (the same name can differ between themes), so each model's own .V2Z is the source of truth — parser/bundle parse it per model.

  • Two kinds of texture, handled differently:
    • Full-colour painted skins (vehicle textures like VTVCAB) are shown as-is (tint = white); their colour lives in the texels.
    • Greyscale / intensity "noise" maps (CANAL, ROCKNOIZ) are tinted by the material diffuse — techy (white) × CANAL = grey concrete, rednoise (red) × CANAL = red pipes. Some (e.g. CANAL, VTVALL) have a dead colour channel and are rebuilt as luminance first. The loader auto-classifies by saturation.
  • Prefer the material's per-part skin <stem>.SVT (e.g. vtvcab_mtl → VTVCAB.SVT) over any atlas the material names (vtvall) — the per-part skins match the model UVs; the atlas tinted by diffuse does not.
  • Pair geometry and materials from the same source directory. The same asset exists in several theme folders (CONVERT/THOR/, CONVERT/CANALS/, …) and the same material name is defined with different colours in each (THOR rednoise = vivid red 0.83,0.006,0.006; CANALS = salmon 0.69,0.41,0.40). Loading .B2Z from one folder but .V2Z from another mixes them and yields the wrong colour. bundle.v2z_for() resolves the sibling .V2Z first.
  • Fallback: only when a model has no .V2Z do we fall back to the old stem/keyword heuristics.

Output gamma (the Division DAC)

Material/diffuse values are linear. The Division i860/pxpl5 card output through a 10-bit DAC with a gamma-1.7 encode — from DPL3/GAMMA.C, which builds a 256→1023 table out = 1023 · (i/255)^(1/1.7). This brightens midtones and gives the characteristic bright/pastel look. The viewer reproduces it by applying colour^(1/1.7) as the final fragment step (and to the background clear). Without it, linear output on an sRGB display looks too dark and over-saturated.

Surface merging (a bug worth noting)

When baking a scene, geometry is merged into surfaces to cut draw calls. Surfaces must be keyed on (texture, diffuse-colour), not texture alone — otherwise two materials that share a texture but differ in tint (grey columns vs red pipes, both on CANAL.SVT) merge into one and the second colour is lost. This was the cause of "the pipes render grey".

Scrolling textures (SCROLL)

SCROLL <texname> u0 v0 du dv        e.g.  SCROLL btfx:firesmoke1_scr_tex 0 0 0.05 -0.331

Animates a texture's UV coordinates — flowing water, drifting smoke, rising fire, laser-beam flow (287 uses across the disk). texname addresses a TEXTURE entity (not a bitmap): either lib:name in a named material library (.VMF/.BMF) or a plain name from the model's own .V2Z/.VGF source. u0 v0 is the initial offset, du dv the drift rate — the viewer plays it as UV/second (rate units are inferred; the engine source for this path is not on the disk).

The scene command is actually an override: the same data is baked into the texture entity itself as a SPECIAL hook in the material source —

TEXTURE(NAME="firesmoke1_scr_tex";SPECIAL=" SCROLL  0 0 0.05 -0.331 \0x00")
{ MAP {"bintA"} }

so a texture scrolls even in scenes/maps with no SCROLL line, and several entities can share one bitmap (bintA) at different rates. In the binary .BMF form the SPECIAL string is texture sub-block tag 0x037 (see B2Z_FORMAT §7). Scroll is a per-texture-entity property, so the baker keys animated surfaces on the entity, not the bitmap.

Extended commands (game-tool scenes)

Larger scenes authored by the game tools use more keywords. The current loader recognises and skips these; they are documented here for completeness:

MORPH (animated geometry) · SPECIALFX (particle/effect hooks) · TEXTURE / GEOMETRY / MATERIAL / RAMP (explicit asset declarations) · ZONE / START / END (zone blocks) · CLIP (near/far clip) · VIEWANGLE (fov) · TRACKER / RETRACE / KEYRATE / GEOMETRIZE / IMMUNE / DRAWLAST / NOVIEWMATRIX / BILLBOARD.

Validation

parser/scn.py parses CANAL.SCN → fog, background, ambient, 1 light, 47 instances (5 unique models, all resolved). viewer/bundle.py assembles it into world space and renders it: a Red Planet canal — 22 red-rock cliff segments lining a channel, 22 struts, a VTV "mule" vehicle, rock and tech-junk — with reddish fog. See viewer/preview_scene.png.