# `.MAP` game maps and `.MOD` game objects

The **actual playable game worlds** — BattleTech arenas and Red Planet tracks —
live in the game trees' `MAPS/` directories (`BTDAVE`, `BTLIVE`, `BTRAVINE`,
`RPDAVE`, `RPLIVE`), not in `.SCN` files. Reverse-engineered from the files
themselves (INI-style text; ~50 maps, ~13,000 instance placements archive-wide).

## `.MAP`

Sections declare assets; a `type=map` section places them:

```ini
[hall2]                     ; asset declaration
type=model
modelfile=hall2.mod
[one]
type=dropzone               ; pod spawn ring
dropzone= x y z  rx ry rz   ; rotations in RADIANS
[arena1]                    ; the map itself (usually named like the file)
type=map
instance=hall2  x y z  rx ry rz
instancedropzone=one  x y z  rx ry rz
[inc]
type=include                ; merge another .MAP's sections
file=other.map
```

- `instance=` may reference a **model or another map section** — maps nest, with
  transform composition (row-vector, `Rz·Rx·Ry·T`, unit scale — the SCN transform
  with radians instead of degrees).
- The root map section is the one named like the file (fallback: the map-typed
  section with the most instances).
- Comments: `//`. A leading `[LAB_ONLY]` marks unreleased content.

## `.MOD` (game object)

```ini
[video]
object=rb3.bgf              ; render geometry (may carry a node name after it)
[collision]
name=rb3_cv.sld             ; collision volume (not needed for rendering)
[gamedata]
class=UnscalableTerrainClassID
; plus physics (mass, drag, friction), DamageZones, Explosion*, animation=,
; skeleton=, Subsystems= ... the full game-object layer (MechBld output)
```

For rendering, only `[video] object=` matters — take the first token, resolve the
`.BGF` (DIV-BIZ2 geometry, see B2Z_FORMAT.md).

## LOD container (format evolution, 1996)

Game-side BGFs nest their patches **inside** the LOD block (`0x041`), which the
1994 loader treated as an empty marker and skipped:

```
0x040 object
  0x036 vertex format
  0x041 LOD                ; now a CONTAINER
    0x046 len=8            ; switch in/out distances (2 × f32)
    0x042 patch ...        ; the actual geometry
```

A parser following the 1994 spec reads these files as *empty*. Parse the first
(highest-detail) LOD's contents; later `0x041` blocks are lower-poly alternates
and would double-draw. This unlocked ~850 game models that previously decoded to
zero geometry.

## Animation & effects

- A MOD's `[video] object=` list may carry **several objects** — e.g. the Red
  Planet door `DRW.MOD`: `drw.bgf dr1.bgf dr2.bgf` = frame + two sliding leaves
  ("number and order of objects is significant!"), plus low-poly LOD twins
  (`<name>l`, dropped for rendering). The wellhead `WH1.MOD` carries
  `wh1.bgf … lazdril.bgf` — the **laser-drill beam mesh**.
- **Door motion is data**, in the `.SUB` subsystems file:

  ```ini
  [door1]
  Type=DoorClassID
  TravelTime=13.0            ; seconds to open
  DeadTime=3.0               ; dwell at each end
  MotionExtent=-25.0 0.0 0.0 ; local slide vector
  Collision=dr1_cv.sld       ; links the subsystem to video object "dr1"
  ```

  The viewer plays this as a ping-pong slide (extent rotated into world space per
  instance). The laser drill's firing is engine-driven (no data), so the viewer
  gives `laz*` objects an approximate glow pulse — flagged as approximation.
- Scrolling textures play in maps too: any surface whose texture entity carries
  a `SPECIAL=" SCROLL u0 v0 du dv"` hook in its material library (smoke stacks,
  sky domes, beam effects) drifts its UVs — see SCN_FORMAT, Scrolling textures.
- Other animation carriers, not yet implemented: `.ANI` (INI skeletal keyframes:
  framecount/framerate/skeletonfile + `.SKL` skeletons — the mech walk cycles)
  and `SPECIALFX` particle-emitter definitions.

## Asset resolution

Prefer assets from the **same game tree** as the map (`<tree>/MODELS/*.MOD`,
`<tree>/VIDEO/**.BGF`) before the archive-wide basename index — BTDAVE, BTLIVE and
BTRAVINE each carry their own versions.

## Validation

`ARENA1.MAP` → the arena hall + 8 dropzones. `CITY1.MAP` → 77 placed buildings.
`BLADE.MAP` (Red Planet) → 205 placements / 24k triangles; a render from its first
dropzone shows the drop-station, canyon walls and track — the pod's-eye view.
Dropzones are drawn as small red pyramids in the archive viewer.