Models & moving pieces

A model you can take apart

A .3do file stores a model as a hierarchy of named pieces. Each piece owns its vertices, faces, and a translation from its parent. Pieces can form a chassis, turret, barrel, articulated limb, or even an invisible point where an effect begins.

Explore a 3DO

One model. Five connected pieces.

EXAMPLE.3DO / AUTHORING SPACE

Models live under objects3d/. A unit’s ObjectName selects its model. Its corpse reference selects a feature definition, whose object names the wreck model. Names such as <unitname>.3do and <unitname>_dead.3do are conventions, not lookup rules. See the FBI and TDF references.

Follow the object tree

There is no separate file header. The root is an ordinary 52-byte object record at file offset 0. Each record points to its name, vertex array, primitive array, first child, and next sibling. All integers are little-endian; all stored offsets are absolute from the start of the file.

Object @ 0x0000  (52 bytes)
  name pointer ───────► NUL-terminated piece name
  vertices pointer ──► Vertex[n]       (12 bytes each)
  primitives pointer ► Primitive[m]   (32 bytes each)
                         indexes ────► u16[k], local to this piece
                         texture ────► GAF entry name, or 0
  child pointer ─────► first child Object
  sibling pointer ───► next Object with the same parent

Children of one parent form a linked list through their sibling pointers. Zero terminates a child or sibling link. The decoder also accepts a root sibling chain; the layout does not prohibit one. Names, arrays and other objects can appear elsewhere in the file. Follow their pointers instead of assuming an exporter’s packing order.

Piece anatomy

Local translations add along the chain

base
├── turret       (+0, +8, +0)
│   └── barrel   (+0, +3, −5)
│       └── flare (+0, +0, −15)
└── mast         (−8, +8, +8)

flare origin in bind pose(0, 8, 0) + (0, 3, −5) + (0, 0, −15)= (0, 11, −20)

Without runtime rotations, summing parent translations places each piece’s origin in the file’s bind-pose coordinate system. The flare in this example is at (0, 11, −20). That is not a world position: it has not yet gone through runtime import, piece animation, unit orientation, or world placement.

A piece with one vertex and no primitives is useful. It has a position but no surface to draw. Such pieces commonly locate muzzle flashes, smoke, nano spray, thrust, or factory build pads. Select flare in the inspector to see one.

Byte layouts

The following offsets are relative to each record. i32 is signed; u32 and u16 are unsigned. Each pointer targets an absolute file offset. Vertex positions and piece translations use signed 16.16 fixed point.

Object record · 52 bytes

Scroll table horizontally to see all fields →

Vertex record · 12 bytes

Scroll table horizontally to see all fields →

Decode a coordinate as signed_integer / 65536. The sign belongs to the whole 32-bit word; do not interpret the fractional half independently. For example:

Primitives share vertices within their own piece through index arrays. An index never names a vertex in another piece. A lossless decoder retains authored coordinates; the runtime import conversion is a later step.

Primitive record · 32 bytes

Scroll table horizontally to see all fields →

Strings and packing

Object and texture names are NUL-terminated strings and can appear anywhere their pointers address. One observed exporter layout puts a texture-name pool immediately after the root, then indexes, vertices, primitives, and additional objects. That is an observation, not a format constraint. Records need not be aligned to four-byte boundaries; the authored fixture’s vertex array starts at 0x0109.

Faces and implied texture corners

A texture name refers to an entry in a GAF under textures/. The name identifies image data; the 3DO does not embed it. Read the GAF guide for named entries and frames, or the palette reference for indexed colors and lookup tables.

For a textured quad, the established default corner assignment is:

Interactive example

The index order turns the texture

Texture entry · 160 × 160

Each quad corner receives a texture corner.

Face · viewed straight on

v0v1v2v3

Index order [0, 1, 2, 3] → A, B, C, D.

A cyclic reordering preserves winding but changes which geometric vertex receives (0, 0). This diagram shows corner assignment; it does not simulate culling, shading or scanline rounding.

Runtime dispatch is a separate contract

The bounded rendering research establishes the following branch behavior. These are runtime rules, not additional records in the file:

The loader owns resolve-at-draw-time and team flags. The owner’s color index can select a complete LOGOS.GAF frame; see GAF team textures. Do not infer runtime precedence from a texture name alone, or from the complete integer value of IsColored.

The model stores no normals. Normal construction, renderer selection, SHD rows, dont-shade, affine sampling and culling belong to the behavioral reference. The inspector above uses neutral face contrast for readability; it does not preview those retail shading operations. Stored polygon counts are also not triangulation advice: retail’s established path does not first fan-triangulate every face.

The selection primitive

The selection field designates a face in its own piece. Retail normalizes this field on every piece, not just the root. Its drawing and picking consumers live in the behavioral specification.

In the original crawler, root selection value 0 designates the first face: a flat X/Z quadrilateral at Y = 0. Toggle Selection plate in the inspector to overlay it. The overlay is a visualization of the reference; it does not claim that the engine renders that face with a translucent green material.

A separate census cross-referenced 278 winning unit definitions to 278 unique models, excluding wrecks, projectiles and map features. All had at least one flat root X/Z quad. Among them, 167 selected primitive 0, 109 selected a positive index, and two (armmstor, cormine1) stored −1 despite still containing a flat primitive-zero plate.

