Tinyworld Flight Sim

tinyworld-flight-sim

Flyable plane flight, ported from the standalone ships/flight-sim3.html arcade model. The plane is NOT a bespoke tool or object kind — it is the existing crop-duster / stunt-plane that the codebase already ships as a model-stamp (models/stunt_plane.glb, stamp id stunt-plane, label "Stunt Plane"), placed through the Stamps system. The placed cell is therefore kind: 'model-stamp' with appearance.modelStampId === 'stunt-plane'.

Do not reintroduce a separate plane tool/kind — that was a wrong turn. Flight attaches to whatever model-stamp the player already placed, detected by signature.

Where it lives

• engine/world/34-flight-sim.js — the whole system: trimmed physics, flight cameras, enterFlight/exitFlight, tickFlight, HUD, Enter/Fly menu, key capture, and isFlyableStampCell(cell) (the detector). Loaded between 33-radial-menu.js and 99-late-boot.js.
• isFlyableStampCell(cell) returns true when cell.kind === 'model-stamp' and the resolved getModelStamp(appearance.modelStampId) signature matches /plane|aircraft|airplane|stunt|crop-?duster|jet/. Exposed as window.isFlyableStampCell.
• Wiring hooks:
  • 20-input-place-erase.js — applyTool gains if (window.__flightActive) return;. In the pointerup click-resolution block, a plain (unmodified) click on a flyable stamp opens the Enter/Fly menu regardless of the active tool (you still erase it with the eraser). This runs BEFORE the place/select branches so a click never stacks/replaces the plane. NOTE: a plain Select click resolves here, NOT in applyTool (applyTool is only reached by non-select tools).
  • 25-animation-loop-schema.js — if (window.tickFlight) window.tickFlight(dt); right before renderScene().
  • styles/tiny-world.css — .flight-hud, .flight-menu, .flight-menu-btn, body.flight-active.

The scale trick (do not "fix" this)

The ships model is tuned for a kilometre-scale world (cruise ~77 m/s). Physics runs untouched in sim space; the flown object (the placed stamp group) position is mapped into the scene via a single similarity transform: scenePos = sceneOrigin + yawQuat * ((simPos - simOrigin) * FLIGHT_SIM_TO_SCENE) (FLIGHT_SIM_TO_SCENE = 0.09). sceneOrigin/yaw are captured from the parked stamp at enterFlight. Ground is a flat sim plane at spawn height.

• Camera is the exception: the chase cam is framed in scene units (~3–5.5 units behind, ~1.45 up — the plane is ~1.35 units wide), NOT run through the sim-scale transform. Running the camera offset through the sim scale parks it inside the tail (the original bug). Controls: arrows Up/Down = throttle, Left/Right = rudder.

Flow

• Place the Stunt Plane from Stamps (it is a model-stamp).
• Plain-click the placed plane → showFlightMenu → "Enter / Fly" → enterFlight(x,z): swaps the global camera to a flightCam (FOV 60), captures keys, and uses the placed stamp group as the flown mesh (flightJet); spins the named propeller mesh in place and adds the Dusty-style translucent strobe disc whose opacity flickers with throttle.
• Controls: W = nose down, S or X = nose up (pitch), A/D roll, Q/E yaw, Shift/Ctrl OR ArrowUp/ArrowDown = throttle, ArrowLeft/ArrowRight = rudder, B brake.
• Combat controls live in 41-flight-combat.js while flying: left mouse or Space holds guns, X fires a missile, and right-click fires one missile via window.__flightMissilePressed / window.__flightMissileHeld. The pointer handler in 34-flight-sim.js must prevent the context menu only while flightActive is true. Missile hits and destruction should use the pooled flight explosion sprites (tw_flight_explosions) plus smoke trails rather than adding DOM effects or build-mode controls.
• Default view while flying is the LOS drone camera, not the chase camera. It captures a fixed observer anchor near the launch/island position and then pans and adjusts FOV to keep filming the plane. The enlarged map panel carries the close chase/cockpit feed, and the swap button can make either feed primary.
• Escape → exitFlight(): restores the previous camera, calls updateCamera(), re-renders the cell to re-park the stamp.
• Lobby vehicles are self-replenishing: enterFlight() detaches the clicked stamp mesh as the active flyer, clears entry.object, and immediately renderCellObject()s a fresh parked copy in the same cell. Do not mutate the world cell or broadcast a cell edit for this handoff; the placed stamp remains the shared lobby spawn so every player can take a plane independently.
• Flight combat has finite gun and missile ammo. 41-flight-combat.js owns the ammo counters plus the tw_flight_resupply_rewards pool: glowing airborne rings placed ahead of the flyer that refill guns and missiles when flown through, then respawn farther ahead.

Gotchas

• Module 34 shares the global scope with every other engine/world module — all its top-level scratch globals are _fl…-prefixed to avoid the duplicate- identifier instantiation failure (see AGENTS.md "Project shape"). A duplicate top-level const/let/function name silently kills the whole module.
• The tool picker is a search palette (#palette-search → #palette-results), not a fixed toolbar; the stunt plane is found under Stamps, not a tool button.
• The stunt plane propeller mesh (SM_Veh_Plane_Stunt_01_Prop) already has its local origin at the hub. Match the crop-duster path by rotating that mesh in place around local Z; do not wrap it in a new AABB-centred pivot, or it orbits off-centre instead of spinning like the ambient dusting plane.
• The flight propeller must read like the ambient Dusty/crop-duster prop while borrowing the duplicate-island engine tint: high apparent RPM, a dark translucent disc, and mostly faded physical blades at cruise throttle. A solid blade screenshot means the visual balance is wrong even if the mesh is technically rotating.
• The blur shape should be a round camera-facing disc, not a projected oval from a tilted local mesh. Use the circular sprite treatment for flight-camera readability.
• Flight is arcade-scale for a tiny world: enterFlight launches the plane already cruising just above the board (initial forward speed + throttle 0.6) so there is no runway taxi phase. Collision and landing are checked in scene space against the TinyWorld board surface plus object bounds, then converted back to sim-space Y. The collision hot path must stay candidate-based: collect the small 3x3-ish cell window around the plane in home/world coordinates plus the matching local window for each editable island, then test only those rendered cellMeshes entries. Do not return to splitting and scanning every cellMeshes key per frame. Shallow, upright touchdowns become ROLLING / LANDED; hard terrain strikes or object hits stop the plane and show a collision/hard-landing status. Tuning lives in FCFG, FLIGHT_SIM_TO_SCENE (0.09), and the FLIGHT_SCENE_* collision constants.

Verify (real app, real pointer pipeline — not synthetic shortcuts)

npm run dev, then via agent-browser eval:

1. Place: setCell(x,z,{terrain:'grass',terrainFloors:1,kind:'model-stamp',floors:1,appearance:{modelStampId:'stunt-plane'}}); isFlyableStampCell(getWorldCell(x,z)) is true once the GLB loads.
2. Find a screen point where pickTile(px,py) resolves to the plane cell (project + search a small window — projecting the centre alone misses, terrain raycast is angled), then dispatch real pointerdown/pointerup there → .flight-menu appears.
3. Click .flight-menu-btn → camera.fov === 60, window.__flightActive === true.
4. Dispatch keydown ShiftLeft+KeyW, run ~2.5s → the stamp's world position moves.
5. Escape → camera.fov === 28, __flightActive === false, stamp re-parked.