melonjs 20.2.0 → 20.3.0

package/skills/melonjs-renderables/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: melonjs-renderables
+description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
+license: MIT
+---
+
+# Renderables, input and effects
+
+> Subclassing `Renderable`, custom drawing, receiving pointer events, and
+> applying post effects — with the traps that produce silently wrong output
+> rather than an error.
+
+Everything here is a **silent failure**: the code runs, nothing throws, and the
+result is wrong. Those are the cases worth memorising, because nothing in the
+type signatures warns you.
+
+## 1. A custom `draw()` must position itself from `this.pos`
+
+The renderer is **not** pre-translated to the renderable's position when `draw()`
+is called. `Container.draw` translates by the *container's* own `pos` and then
+calls `child.preDraw` / `draw` / `postDraw`; `preDraw` never translates by the
+child's `pos`. Read `this.pos` and draw relative to it.
+
+```js
+class Marker extends Renderable {
+    draw(renderer) {
+        // ✗ draws at the parent container's origin, not at the marker
+        renderer.fillRect(0, 0, this.width, this.height);
+
+        // ✓
+        renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
+    }
+}
+```
+
+The symptom is an object that renders correctly at position (0, 0) and appears
+stuck at the top-left as soon as you move it.
+
+**Zero the anchor in custom-draw renderables.** `preDraw` does not translate to
+`pos`, but it *does* apply the anchor offset `(-width * anchorPoint.x,
+-height * anchorPoint.y)`. With the default centred anchor, drawing at
+`this.pos` therefore lands half a size off:
+
+```js
+constructor(x, y, w, h) {
+    super(x, y, w, h);
+    this.anchorPoint.set(0, 0);   // ← or every custom draw is offset by -w/2, -h/2
+}
+```
+
+## 2. `isKinematic` must be `false` to receive input or collisions
+
+`Renderable.isKinematic` **defaults to `true`**, which means *"physics collision
+and input events will not impact this renderable"*. A kinematic renderable is
+skipped by the pointer-event dispatcher entirely.
+
+```js
+class Button extends Renderable {
+    constructor(x, y) {
+        super(x, y, 100, 40);
+        this.isKinematic = false;          // ← required, or clicks never arrive
+        input.registerPointerEvent("pointerdown", this, () => { /* … */ });
+    }
+}
+```
+
+The symptom is a handler that is registered, looks correct, and never fires.
+
+Note that `Container`, `Camera2d`, `Draggable`, `DropTarget` and the `UI*`
+elements set it to `false` for you, and so does the `Body` constructor on its
+owner (which covers `Entity` and anything you give a body to) — so a plain
+`Renderable` or `Sprite` subclass with no body is the case that catches people.
+
+The same flag has a second, less obvious effect: it is also the opt-in to the
+world **broadphase**. The quadtree/octree insert skips any child with
+`isKinematic === true`, so body-less objects you want `adapter.queryAABB` /
+`querySphere` to find need `isKinematic = false` as well. The builtin
+narrowphase likewise requires *both* partners to be non-kinematic.
+
+## 3. Draw order: only `addChild(child, z)` works
+
+There are three separate traps here and they compound.
+
+```js
+world.addChild(sprite, 10);   // ✓ the only reliable form
+```
+
+1. **`renderable.z` does not exist.** There is no `z` accessor anywhere on
+   `Renderable` (nor on `Rect`/`Polygon` above it) — only `depth`, which proxies
+   `pos.z`, and the container's default `sortOn: "z"` comparator reads `pos.z`.
+   Writing `sprite.z = 100` creates an inert property that nothing reads.
+   Several shipped examples still contain `this.z = Number.POSITIVE_INFINITY`;
+   those HUDs draw on top only because they happen to be added last. (A `z` key
+   in a `Sprite`/`ImageLayer` *settings* object is a different thing and is real
+   — it assigns `pos.z` in the constructor — but trap 2 then overwrites it.)
+2. **Setting `depth` *before* `addChild` is overwritten.** With `autoDepth` on
+   (the default), `addChild` without an explicit `z` assigns
+   `child.pos.z = children.length` after the push, discarding whatever you set.
+3. **Setting `depth` *after* `addChild` does not reorder.** Containers sort when
+   a child is added (`autoSort`, deferred to the next tick), not when `pos.z`
+   changes. If you must change it later, call `container.sort()` yourself.
+
+The exception: under `Camera3d` the world's `sortOn` is `"depth"`, and the
+camera calls `container.sortNow(true)` every frame. Note that mode does **not**
+sort by `pos.z` as a layer index — it sorts by squared distance from the camera
+in world space (nearest first in the array, painted far→near). So changing
+`depth` does reorder there, but as a position change, not as a layer number.
+
+```js
+// ✗ overwritten by autoDepth
+sprite.depth = 10;
+world.addChild(sprite);
+
+// ✗ no resort happens (except under Camera3d)
+world.addChild(sprite);
+sprite.depth = 10;
+
+// ✓
+world.addChild(sprite, 10);
+```
+
+## 4. `removePostEffect()` destroys the effect
+
+To disable an effect temporarily, toggle it. Removing it frees its GPU
+resources and leaves you holding a dead object.
+
+```js
+// ✗ effect is destroyed; re-adding it will not work
+sprite.removePostEffect(effect);
+
+// ✓
+effect.enabled = false;
+```
+
+Exception worth knowing: an effect with `effect.shared === true` opts out of
+auto-destroy, because it is reused across renderables.
+
+Use `addPostEffect()` / `getPostEffect()` / `removePostEffect()`. Assigning
+`renderable.shader = …` is deprecated since 19.2.0.
+
+Post effects need a programmable pipeline. A `ShaderEffect` constructed against
+the Canvas renderer (`renderer.shaderLanguage === null`) logs a warning, stays
+at `enabled === false` and no-ops every method rather than throwing — and
+`beginPostEffect` filters disabled effects out. Since `video.AUTO` picks the
+backend at runtime, an effect that works on your machine may do nothing on
+another.
+
+## 5. `Vector3d.set(x, y)` silently zeroes `z`
+
+```js
+v.set(10, 20);        // z becomes 0, not "unchanged"
+v.set(10, 20, v.z);   // keep it
+```
+
+`pos` is an `ObservableVector3d`, whose `set(x = 0, y = 0, z = 0)` does the same
+— so `this.pos.set(x, y)` wipes the object's depth.
+
+## Update and draw
+
+```js
+class Enemy extends Renderable {
+    update(dt) {
+        this.pos.x += this.speed * (dt / 1000);
+        return true;                       // ← true means "redraw me"
+    }
+    draw(renderer) { /* … */ }
+}
+```
+
+`update()` returns a boolean meaning *"this object changed and needs
+redrawing"*. The parent accumulates it into the container's `isDirty`, and the
+application skips the whole draw pass while nothing is dirty — so returning
+nothing (falsy) can leave the scene frozen even though state is updating. The
+base implementation returns `this.isDirty`, so `return super.update(dt)` is the
+other correct ending.
+
+`update()` is only called when `obj.inViewport === true` or
+`obj.alwaysUpdate === true`. An off-screen object with the default
+`alwaysUpdate = false` does not tick at all.
+
+## Anchors and floating
+
+- `anchorPoint` defaults to centre `(0.5, 0.5)` on `Renderable`, but `Container`
+  forces `(0, 0)`. Mixing them up shifts children by half their size.
+- `floating = true` pins a renderable to the screen rather than the world, which
+  is what you want for HUD elements. It opts the object out of camera transforms
+  and out of ancestor position accumulation.
+
+## Prefer built-in features
+
+Before writing custom `draw()` code, check whether the engine already covers it —
+`ParticleEmitter`, `Tween`, the `ShaderEffect` presets, `UISpriteElement` and
+`UITextButton`, the physics adapters, and the Tiled tilemap renderers all exist.
+Hand-rolled equivalents miss the batching and the multi-backend support.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| object draws at its parent's origin, ignores its position | `draw()` not reading `this.pos` |
+| pointer handler registered but never fires | `isKinematic` left at its `true` default |
+| wrong draw order | anything other than `addChild(child, z)` — see section 3 |
+| effect cannot be re-enabled after removal | `removePostEffect()` destroyed it |
+| effect silently does nothing | running on the Canvas renderer |
+| object appears frozen while its state changes | `update()` not returning `true` |
+| off-screen object never ticks | `update()` is gated on `inViewport` — set `alwaysUpdate = true` |
+| custom draw offset by half the size | centred `anchorPoint` default not zeroed |
+| spatial query never finds an object | `isKinematic` left `true` — not in the broadphase |
+| `z` unexpectedly 0 after a `set` | `Vector3d.set(x, y)` defaults `z` to 0 |
+
+## Related skills
+
+- `melonjs-getting-started` — Application lifecycle and the scene graph
+- `melonjs-20-migration` — the deprecated `shader` property and other pre-20 APIs

