Renderable

A visual description for a 6-DOF entity — shape, size, colour, and optional GLB — that RenderSyncSystem turns into a live mesh and drives from the entity's pose.

What it does

RenderableComponent is pure data — a shape, a size (sx,sy,sz), a diffuse colour (r,g,b), an emissive scalar, render flags, and optional GLB / procedural hints — carrying no mesh handle. RenderSyncSystem (query [Transform6DOF, Renderable]) mints the mesh on first sight through the active RendererAdapter on one of three paths: a glbSrc loads a real model (loadModelTemplate + instantiateModel, auto-fit scale and nose-facing yaw); a seeded procedural shape (asteroid / oil-blob + meshSeed) builds a deterministic noise-displaced rock via createProceduralMesh — and directional silhouettes (spaceplane, kilrathi, freighter-*, missile) always take this path so their +Z nose points right; anything else is an engine primitive via createMesh. Each frame it reads the sibling Transform6DOF (position + unit-quaternion orientation) and pushes that pose onto the mesh, diffing visible and colour so steady-state frames stay quiet. The live handle lives in a System-side WeakMap, and the System is park-aware: a pooled entity keeps its hidden mesh while parked, and only a true destroy disposes it.

Use it in a scene

{
  "Player": {
    "tags": ["player"],
    "components": {
      "Transform6DOF": { "x": 0, "y": 0, "z": 0, "rx": 0, "ry": 0, "rz": 0 },
      "Renderable": {
        "shape": "spaceplane",
        "sx": 3,
        "sy": 1,
        "sz": 4,
        "r": 0.55,
        "g": 0.62,
        "b": 0.78,
        "emissive": 0.18,
        "selfShadow": true,
        "glbSrc": "/wingman/falconship.glb"
      }
    }
  }
}

Props

• shape (RenderableShape, default "box") — one of box, sphere, cylinder, plane, torus (primitives), spaceplane, kilrathi, freighter-head, freighter-car, missile (directional silhouettes, always procedural), or asteroid, asteroid-drop, oil-blob, waypoint (procedural rocks/markers).
• sx, sy, sz (number, default 1) — size on each axis (width, height, depth).
• r, g, b (number, default 1) — diffuse colour in [0,1].
• emissive (number, default 0) — emissive self-illumination scalar; 0 is an unlit surface.
• visible (boolean, default true) — whether the mesh is drawn; diffed each frame so it can be toggled at runtime.
• selfShadow (boolean, default false) — hint that this mesh wants self-shadow registration (driven by a Shadow system).
• glow (boolean, default false) — opt this mesh into the selective glow post-pass.
• glbSrc (string, optional) — GLB asset to use as the visible model (e.g. the player ship); loaded through the adapter's loadModelTemplate + instantiateModel, with a procedural-ship fallback if it can't resolve.
• meshSeed (number, optional) — seed for a procedural rock (asteroid / oil-blob); same seed ⇒ identical geometry. Seedless rocks degrade to a sphere.
• cutAxisX, cutAxisY, cutAxisZ, cutDepth (number, optional) — carve a flat face into a procedural rock along the given axis at the given depth.
• debugForward (boolean, optional, default false) — force the DEV forward-pointer gizmo on for a ship even outside a dev build; leave unset in shipped scenes.

Events

Renderable neither emits nor listens for any bus events (emits: [], listens: []). It is a pure render sink: it reads Transform6DOF directly each frame and pushes to the renderer — there are no RenderableEvents / RenderableInputEvents constants to import.

Dependencies

Transform6DOF — required on the same entity; RenderSyncSystem reads its position and orientation every frame to pose the mesh, and an entity without it never matches the query. To see a Renderable you also need a camera (CameraState6DOF, typically framed by ChaseCamera6DOF targeting a ChaseCameraTarget) and a light.

Notes

• The System never imports @babylonjs/three — every mint and pose call goes through this.world.renderer, so the component is renderer-agnostic.
• glbSrc overrides the procedural build but the authored shape is still kept on the component — set shape to the matching silhouette (spaceplane, kilrathi, …) so the fallback ship and forward gizmo stay correct if the GLB fails to resolve.
• Directional shapes are always built procedurally, even seedless, because a primitive fallback would mis-orient them (a missile → a +Y cylinder). Only the seeded rocks degrade to a symmetric sphere when seedless — harmless, since a rock has no front.
• visible and colour are diffed against their last-applied values, so toggling or tinting at runtime is cheap and steady-state frames issue no redundant adapter calls.