Coordinates: authored, imported, world

A 3DO’s authored coordinates are Y-up. Retail then persistently negates both X and Z, for vertices and parent translations: a half-turn about Y. After composition, a model-space offset (x, y, z) maps to world offset (x, y, −z). These are two separate operations.

Supported inference: a common authoring convention puts the nose toward −Z. A recorded locator census found negative local Z for flare* translations 135 times, versus positive Z 13 times. That supports an asset convention, not a mandatory forward axis. Historical documentation also described +Z-forward; preserve the distinction between convention and the established runtime transform.

The 16.16 interpretation matches the surveyed data, but the research identifies no vendor statement of that scale. BOS/COB linear script values use another scale: 1 BOS unit = 2.5 model units. See the COB reference.

A file you can inspect

Download example.3do · 3,750 bytes and its decoded model and offset manifest. The manifest includes all five records, the local geometry, raw primitive fields represented by the fixture, and the original display palette. Nothing in the download depends on retail data.

This fixture puts five object records first, followed by each piece’s names and arrays. The root’s first 52 bytes are the root object itself:

01 00 00 00  24 00 00 00  19 00 00 00  00 00 00 00
00 00 00 00  00 00 00 00  00 00 00 00  04 01 00 00
00 00 00 00  09 01 00 00  B9 02 00 00  00 00 00 00
34 00 00 00

Read those words as version 1, 36 vertices, 25 primitives, selection index 0, zero translation, name at 0x0104, zero auxiliary offset, vertices at 0x0109, primitives at 0x02B9, no root sibling, and first child at 0x0034.

The first vertex at 0x0109 is:

00 00 EF FF  00 00 00 00  00 00 EA FF

That is (-1114112, 0, -1441792) as signed integers, or (−17, 0, −22) model units. The selection face’s index array is [0, 1, 2, 3], so this is one corner of its flat plate. The turret’s sibling pointer reaches the mast; its child pointer reaches the barrel. The barrel’s child reaches the one-vertex flare.

The website’s scripts/3do-example.py writes the fixture, independently follows its pointers and index arrays, and generates the images and manifest from the decoded result. --check validates the committed outputs, including fixed-point quantization. The page does not use the publication-omitted retail byte dumps.

Loading, ordering and measured bounds

Retail reads the file whole. A missing or zero-length model is fatal, with the path shown, whether a unit, weapon, or feature names it. The loader relocates names and auxiliary offsets when nonzero, array offsets unconditionally, and child and sibling links recursively. It also relocates the primitive offsets. These operations are unbounded, and the relocator has no visited set.

Primitive compilation is runtime behavior. The loader normalizes selection and creates an ordered view using its established ordering and arithmetic. A lossless parser should retain authored primitive order and the original selection field; a runtime compiler can create a separate ordered representation. Do not bake runtime sorting into the stored-format interpretation.

The model-top walk is not an ordinary bounding box

Established: the definition’s upper Y bound is measured by a recursive sibling-chain walk. Each invocation starts top = 0. It considers every vertex.y + piece.translation.y. For children, it recursively computes a fresh child maximum, adds the parent piece’s own Y translation, and compares again. Additions wrap to signed 32 bits; comparisons are signed.

Zero is a floor at each recursive level. A small constructed example shows why that matters:

The measured top is 10, although the only vertex reaches 5. The walk reads no script orientation and has no minimum-vertex-count gate. This example illustrates the specified arithmetic; it is separate from the downloadable model.

Host policy and remaining unknowns

Checked decoding and encoding

Retail has no corresponding aggregate budgets and does not check selection or vertex indexes before the ordering pass. A zero-index face reaching comparison in that pass can cause signed division by zero. Checked decoders may reject those malformed inputs instead of reproducing unsafe access. These are implementation acceptance boundaries, not file-format maxima.

Winding, flags and stock distributions

The recorded signed-volume census of 608 base models found 2,029 pieces with outward right-handed winding and 90 with inward winding. Signed volume establishes orientation for closed pieces; it does not by itself label an open piece defective. Runtime culling must come from the behavioral contract.

These censuses describe their specified reference populations. They are evidence about shipped assets, not constraints on all authored files.

Piece names link the model to its script

Common names include base, turret, barrel1, flare1, pelvis, torso, lfoot, rfoot, nano1, pad, and door1. They connect authored model pieces with script queries, motion, and effects. Ship wake* and aircraft thrust locators often have a single vertex and no primitives; wrecks conventionally use names such as ground, wreck, or gp.

The format does not enforce those names. SMOKEPIECE is an authored helper convention. The engine’s SweetSpot query seeds piece index zero, which need not be named base. A parser should preserve names rather than infer fixed behavior from them.

Sources and evidence

This guide adapts the 3DO research at commit 1ef7b91, with a complete plain-text snapshot. It retains the source’s distinction between established byte layouts, bounded asset observations, supported inferences, unknowns, and Nanolathe policy. The texture-corner and span-writer explanations also use the owning behavioral reference at that same revision.

The source research also cites the inspected 3DOBuilder writers for their zero auxiliary fields and a 761-model base/expansion survey. Those findings do not recover the meaning of arbitrary auxiliary targets.

Continue with GAF images and animations, COB unit scripts, or FBI unit definitions.