# Obstacle models

Open [Obstacles by level](https://swift-speed-asset-library.blakedev.chatgpt.site/obstacles) in the asset library. Select a level. Drag a model to rotate it. Use the zoom buttons or focus the model and use arrow keys, `+`, `-`, and `0`. Select a shape or action state. **Blast** shows an explosion. Lance, mini-bomb, and crown states share a fixed frame and ground marker.

The page shows real meshes from the RealityKit builders. It includes each chapter's color swatches, native hazards, signature encounters, six jump profiles, and boost gates. Canyon Hunt also includes its boundary wall mesh. Four seeded encounter runs supply the generated inventory. The four complete ship models appear below the obstacles. Canvas lighting is an inspection aid; check final material response and timing in the game.

## Edit a model

1. Change its builder in `SwiftSpeed/SwiftSpeed/SwiftSpeed/RealityGameScene.swift`.
2. Match the solid geometry in `FlightMechanics.swift`.
3. Add or change chapter use in `CourseProfile.swift` and encounter placement in `EncounterDirector.swift`.
4. Run the focused XCTest checks.
5. Export the updated runtime meshes:

   ```sh
   bash scripts/export-obstacle-models.sh
   ```

   Set `SWIFTSPEED_PREVIEW_DEVICE` to another installed iOS Simulator UUID when needed.

6. Run `npm test` from `asset-library`.
7. Review the level page and test the model during flight.

The export test writes development files into the Simulator's temporary directory. The script copies only generated JSON files into `asset-library/public/assets/models`. The bundled inventory in `app/lib/obstacle-model-index.json` is generated by the same command. Do not edit those JSON files by hand. If you add a hazard kind, add its display text in `asset-library/app/lib/obstacles.ts` and its stable asset record in `catalog.ts`. Run `npm run docs:inventory` to update the linked design-system inventory.

## Obstacle behavior

- **Large boulders:** use one stone color. Their broad collision mass stays grounded.
- **Vertical barricades:** have six tall shapes and a wide form. Each collision profile follows its model.
- **Orbital lances:** descend from 24 m above their planted position. They pierce the ground 30 m ahead. They do not explode.
- **Strafe fighters:** fly straight toward the ship. Each fighter drops three mini bombs along its fixed path.
- **Mini bombs:** fall for 0.6 seconds, then detonate 14 m ahead. Their small blast lasts 0.85 seconds. Every drop retains at least 1.8 seconds of warning at the maximum supported speed.
- **Alien bombs and missiles:** retain their marked blast footprints. Bombs detonate 24 m ahead. Missiles detonate 32 m ahead. Their blasts last 1.25 seconds.
- **Capture Crown:** starts wide. A harmful grip closes over 0.45 seconds. It holds the ship, lifts it to 4.2 m over 1.1 seconds, then releases it into a jump. Capture applies one heavy impact with normal shield protection. An airborne capture preserves the ship's starting height.
- **Transit skimmers:** use the Twin Keel design. Two blue hover pods flank a raised cockpit. Purple lights mark the pods.
- **Occupation walkers:** stand three times taller than the original model and have purple eyes. They walk forward or side to side. Shared gait samples move the legs and collision pieces together. The opening fits the widest visible ship at every step.
- **Boost gates:** use Vector pylons with a transparent blue field. Forward chevrons mark the route. The wide collection area keeps the existing boost behavior.
- **Jump ramps:** offer Standard, Long, Skip, Wide, High, and Long glide decks. Width, rise, length, and launch velocity come from the actual profile. Flight forecasts reserve the full jump and landing corridor, including each lance's descent path.
- **Level colors:** named swatches show the actual sky, horizon, ground, stone, structure, shadow, native accent, jump cue, and boost cue. First Contact uses warm sand and limestone. Canyon Hunt uses rust rock and slate shadows.
- **Canyon boundary walls:** stand at world x = −100 m and +100 m. Continuous segments rise at least 100 m above local terrain. Simulation bounds prevent passage through either wall, including shielded and airborne contact. Other chapters and endless mode remain open.

Low barricade wedges and hex shield walls are retired. The old shield-wall identifier remains readable for older data. It has no model or collision mass and never appears in new encounters.

Bomb timers, fighter drops, capture phases, and walking motion pause with the game. Checkpoint snapshots retain their state. Normal shields, swept contact, jump clearance, and lateral avoidance still apply.

Ship outlines, panels, engines, exhaust cores, and trails use mirrored geometry. Ship rebuilds first detach all old parts. `ShipGeometryTests` checks the vertices of each complete runtime model, including its boosters.

## Route hardware designs

Open [Design options](https://swift-speed-asset-library.blakedev.chatgpt.site/designs) to compare the models side by side.

The six ramp profiles now use a chamfered wedge, open bridge, arrow deck, fan deck, curved kicker, and launch runway. Their launch widths, heights, and flight profiles stay the same. Lime guide lights follow each surface.

Levels 4–6 use blue teal (`#3D6E75`), plum (`#663D61`), and warm bronze (`#856E4D`) ground. The level palettes and comparison page export these values from the runtime.

Vector pylons is the selected gameplay gate. A transparent blue field spans the opening. The field has no solid collision. Split halo and Hex portal remain alternative designs in the comparison page. All three models have blue lights on both faces.
