# runner A module script.

# ThreeZero A three.js runtime for the Zero engine, built on the ZeroJS JavaScript interpreter. Drop an existing three.js project into the world's VFS, point a `ThreeApp` component at its entry module, and the project runs unmodified — `import * as THREE from 'three'` resolves to a THREE-compatible API whose scene graph renders through Zero's real renderer, GLTF models spawn through the engine's import pipeline, and keyboard/mouse events reach game code as DOM events. ## Pieces - `host.module` — the `__ZERO` host bridge: entity pools mirroring the THREE scene graph 1:1 (world composition happens in the native hierarchy), change-set-only batched transform sync, runtime meshes from BufferGeometry vertex data, GLTF bundle spawning, lights, the viewport camera, input snapshots/events, and screen/time queries. - `runner.module` — builds a ZeroJS VM per app: installs the browser prelude (window, document, performance, typed arrays, a real event registry), resolves ES imports (`three`, `three/addons/...`, relative `./file.js` paths), dispatches engine input as DOM `keydown`/`keyup`/mouse/touch events each frame, and pumps the VM event loop plus animation-frame callbacks with a self-healing loop. - `three.zJs` — the THREE API surface: math, the Object3D graph with mutation tracking (only changed transforms cross the bridge), geometries (parametric + real-vertex BufferGeometry), materials, lights, cameras, Clock, AnimationMixer, and a WebGLRenderer whose `render(scene, camera)` diffs arrivals/departures/dirty objects into host calls. - `OrbitControls.zJs` — `three/addons/controls/OrbitControls.js`: drag-orbit, scroll zoom, pan, damping, auto-rotate, from the engine input snapshot. - `GLTFLoader.zJs` — `three/addons/loaders/GLTFLoader.js`: binds models to imported bundles by URL basename; DRACOLoader/KTX2Loader accepted inert. - `ThreeApp.component` — attach to an entity, set `entry` to the project's main module VFS path; the app boots on play and tears down on edit. ## Running a project ThreeZero builds on the `zerojs` package and reaches it by the package alias `~zerojs`, which a package registers from the `name` in its `package.yaml` wherever it sits. Installing ThreeZero brings `zerojs` along as a dependency, so nothing has to be wired up by hand; `~threezero.runner` and `~threezero.host` address this package's own modules the same way. ``` /zero/source/projects/myapp/main.js ← unmodified three.js sources /zero/source/projects/myapp/models/*.glb ← model files (imported to bundles on upload) ``` ```luau entity.spawn("MyApp").component.add("ThreeApp", { entry = "/zero/source/projects/myapp/main.js" }) ``` Flip to play mode. `requestAnimationFrame` / `setAnimationLoop` run once per engine frame, and `addEventListener('keydown' | 'mousedown' | ...)` receives live input — playable games work end to end (see `/zero/source/projects/crossing`). ## Limitations - No optional chaining (`?.`), `#private` fields, or `Symbol` in project code. - Textures load as inert handles; material color/emissive/opacity drive the visual. - Points/Line/Sprite objects are skipped with a one-time warning. - Skinned-mesh submeshes from imported models render at bind pose or are hidden (engine importer limitation); AnimationMixer plays clips through the engine's ClipPlayer where the rig supports it.