package/skills/melonjs-renderer-backends/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: melonjs-renderer-backends
+description: "Use this skill when a feature works on one machine and not another, when choosing or pinning a renderer, or when writing code that must degrade gracefully. Covers the WebGPU to WebGL 2 to Canvas fallback ladder, what each backend supports, capability detection, and the subsystems that warn once and then stop working on Canvas. Triggers on: video.AUTO, video.WEBGPU, video.WEBGL, video.CANVAS, renderer.type, supportsDepthBuffer, shaderLanguage, WebGPU, WebGL2, Canvas fallback, context loss, backend, works on my machine."
+license: MIT
+---
+
+# Renderer backends and graceful degradation
+
+> `video.AUTO` picks a backend at **runtime**. The same code runs on a different
+> renderer depending on the machine, and several subsystems degrade to nothing
+> rather than erroring. This is the root cause of most "works on my machine"
+> reports.
+
+## The ladder
+
+`video.AUTO` (the default) tries **WebGPU → WebGL 2 → Canvas** and uses the first
+that initialises.
+
+```js
+const app = new Application(800, 600, {
+    parent: "screen",
+    renderer: video.AUTO,     // or video.WEBGPU / video.WEBGL / video.CANVAS
+});
+await app.init();
+```
+
+WebGL 1 is not in the ladder — 20.x made WebGL 2 the baseline, and pinning
+`video.WEBGL` **rejects** on a WebGL-1-only device rather than degrading.
+
+## What each backend can do
+
+| | WebGPU | WebGL 2 | Canvas |
+|---|---|---|---|
+| sprites, tilemaps, text | ✅ | ✅ | ✅ |
+| blend modes | ✅ | ✅ | ✅ except `"none"` |
+| shaders and post effects | ✅ | ✅ | ❌ inert |
+| `Light2d` glow (`drawLight`) | ✅ | ✅ | ✅ cached radial gradient |
+| normal-map lighting, `Light3d` | ✅ | ✅ | ❌ inert |
+| `Mesh` | ✅ | ✅ | ⚠️ CPU-projected, no depth |
+| `Camera3d` / depth sorting | ✅ | ✅ | ❌ warns, renders wrong |
+| `InstancedMesh` | ✅ | ✅ | ⚠️ one draw per instance |
+| GPU tilemap rendering | ✅ | ✅ | ❌ per-tile CPU path |
+
+The Canvas column is the problem: none of it throws. Each of those paths warns
+once and then degrades or no-ops, so the game runs and looks wrong.
+
+Two Canvas rows are worth spelling out because they are easy to misread as total
+failures. A `Light2d` still *draws* — the Canvas renderer bakes a radial gradient
+per light and blits it — what disappears is per-pixel normal-map shading, which
+warns once (`Light2d normal-map lighting requires the WebGL renderer`) and then
+renders sprites unlit. A `Mesh` still draws too, sorted with the painter's
+algorithm and no depth buffer, so convex models look right and anything
+self-overlapping does not. `"none"` (replace, alpha included) is the one blend
+mode Canvas cannot express — there is no `globalCompositeOperation` that
+disables blending for the drawn area alone — so it resolves to `"normal"`, and
+`setBlendMode` reports that back.
+
+## Detecting what you have
+
+```js
+app.renderer.type;                    // "WebGPU" | "WebGL2" | "CANVAS"
+app.renderer.supportsDepthBuffer;     // the practical "is this a GPU backend" test
+app.renderer.shaderLanguage;          // "wgsl" | "glsl" | null (null on Canvas)
+```
+
+There are narrower flags for the features that do not travel together:
+`supportsShaderTileLayers`, `supportsRetainedMesh` and `supportsInstancing` —
+all three `false` on Canvas, `true` on both GPU backends. Prefer a capability
+flag over comparing `type` against a string; `type` is an identity check for
+code coupled to one backend's machinery.
+
+For a scene that genuinely requires a GPU backend, fail loudly rather than
+rendering something broken:
+
+```js
+await app.init();
+if (!app.renderer.supportsDepthBuffer) {
+    throw new Error("this game needs WebGL 2 or WebGPU");
+}
+```
+
+## Writing code that degrades well
+
+**Decorative effects** — let them no-op. A missing vignette is fine.
+
+**Load-bearing effects** — guard the carrier. If a shader draws your content
+rather than decorating it, the carrier renderable shows through raw when the
+effect is disabled: a 1×1 white texture stretched to fill a quad renders as a
+white box exactly where the effect should have been.
+
+```js
+if (effect.enabled) {
+    // draw the carrier the shader consumes
+}
+```
+
+**Dual-language shaders** — a `ShaderEffect` compiles the body matching
+`renderer.shaderLanguage`. With no matching body — a GLSL-only effect on WebGPU,
+any effect on Canvas — the constructor warns once, leaves `enabled === false`,
+and every method becomes a no-op. Pass `{ glsl, wgsl }` rather than a bare
+string, or gate on `renderer.shaderLanguage`.
+
+## Pinning a backend
+
+Pin only with a reason. `video.WEBGL` costs you the WebGPU path *and* the Canvas
+fallback, so a WebGL-1-only device gets nothing at all.
+
+Legitimate reasons: reproducing a backend-specific bug, a benchmark, or a known
+driver issue in the field.
+
+For one-off testing you do not need to touch the settings at all: the URI
+fragments `#webgpu`, `#webgl` (or `#webgl2`) and `#canvas` override the
+`renderer` setting for that run, and behave exactly like passing the matching
+constant — `#webgl` on a WebGL-1-only device rejects rather than falling back.
+
+## Context loss
+
+A GPU context can be lost at any time — tab backgrounding, driver reset, memory
+pressure. melonJS handles restoration on both GPU backends: WebGL recompiles
+every live `GLShader` and replays its uniform snapshot, WebGPU renegotiates a
+device and rebuilds its batchers, and both then emit
+`event.ONCONTEXT_RESTORED` (the paired loss event is `event.ONCONTEXT_LOST`).
+
+What you must handle is your own GPU-side state. If you cached a raw texture or
+program handle, re-acquire it on restore rather than holding the stale one:
+
+```js
+import { event } from "melonjs";
+
+event.on(event.ONCONTEXT_RESTORED, (renderer) => {
+    // re-acquire anything you were holding by raw handle
+});
+```
+
+## Practical differences
+
+- **Frame capture orientation differs**: row 0 of a `toFrameTexture()` capture is
+  the bottom of the frame under WebGL and the *top* under WebGPU, so a GLSL body
+  that flips with `1.0 - uv.y` must not do so in its WGSL twin. The WebGPU
+  capture also preserves alpha, where the WebGL one captures into an opaque RGB
+  texture.
+- **The advanced blend modes cost far more than they look.** `overlay`,
+  `difference`, `hard-light`, `soft-light`, `color-dodge`, `color-burn`,
+  `darken` and `lighten` cannot be expressed as fixed-function blending, so on
+  both GPU backends each such draw is bracketed individually: capture the
+  destination, redraw offscreen, composite through `BlendEffect`. Fine for
+  accents, ruinous for hundreds of objects. `normal`, `additive`, `multiply`,
+  `screen` and `exclusion` are ordinary fixed-function state and cost nothing
+  extra.
+- **3D meshes do not honour blend modes.** The mesh pass draws with its own
+  depth/blend state; asking for one of the advanced modes logs a one-time
+  `blend mode "…" is not supported for 3D meshes` warning and falls back to
+  `"normal"`. Gradient fills warn the same way.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| effect works locally, not for a user | they got the Canvas fallback, or a different GPU backend |
+| sprites render unlit though lights are in the scene | Canvas fallback — normal-map shading is inert (check the console) |
+| mesh looks inside-out where it overlaps itself | Canvas fallback — painter's algorithm, no depth buffer |
+| shader works on one machine only | GLSL-only effect, AUTO chose WebGPU elsewhere — the console carries the warning |
+| a solid box where an effect should be | carrier drawn while the effect is disabled |
+| nothing renders at all on an old device | `video.WEBGL` pinned; WebGL 1 is rejected, not downgraded |
+| ported shader is vertically flipped | the WebGL capture is bottom-up, the WebGPU one top-down |
+| a blended mode is ignored on a mesh | meshes fall back to `"normal"`; look for the one-time warning |
+| textures vanish after the tab is restored | cached raw GPU handles not re-acquired on context restore |
+
+## Related skills
+
+- `melonjs-getting-started` — renderer selection in the Application settings
+- `melonjs-effects-and-shaders` — dual-language shaders and the Canvas no-op
+- `melonjs-3d` — the tier that requires a GPU backend outright

