build-app

Build an Engine application

Read package.json and the entry point, keep the surface that owns the lifecycle, and read only its reference: direct Engine, React, or Web Components. Choose from imports and markup, not dependencies.

Bootstrap

• Input is opt-in. app.keyboard, mouse, touch, gamepads, and elementInput stay null unless passed to new Application(canvas, { ... }); UI buttons need new ElementInput(canvas).
• The Engine adds no window resize listener; call app.resizeCanvas() from your own handler.
• graphicsDevice.maxPixelRatio defaults to 1. Raise it, at most to window.devicePixelRatio, only where the target holds its frame budget, call app.resizeCanvas(), and confirm with canvas.width / canvas.clientWidth.
• Rigid bodies stay inert until Ammo loads through WasmModule. Copy the loader from the physics/falling-shapes example with find-examples.
• devtools defaults to true, so debugging tools can find the app (inspect-runtime). Set it to false only to hide a production build.

Update loop

• dt is already clamped by app.maxDeltaTime (0.1 s); tune it instead of clamping by hand. app.timeScale scales it, and 0 pauses scaled time.
• Keep app state explicit and owned in one place; advance time-dependent logic from dt, and reset through the same setup used at start.

UI

• Render UI from app state; never keep the source of truth in the DOM or UI elements.
• Use a DOM or React overlay, or Engine screen and element components adapted from a user-interface example.
• Hide unused elements with enabled = false; an element at opacity 0 still draws.

Ownership

• Keep one owner for app creation, assets, entities, update callbacks, and teardown.
• Prefer the surface's declarative primitives. Put per-entity and per-frame behaviour in an Engine Script.
• Remove external events and resources in the lifecycle that created them.