w

docs/SCRIPTING.md

@@ -0,0 +1,379 @@
+# Scripting
+
+Dusk embeds [JerryScript](https://github.com/jerryscript-project/jerryscript) to
+drive gameplay logic from JavaScript. The engine itself (rendering, physics,
+asset loading, entity storage) is all C; scripts sit on top and manipulate that
+state through a small set of bound objects.
+
+This document covers the JS-facing scripting API. **UI (buttons, sliders,
+menus, etc.) is not exposed to scripts** — it's a separate, C-only API. See
+[UI.md](UI.md) if you're building screens/menus from engine/game C code.
+
+## Lifecycle
+
+On startup, `engineInit()` loads and evaluates `assets/engine.js` as the main
+script, then calls the global `init()` function if one is defined. From then
+on, every engine tick calls (in order):
+
+1. `fixedUpdate()` — once per fixed timestep. Use this for gameplay logic that
+   must be deterministic and independent of display refresh rate (movement,
+   physics-adjacent input handling, etc). Skipped on interpolation/dynamic
+   frames when the build has variable-timestep rendering enabled.
+2. `update()` — once per rendered frame, including interpolation frames. Use
+   this for smooth, purely presentational animation (nothing that needs to be
+   deterministic).
+
+On shutdown, `deinit()` is called once.
+
+All four hooks (`init`, `update`, `fixedUpdate`, `deinit`) are **optional** —
+if a script doesn't define one, the engine simply skips it, no error.
+
+```js
+function update() {
+  cubePosition.rotation.y += TIME.delta * 1.5;
+}
+```
+
+### `async init()` and `include()`
+
+`init` (or any of the other hooks) can be declared `async` and use `await`
+freely, including awaiting `include()` (see below), even though the engine
+calls these functions synchronously from C with no external JS event loop.
+When a hook returns a pending `Promise`, the engine keeps driving the asset
+system and JerryScript's job queue until that promise settles before
+continuing — so by the time e.g. `init()` "returns" from the engine's point of
+view, everything it awaited has actually finished.
+
+```js
+async function init() {
+  Actions = await include("input.js");
+  // ...
+}
+```
+
+If the awaited work throws/rejects, it surfaces as a C-level error.
+
+## Loading other scripts: `include(path)`
+
+```js
+var Actions = await include("input.js");
+```
+
+`include(path)` always returns a `Promise`. The named file is loaded and
+evaluated once no matter how many times (or from how many different scripts)
+you `include()` it — later calls for the same path are handed the same
+in-flight/resolved promise rather than re-running the file.
+
+The included script communicates its result back by assigning to the bare
+global `module`:
+
+```js
+// input.js
+Input.bind("w", INPUT_ACTION_UP);
+// ...
+
+module = {
+  UP: INPUT_ACTION_UP,
+  DOWN: INPUT_ACTION_DOWN,
+  // ...
+};
+```
+
+Whatever `input.js` assigns to `module` becomes the resolved value of the
+promise `include("input.js")` returned — that's what `Actions` ends up being
+in the example above. If the included script throws, the promise rejects
+instead.
+
+## Full example
+
+This is the actual shipped example content (`assets/engine.js` +
+`assets/input.js`):
+
+```js
+// input.js — binds physical buttons to abstract actions, then exports the
+// action constants so other scripts don't need to know raw INPUT_ACTION_* names.
+Input.bind("w", INPUT_ACTION_UP);
+Input.bind("s", INPUT_ACTION_DOWN);
+Input.bind("a", INPUT_ACTION_LEFT);
+Input.bind("d", INPUT_ACTION_RIGHT);
+Input.bind("space", INPUT_ACTION_ACCEPT);
+Input.bind("escape", INPUT_ACTION_RAGEQUIT);
+
+if(typeof INPUT_GAMEPAD !== "undefined") {
+  Input.bind("gamepad_up", INPUT_ACTION_UP);
+  Input.bind("gamepad_down", INPUT_ACTION_DOWN);
+  Input.bind("gamepad_left", INPUT_ACTION_LEFT);
+  Input.bind("gamepad_right", INPUT_ACTION_RIGHT);
+  Input.bind("gamepad_a", INPUT_ACTION_ACCEPT);
+  Input.bind("gamepad_start", INPUT_ACTION_RAGEQUIT);
+}
+
+module = {
+  UP: INPUT_ACTION_UP,
+  DOWN: INPUT_ACTION_DOWN,
+  LEFT: INPUT_ACTION_LEFT,
+  RIGHT: INPUT_ACTION_RIGHT,
+  ACCEPT: INPUT_ACTION_ACCEPT,
+  CANCEL: INPUT_ACTION_CANCEL,
+  RAGEQUIT: INPUT_ACTION_RAGEQUIT
+};
+```
+
+```js
+// engine.js
+var Actions;
+var camera, cameraPosition;
+var cube, cubePosition, cubeRenderable, cubeMesh;
+
+async function init() {
+  Actions = await include("input.js");
+
+  camera = new Entity();
+  cameraPosition = camera.add(POSITION);
+  camera.add(CAMERA);
+  cameraPosition.position = new Vec3(3, 3, -6);
+  cameraPosition.lookAt(new Vec3(0, 0, 0));
+
+  cube = new Entity();
+  cubePosition = cube.add(POSITION);
+  cubeRenderable = cube.add(RENDERABLE);
+  cubeMesh = Mesh.createCube();
+  cubeRenderable.mesh = cubeMesh;
+  cubeRenderable.color = Color.red();
+}
+
+function update() {
+  cubePosition.rotation.y += TIME.delta * 1.5;
+  cubePosition.rotation.x += TIME.delta * 0.7;
+}
+
+function fixedUpdate() {
+  var move = 3.0 * TIME.delta;
+  if(Input.isDown(Actions.LEFT))  cubePosition.position.x -= move;
+  if(Input.isDown(Actions.RIGHT)) cubePosition.position.x += move;
+  if(Input.isDown(Actions.UP))    cubePosition.position.z += move;
+  if(Input.isDown(Actions.DOWN))  cubePosition.position.z -= move;
+  if(Input.pressed(Actions.ACCEPT)) cubePosition.position = new Vec3(0, 0, 0);
+}
+
+function deinit() {
+  cube.dispose();
+  camera.dispose();
+}
+```
+
+## API reference
+
+### `TIME`
+
+Plain global object, live getters (read fresh engine state every access, not
+snapshotted):
+
+| Property | Type | Description |
+|---|---|---|
+| `TIME.delta` | number | Seconds since the last frame. |
+| `TIME.time` | number | Total elapsed engine time, in seconds. |
+
+### `PLATFORM`
+
+A single global string constant — the compile-time target name, e.g.
+`"linux"`, `"psp"`, `"vita"`, `"dolphin"`. Individual platform builds may
+inject additional platform-specific globals via their own
+`modulePlatformPlatform()` hook; those aren't documented here since they vary
+per target.
+
+### `Input`
+
+Static namespace (not constructible — there's no `new Input()`).
+
+| Method | Description |
+|---|---|
+| `Input.bind(buttonName, action)` | Binds a physical button/key (string, e.g. `"w"`, `"space"`, `"gamepad_up"`) to an abstract `INPUT_ACTION_*` constant. Many buttons can bind to the same action. Throws on an empty/unrecognized button name or invalid action. |
+| `Input.isDown(action)` → boolean | Is the action currently held. |
+| `Input.pressed(action)` → boolean | Action transitioned to down this frame. |
+| `Input.released(action)` → boolean | Action transitioned to up this frame. |
+| `Input.getValue(action)` → number | Current analog value for the action. |
+| `Input.axis(negAction, posAction)` → number | Combined axis value from two opposing actions. |
+| `Input.axis2D(negX, posX, negY, posY)` → `Vec2` | Combined 2D axis from four actions. |
+
+Global `INPUT_ACTION_*` constants (names are stable API; treat the numeric
+values as opaque/build-specific): `INPUT_ACTION_UP`, `INPUT_ACTION_DOWN`,
+`INPUT_ACTION_LEFT`, `INPUT_ACTION_RIGHT`, `INPUT_ACTION_ACCEPT`,
+`INPUT_ACTION_CANCEL`, `INPUT_ACTION_PAUSE`, `INPUT_ACTION_RAGEQUIT`,
+`INPUT_ACTION_CONSOLE`, `INPUT_ACTION_POINTERX`, `INPUT_ACTION_POINTERY`.
+
+Conditionally-defined boolean globals reflecting build capability — only
+present at all if the corresponding input method is compiled in, so
+feature-test with `typeof`, don't assume they exist:
+`INPUT_KEYBOARD`, `INPUT_GAMEPAD`, `INPUT_POINTER`, `INPUT_TOUCH`.
+
+### `Vec2` / `Vec3` / `Vec4`
+
+`new Vec2(x?, y?)`, `new Vec3(x?, y?, z?)`, `new Vec4(x?, y?, z?, w?)` — all
+components optional, default `0`.
+
+Common instance surface across all three: `.dot(other)`, `.length()`,
+`.lengthSq()`, `.normalize()`, `.negate()`, `.add(other)`, `.sub(other)`,
+`.scale(n)`, `.lerp(other, t)` — each of `add`/`sub`/`scale`/`negate`/
+`normalize`/`lerp` returns a **new** vector (non-mutating). `Vec3` additionally
+has `.cross(other)` and `.distance(other)`; `Vec2` has `.distance(other)` too;
+`Vec4` has neither `.cross()` nor `.distance()`.
+
+`Vec4` also has UV aliases over the same four floats: `.u0` (= `.x`), `.v0`
+(= `.y`), `.u1` (= `.z`), `.v1` (= `.w`) — handy for texture-rect style code.
+
+All three have `.x`/`.y`(/`.z`/`.w`) get/set properties and a `.toString()`
+like `"Vec3(1, 2, 3)"`.
+
+**"Vec3Ref" — live references.** Several engine properties (entity
+`position`/`rotation`/`scale`, physics `velocity`, a mesh vertex's `position`)
+return a vector-*like* object instead of a plain `Vec3`. It has the identical
+`.x`/`.y`/`.z` surface, but reads/writes go straight into the underlying
+native buffer — writing `.x` on `entity.position.position` immediately moves
+the entity, no separate assignment needed. Anywhere the API expects a `Vec3`
+argument, a Vec3Ref works too. You never construct one directly; you only
+ever receive them from properties like the ones above.
+
+### `Mat4`
+
+`new Mat4()` — always constructs identity; no other constructor form.
+
+| Member | Description |
+|---|---|
+| `.mul(other)` → `Mat4` | `this * other`. |
+| `.transpose()` → `Mat4` | |
+| `.inverse()` → `Mat4` | |
+| `.determinant()` → number | |
+| `.mulVec3(vec3, w?)` → `Vec3` | `w` defaults to `1.0` (point); pass `0` for a direction. |
+| `.mulVec4(vec4)` → `Vec4` | |
+| `.translate(vec3)` → `Mat4` | Non-mutating — returns a translated copy. |
+| `.scale(vec3)` → `Mat4` | Non-mutating — returns a scaled copy. |
+| `Mat4.identity()` → `Mat4` | Static. |
+| `Mat4.perspective(fov, aspect, near, far)` → `Mat4` | Static, all 4 args required. |
+| `Mat4.lookAt(eye, center, up)` → `Mat4` | Static, all 3 args required `Vec3`s. |
+
+### `Color`
+
+`new Color(r?, g?, b?, a?)` — each an int `0..255`, default `255` (so
+`new Color()` is opaque white). Properties `.r`/`.g`/`.b`/`.a` get/set.
+
+Named factories, each a zero-arg static returning a new opaque `Color`
+(alpha `255` unless noted): `Color.black()`, `Color.white()`, `Color.red()`,
+`Color.green()`, `Color.blue()`, `Color.yellow()`, `Color.cyan()`,
+`Color.magenta()`, `Color.transparent()` (alpha 0), `Color.transparent_white()`
+(alpha 0), `Color.transparent_black()` (alpha 0), `Color.gray()`,
+`Color.light_gray()`, `Color.dark_gray()`, `Color.orange()`, `Color.purple()`,
+`Color.brown()`, `Color.pink()`, `Color.lime()`, `Color.navy()`,
+`Color.teal()`, `Color.cornflower_blue()`.
+
+`Color.rainbow(t?, speed?)` → `Color` — `t` defaults to `TIME.time * 4.0`;
+produces a shifting rainbow color, useful for debug visuals.
+
+### `Mesh`
+
+`new Mesh(vertexCount)` — allocates an uninitialized CPU-side vertex buffer
+(not yet uploaded to the GPU).
+
+| Member | Description |
+|---|---|
+| `.vertices` | Array of vertex wrappers, each with a `.position` (Vec3Ref, writes straight into that vertex). |
+| `.vertexCount` | Read-only. |
+| `.flush()` | Uploads to the GPU. First call initializes the GPU mesh; later calls re-upload the current vertex data — call this after editing `.vertices[i].position`. |
+| `.dispose()` | Frees GPU + CPU resources. |
+
+Static engine-owned singletons (read-only, not something you dispose):
+`Mesh.DEFAULT_CUBE`, `Mesh.DEFAULT_QUAD`, `Mesh.DEFAULT_SPHERE`,
+`Mesh.DEFAULT_PLANE`, `Mesh.DEFAULT_CAPSULE`, `Mesh.DEFAULT_TRIPRISM`.
+
+Static factories (each builds and uploads a brand-new `Mesh`):
+
+| Factory | Notes |
+|---|---|
+| `Mesh.createCube(min?, max?)` | Both `Vec3`, default `(-0.5,-0.5,-0.5)`..`(0.5,0.5,0.5)`. |
+| `Mesh.createQuad(minX?, minY?, maxX?, maxY?)` | Default `-0.5..0.5` both axes; UV fixed `0,0`–`1,1`. |
+| `Mesh.createSphere(radius?, stacks?, sectors?)` | `radius` default `0.5`. |
+| `Mesh.createPlane(width?, height?)` | Defaults `1.0`/`1.0`; XZ-aligned, centered at origin. |
+| `Mesh.createCapsule(radius?, halfHeight?, capRings?, sectors?)` | Defaults `0.5`, `0.5`. |
+| `Mesh.createTriPrism(x0, y0, x1, y1, x2, y2, minZ, maxZ)` | All 8 args required — a triangular cross-section extruded along Z. |
+
+### `Entity` and components
+
+```js
+var e = new Entity();
+var pos = e.add(POSITION);
+```
+
+`new Entity()` allocates an entity. `.id` is the read-only numeric engine ID.
+`.add(TYPE)` adds a component and returns its wrapper (`TYPE` is one of the
+constants below). `.dispose()` removes the entity and all its components.
+
+Component-type constants: `POSITION`, `CAMERA`, `RENDERABLE`, `PHYSICS`,
+`TRIGGER`. Each entity also exposes a lowercase getter that returns the
+existing wrapper if the component is present, or `undefined` if not (it does
+**not** add the component — use `.add()` for that): `entity.position`,
+`entity.camera`, `entity.renderable`, `entity.physics`, `entity.trigger`.
+
+#### `entity.add(POSITION)` → position component
+
+| Member | Description |
+|---|---|
+| `.position` | Vec3Ref. Writing rebuilds the transform automatically. |
+| `.rotation` | Vec3Ref, Euler angles. Same rebuild-on-write behavior. |
+| `.scale` | Vec3Ref. Same rebuild-on-write behavior. |
+| `.parent` | Get/set another position-component wrapper, or `null` to clear parenting. |
+| `.lookAt(target, up?)` | `target` a `Vec3`; `up` defaults to `(0,1,0)`. |
+
+#### `entity.add(CAMERA)` → camera component
+
+| Member | Description |
+|---|---|
+| `.zNear` / `.zFar` | Numbers. |
+| `.fov` | Only meaningful when `projectionType` is `CAMERA_TYPE_PERSPECTIVE`; otherwise get returns `undefined` and set is a no-op. |
+| `.projectionType` | `CAMERA_TYPE_PERSPECTIVE` or `CAMERA_TYPE_ORTHOGRAPHIC`. |
+| `.orthoTop` / `.orthoBottom` / `.orthoLeft` / `.orthoRight` | Only meaningful in orthographic mode, same undefined/no-op rule otherwise. |
+
+#### `entity.add(RENDERABLE)` → renderable component
+
+| Member | Description |
+|---|---|
+| `.type` | `ENTITY_RENDERABLE_TYPE_MATERIAL`, `_SPRITEBATCH`, or `_CALLBACK`. |
+| `.mesh` | Get/set a `Mesh` instance or a `Mesh.DEFAULT_*` singleton. |
+| `.color` | Get/set a `Color` instance (throws if given something else). |
+| `.addSprite({ min?, max?, uvMin?, uvMax? })` | Adds a sprite to this renderable's sprite batch; all fields optional, default zero. |
+| `.clearSprites()` | Clears the sprite batch. |
+| `.setCallback(fn?)` | Switches to `ENTITY_RENDERABLE_TYPE_CALLBACK` and calls `fn()` on every render of this entity. Omit/pass non-function to clear. Exceptions inside `fn` surface as a C error. |
+
+#### `entity.add(PHYSICS)` → physics component
+
+| Member | Description |
+|---|---|
+| `.velocity` | Vec3Ref, plain (no rebuild-on-write). |
+| `.onGround` | Read-only boolean. |
+| `.bodyType` | `PHYSICS_BODY_STATIC`, `PHYSICS_BODY_DYNAMIC`, `PHYSICS_BODY_KINEMATIC`. |
+| `.applyImpulse(vec3)` | Adds to velocity. No-op on static bodies. |
+| `.setShapeCube(halfExtents)` | `halfExtents` a `Vec3`. |
+| `.setShapeSphere(radius)` | Number. |
+| `.setShapeCapsule(radius, halfHeight)` | Two numbers. |
+| `.setShapePlane(normal, distance)` | `Vec3` + number. |
+
+Shape-type constants (for reading `.type` on the underlying shape, not for
+`.bodyType`): `PHYSICS_SHAPE_CUBE`, `PHYSICS_SHAPE_SPHERE`,
+`PHYSICS_SHAPE_CAPSULE`, `PHYSICS_SHAPE_PLANE`.
+
+#### `entity.add(TRIGGER)` → trigger component
+
+| Member | Description |
+|---|---|
+| `.min` / `.max` | Plain `Vec3` values (copies, not live refs). |
+| `.setBounds(min, max)` | Sets both at once. |
+| `.contains(point)` → boolean | `point` a `Vec3`. |
+
+## Not yet available to scripts
+
+The following C modules exist and are fully implemented, but aren't currently
+wired into script registration (`moduleRegister()` in
+`src/dusk/script/module/module.h`), so none of these globals exist in a
+script today: `Screen`, `SpriteBatch`, `Text`, `Scene`, `Easing`, `Console`,
+`Engine`. If you need one of these from a script, it needs to be registered
+in `moduleRegister()` first — see the existing entries there and the modules
+under `src/dusk/script/module/` for the pattern to follow.