Module catalog and limits
Import the runtime from engine/index.js. Import each selected object package separately and inject the runtime namespace into its constructor. Imports do not require a scene, runtime network service or documentation files.
| Runtime module | Public interface | Limits |
|---|---|---|
| Lifecycle/resources | Engine, ResourceScope, disposeTree, ObjectState | Supplied canvas, asynchronous scene stages, explicit resource ownership |
| Motion | MotionBody, FixedClock | Position/velocity/quaternion integration; no general rigid-body or aerodynamic solver |
| Spatial | SpatialWorld, sweepTriangle | Swept spheres/segments against boxes, spheres, static meshes and terrain |
| Terrain | Heightfield, generateLandscape | Exact render/query triangles, local refinements; finite generated region |
| Shared environment | Environment, ENVIRONMENT_PRESETS, RainField | Adjustable presentation state/layers; visual weather, not forecasting |
| Wind | WindField, addWindData, applyInstanceFade | Stable uniforms, gust sampling, matching visible/depth deformation and instance fades |
| Lighting | Daylight, CascadedShadows | Sun/moon/sky/fog; optional three-map finite shadow coverage |
| Surface detail | createGroundMaterial, groundTexture | Generated grass/soil/rock/sand with height/slope blending and snow |
| Water | WaterSurface, createRiver, createRiverGeometry | One horizontal reflected surface plus descending river; up to four terrain refinements; no fluid solver |
| Postprocessing | PostFX | HDR, bloom, contact shading, display conversion; optional six-box obstruction helper has limited integration coverage |
| Effects | PlasmaSun, ParticleField | Locally generated plasma and bounded particles with owned resources |
| Geometry/material helpers | ArchitectureBatch, roundedBox, consolidate, surfaceLibrary, disposeSurfaceLibrary | Consolidate compatible static geometry only; explicitly manage shared material lifetime |
| Input/cameras | OrbitControls, InputState, FollowCamera | Canvas-scoped desktop controls; physical touch/gamepad operation unverified |
| Object folder | Classes | Details |
|---|---|---|
| aircraft | NavalFighter | Exterior, 3D cockpit, instruments, movable controls; guide |
| people | Person, Bird, Pet | Body/head variation, articulation, poses and actions; guide |
| vegetation | Tree, Forest, GrassPatch | Varied trees, leaves, grass, wind and LOD; guide |
| beach | BeachUmbrella, SunLounger, VolleyballCourt, BeachBall, Sandcastle, BeachTowel, SandBucket | Independent props; guide |
| buildings | Building, Bridge, Road, FarmField, Airfield | Structures and ground-conforming surfaces; guide |
| craft | Hovercraft | Source-derived reusable craft; no campaign, combat or navigation behavior |
| props | Flag | Pinned cloth with optional shared wind; procedural deformation, not cloth physics |
Legacy construction helpers remain within selected packages for the original studio/courtyard scenes. They are exposed by shell/lib/legacy-api.js to those applications, not by engine/index.js. Never make an object depend on that shell bridge.
Ownership and animation
Register each object's dispose method through the scene scope. Object roots are ordinary Three.js groups/meshes. Properties describe the object; actions change class-specific state. Serialization is not a promise to rebuild geometry after arbitrary property edits: follow the class guide or reconstruct with new options.
PlasmaSun and ParticleField retain their update/configure/emit methods documented in API.md and their exported source. Particle capacity is bounded. Source-derived RoomLighting/RoomBatch live in the buildings package, with six lighting groups and narrower test coverage than the primary shell modules.
Sunjack campaign logic, UI, saves, city coordinates, resident schedules, missions, weapons and boss behavior are excluded. Source provenance and embedded license obligations are recorded separately.