package/skills/melonjs-scenes-and-state/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: melonjs-scenes-and-state
+description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
+license: MIT
+---
+
+# Scenes, game state and timing
+
+## Stages and the state manager
+
+A `Stage` is a screen. Register it against a state id, then change to it:
+
+```js
+import { Stage, state } from "melonjs";
+
+class PlayScreen extends Stage {
+    onResetEvent(app) { /* build the scene */ }
+    onDestroyEvent(app) { /* tear it down */ }
+}
+
+state.set(state.PLAY, new PlayScreen());   // register first
+state.change(state.PLAY);                   // then switch
+```
+
+Built-in ids: `state.LOADING`, `state.MENU`, `state.READY`, `state.PLAY`,
+`state.GAMEOVER` (no underscore), `state.GAME_END`, `state.SCORE`,
+`state.CREDITS`, `state.SETTINGS`, `state.DEFAULT`. `state.USER` (100) is the
+base for your own ids — `const CUTSCENE = state.USER + 1`.
+
+**Build scene content in `onResetEvent`, not the constructor.** `onResetEvent`
+runs on *every* entry to the state; the constructor runs once. Scene content
+created in the constructor exists once and is not rebuilt when you return.
+
+`onResetEvent(app)` receives the `Application` — use that rather than importing
+the global `game`.
+
+Extra arguments to `state.change` are forwarded:
+
+```js
+state.change(state.PLAY, false, { level: 2 });   // → onResetEvent(app, { level: 2 })
+```
+
+The second argument is `forceChange`: pass `true` to switch immediately instead
+of on a deferred tick, which is what you want when changing state right after a
+preload completes. It is ignored when a transition is configured — a transition
+always drives the switch from its own completion callback.
+
+`state.change` **throws** `Undefined Stage for state '<id>'` if nothing was
+registered for that id, and `state.set` throws if the second argument is not a
+`Stage` instance. Neither fails quietly.
+
+## Persistent objects across levels
+
+```js
+if (typeof this.HUD === "undefined") {
+    this.HUD = new Container();         // construct once (or UIBaseElement)
+}
+this.HUD.isPersistent = true;           // survives level changes
+this.HUD.floating = true;               // screen coordinates, not world
+app.world.addChild(this.HUD, 100);      // explicit z — see melonjs-renderables
+```
+
+## Transitions and pausing
+
+```js
+state.transition("fade", "#FFFFFF", 250);
+state.transition("mask", "#000", 500, new Ellipse(0, 0, 1, 1));  // shape required
+state.pause();                               // freeze update, keep drawing
+state.resume();
+app.freeze(150);                             // brief hit-stop (proxies state.freeze)
+```
+
+`state.transition` is global and sticky — once set it applies to every later
+`state.change`. The `"mask"` form needs its fourth argument, an `Ellipse` or
+`Polygon`; without one it warns and falls back to a direct switch.
+
+## The update loop
+
+There is no loop you own. Logic goes in `update(dt)` overrides, or a
+`GAME_UPDATE` subscription for scene-level animation:
+
+```js
+event.on(event.GAME_UPDATE, () => { /* per frame */ });
+```
+
+`update(dt)` must **return `true`** when the object changed and needs redrawing.
+Returning nothing is falsy and the object can appear frozen while its state moves.
+
+`dt` is milliseconds since the last frame and is the right basis for motion —
+the engine already paces it. Do not reach for `performance.now()`.
+
+A common idiom for a per-frame game controller with nothing to draw is a
+`Renderable(0, 0, 1, 1)` with `alwaysUpdate = true` and an empty `draw()`.
+
+## Timers: use the engine's, not the window's
+
+```js
+import { timer } from "melonjs";
+
+timer.setTimeout(fn, 1000);
+const id = timer.setInterval(fn, 500);
+timer.clearInterval(id);        // in the Stage's onDestroyEvent
+```
+
+`Stage` has only `onResetEvent` and `onDestroyEvent` — there is no
+`onActivateEvent` / `onDeactivateEvent` on a stage. Those two are `Renderable`
+hooks; put per-renderable teardown there instead.
+
+Engine timers are **pause-aware**. `window.setTimeout` keeps firing while the
+game is paused, which produces enemies spawning behind a pause menu. Pass
+`false` as the third argument — `timer.setInterval(fn, 500, false)` — for one
+that keeps running through a pause, which is what a pause-menu animation or a
+countdown that should not freeze needs. (That argument was ignored by
+`setInterval` before 20.3.)
+
+## Tweens
+
+```js
+import { Tween, pool } from "melonjs";
+
+const t = pool.pull("Tween", sprite.pos)   // registered name is "Tween"
+    .to({ x: 300 }, { duration: 500 })     // options object, not a number
+    .easing(Tween.Easing.Quadratic.Out)
+    .onComplete(() => { /* … */ })
+    .start();                    // ← without this, nothing happens
+```
+
+Four traps:
+
+- **A tween without `.start()`** (or `autoStart: true` in the `to()` options)
+  silently does nothing.
+- **`to()`'s second argument is an options object**
+  (`{ duration, easing, yoyo, repeat, delay, repeatDelay, interpolation,
+  autoStart }`). Passing a bare number is not a duration — it is read for a
+  `.duration` property, finds none, and the tween silently runs the default
+  1000 ms.
+- **Tweens freeze during `state.pause()` / `freeze()`** unless
+  `tween.updateWhenPaused = true` — which is how you get an effect that decays
+  *through* a hit-stop.
+- **Stop a tween before destroying its target**, or `onUpdate` fires against a
+  dead renderable.
+
+## Guard teardown-adjacent callbacks
+
+Callbacks can fire while a stage is being torn down, when the current state is
+already something else:
+
+```js
+if (!state.isCurrent(state.PLAY)) return;
+```
+
+Without the guard, a "children emptied" handler can reset the wrong stage.
+
+## Persistence
+
+```js
+import { save } from "melonjs";
+
+save.add({ hiscore: 0 });      // once; idempotent, loads any stored value
+save.hiscore = 1200;           // plain assignment writes to localStorage
+```
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| scene builds once and is empty on return | content created in the constructor, not `onResetEvent` |
+| `Undefined Stage for state 'N'` thrown | no `state.set` for that id first |
+| a tween finishes in 1000 ms whatever you pass | `to()` takes `{ duration }`, not a number |
+| object frozen while its state updates | `update()` not returning `true` |
+| timers fire behind a pause menu | `window.setTimeout` instead of `timer.setTimeout` |
+| a tween does nothing | `.start()` never called |
+| effect stops during a hit-stop | tween needs `updateWhenPaused = true` |
+| crash after a stage switch | callback ran during teardown — guard with `state.isCurrent` |
+| HUD scrolls away with the camera | missing `floating = true` |
+
+## Related skills
+
+- `melonjs-getting-started` — the Application and the first scene
+- `melonjs-renderables` — `floating`, draw order, update/draw contracts