spriteforge 0.1.1__py3-none-any.whl

spriteforge/skills/builtin/level-design/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: level-design
+description: >
+  Design and build playable levels — the blockout/whitebox-to-playable workflow,
+  player metrics and grid layout, pacing and flow (tension/rest curve), gating
+  and the critical path, and encounter design. Engine-neutral practice. Use when
+  the user mentions level design, blockout/whitebox/greybox, level layout, level
+  pacing, encounter design, or the critical path through a level.
+---
+
+# Level design
+
+A level is a **sequence of intentional experiences** delivered through space.
+Good level design is a *process*: define the metrics movement is built on, block
+out geometry with primitives, play it, then dress it — never the reverse. This
+skill is the engine-neutral practice; use `godot-tilemap`/`unity-tilemap-2d` to
+lay out 2D grids and gridmaps for 3D.
+
+## When to use
+
+- Use to plan a level's structure: critical path, pacing, gating, encounters,
+  and where the player learns vs is tested.
+- Use the **blockout → test → iterate → dress** workflow to build a level that
+  plays well before any art exists.
+- Use to derive level **metrics** from the character's movement so geometry is
+  reachable and fair.
+
+**When *not* to use:** to *generate* levels algorithmically, use `procedural-gen`
+(authored and procedural design are complementary). For the engine's tile/grid
+painting tools, use `godot-tilemap` / `unity-tilemap-2d`. For the movement
+abilities the metrics come from, that's the engine movement skill + `input-systems`.
+
+## Core workflow
+
+1. **Derive metrics first.** Measure the character: max jump height and distance,
+   run speed, reach, camera range. Every gap, ledge, and corridor is sized in
+   these units. Lock them before building geometry.
+2. **Blockout (whitebox/greybox).** Build the whole level from untextured
+   primitives at correct scale. Validate flow, sightlines, and reachability while
+   changes are cheap. No art yet. Tools: Godot `CSGBox3D` and friends with
+   `use_collision` on (prototype only: the docs flag their CPU cost, so bake to
+   static meshes later), Unity's ProBuilder package (`com.unity.probuilder`),
+   Unreal's Modeling Mode (Cube Grid), and a plain grey tileset for 2D.
+3. **Define the critical path** (start → goal) and the **golden path** you expect
+   most players to take. Layer optional/secret paths off it.
+4. **Pace the experience.** Alternate tension and rest in a deliberate curve;
+   don't run combat-combat-combat. Give the player room to breathe and to
+   anticipate.
+5. **Teach, then test.** Introduce each mechanic in a safe space, let the player
+   practice, then test it under pressure. Difficulty rises in a sawtooth, not a
+   straight line.
+6. **Gate with intent.** Use locks/keys, abilities, and one-way drops to control
+   order and pacing; guide with light, lines, and landmarks rather than walls.
+7. **Playtest and iterate.** Watch real players: where do they get lost, stuck,
+   bored, or killed unfairly? Fix the blockout; only dress when it plays well.
+
+## Patterns
+
+### 1. Player metrics drive every dimension
+
+```gdscript
+# Derive the metrics from the SAME constants the character controller uses, then
+# size geometry in these units. If the jump changes, the numbers follow.
+const RUN_SPEED      := 240.0   # px/s (or m/s in 3D)
+const JUMP_VELOCITY  := 420.0   # initial upward speed of a full jump
+const GRAVITY        := 980.0   # px/s², the value the controller applies
+const MAX_JUMP_H     := JUMP_VELOCITY * JUMP_VELOCITY / (2.0 * GRAVITY)  # 90: peak height
+const AIR_TIME       := 2.0 * JUMP_VELOCITY / GRAVITY   # ~0.86 s, take-off to same height
+const MAX_JUMP_DIST  := RUN_SPEED * AIR_TIME            # ~206: running jump, level ground
+const SAFE_GAP       := MAX_JUMP_DIST * 0.7   # comfortable, not pixel-perfect
+const HARD_GAP       := MAX_JUMP_DIST * 0.95  # a deliberate skill check
+# Build platforms so required jumps use SAFE_GAP; reserve HARD_GAP for optional reward.
+```
+
+The formulas are the ideal arc. Variable jump height, a separate fall gravity,
+air acceleration, the fixed physics step and the collider's width all move the
+real numbers, and landing higher shortens the reach. Confirm them once in a
+test room with a measured gap ladder, then treat the measured values as the
+truth. A platform placed `MAX_JUMP_DIST + 1` away is impossible; one at
+`SAFE_GAP` is fair. Keep these constants beside the level data so designers and
+code agree.
+
+### 2. Encounter / pacing as data (a tension timeline)
+
+```gdscript
+# Author the level as a sequence of beats with an intended intensity (0..1).
+# This makes the pacing curve explicit and reviewable before you build rooms.
+const BEATS := [
+    { "room": "entry",      "type": "teach",   "intensity": 0.1 },
+    { "room": "hall_1",     "type": "combat",  "intensity": 0.5 },
+    { "room": "vista",      "type": "rest",    "intensity": 0.1 },  # breather + reward
+    { "room": "gauntlet",   "type": "combat",  "intensity": 0.8 },
+    { "room": "save_room",  "type": "rest",    "intensity": 0.2 },  # before the boss
+    { "room": "boss",       "type": "climax",  "intensity": 1.0 },
+]
+# Read the intensity column top-to-bottom: it should rise overall but dip for rests
+# (a sawtooth), never flatline high. Drive spawns/music intensity from this.
+```
+
+### 3. Gating and the critical path (a small graph)
+
+```gdscript
+# Model the level as rooms + gated connections. Validate that the goal is
+# reachable with the keys/abilities the player can actually obtain in order.
+const ROOMS := {
+    "entry":   { "exits": [ { "to": "hall_1" } ] },
+    "hall_1":  { "exits": [ { "to": "vista", "needs": "double_jump" },
+                            { "to": "side_room" } ] },           # optional branch
+    "side_room": { "exits": [ { "to": "hall_1" } ], "grants": "double_jump" },
+    "vista":   { "exits": [ { "to": "boss", "needs": "red_key" } ] },
+}
+
+# Grow the reachable set until nothing new opens: collect what each reached room
+# grants, then follow every exit whose `needs` is already held. Assumes keys are
+# never used up and doors never re-lock; model consumable keys as counts.
+func goal_reachable(rooms: Dictionary, start: String, goal: String) -> bool:
+    var have := {}                                 # keys/abilities collected
+    var reached := {start: true}
+    var changed := true
+    while changed:
+        changed = false
+        for room in reached.keys():
+            var info: Dictionary = rooms.get(room, {})
+            var grant = info.get("grants")
+            if grant != null and not have.has(grant):
+                have[grant] = true
+                changed = true
+            for exit in info.get("exits", []):
+                var open: bool = not exit.has("needs") or have.has(exit["needs"])
+                if open and not reached.has(exit["to"]):
+                    reached[exit["to"]] = true
+                    changed = true
+    return reached.has(goal)
+# goal_reachable(ROOMS, "entry", "boss") is FALSE for the table above: no room
+# grants "red_key". That is exactly the soft-lock this check exists to catch.
+# Run it in a test or editor tool whenever the room graph changes.
+```
+
+## Pitfalls
+
+- **Dressing before it plays.** Detailing a blockout you haven't validated wastes
+  the most expensive work on a layout you'll change. Greybox and test first.
+- **Geometry that ignores metrics**: gaps the jump can't clear, ledges below
+  reach, corridors narrower than the camera needs. Size everything in player units.
+- **Flat pacing.** Wall-to-wall combat (or wall-to-wall calm) numbs the player.
+  Alternate tension and rest; place a breather and a save before the climax.
+- **Testing a mechanic before teaching it.** Players meet a hazard for the first
+  time in a lethal spot. Introduce safely, let them practice, then test.
+- **Soft-locks and dead ends.** A gate needs an ability/key obtainable only past
+  the gate. Validate the critical path's key/ability order, not just connectivity.
+- **No readability / guidance.** Players get lost when nothing draws the eye. Use
+  light, leading lines, color, and landmarks to point toward the path.
+- **One-way drops with no signposting** strand or surprise players. Telegraph
+  irreversible moves.
+- **Confusing procedural with authored.** Generation gives variety, not
+  authored pacing. Use `procedural-gen` for variety; hand-author for intent.
+
+## References
+
+- `references/pacing-and-flow.md` — the difficulty/tension curve in depth,
+  teaching-loop design (introduce→develop→twist→test), readability and guidance
+  techniques, 2D vs 3D layout considerations, and a blockout review checklist.
+
+## Related skills
+
+- `godot-tilemap`, `unity-tilemap-2d` — paint 2D level grids; gridmaps for 3D.
+- `procedural-gen` — generate variety to complement authored structure.
+- `game-ai` — encounter enemies that navigate the space you build.
+- `platformer`, `puzzle`, `roguelike` — genres that compose this skill.

spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: phaser-arcade-physics
+description: Implement Phaser 3 Arcade Physics movement, collision and lifecycle for small pixel games.
+---
+Use Phaser 3 browser scripts with no build step. Enable pixelArt and roundPixels,
+and keep logical screen size separate from CSS scaling. Use Arcade bodies for
+simple axis-aligned collision: top-down actors need a small foot collider rather
+than their entire 48x48 canvas. Normalize diagonal input and set velocity rather
+than accumulating per-frame displacement. Separate overlaps for damage from solid
+colliders. Register input and colliders once per scene and clean up on shutdown.
+Check walls, corners, simultaneous contacts, pause, restart and missing atlas keys.
+A sprite added to a physics group (`group.add`, `group.create`) takes the group's body
+defaults: its gravity, velocity, bounce and world-bounds settings are reset. Create the
+group with its defaults (`this.physics.add.group({gravityY: G})`) or set body properties
+after adding it. Side-view actors that walk on the ground need gravity and a collider with
+the floor; spawn them with their feet on it, never hanging at a fixed height.
+Use the Phaser 3 documentation: https://docs.phaser.io/phaser/concepts/physics/arcade

spriteforge/skills/builtin/physics-tuning/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: physics-tuning
+description: >
+  Tune game physics for stable, good-feeling motion — fixed vs variable
+  timestep, render interpolation, mass/gravity/drag, continuous collision
+  detection (CCD) to stop tunneling, fixing jitter, and collision layers/masks.
+  Engine-neutral. Use when the user mentions physics feel, jitter, tunneling,
+  fixed timestep, FixedUpdate, CCD, bouncing/unstable physics, or collision layers.
+---
+
+# Physics tuning
+
+Most "bad physics" is not a bug in the engine — it's a mismatch between the
+**fixed-timestep simulation** and the **variable-rate render loop**, or untuned
+mass/drag/CCD/layer settings. This skill covers the engine-neutral knobs that
+make physics stable and responsive; pair it with `godot-physics` or
+`unity-physics` for the concrete APIs.
+
+## When to use
+
+- Use when motion jitters, objects pass through walls (tunneling), stacks
+  explode, or movement feels floaty/sticky/laggy.
+- Use to decide what goes in the fixed (physics) step vs the render frame, and
+  how to interpolate between them.
+- Use to tune gravity, mass, drag, restitution, solver iterations, sleeping, and
+  collision layers/masks.
+
+**When *not* to use:** for an engine's exact physics nodes/components and
+collision callbacks, use `godot-physics` or `unity-physics`. For *movement
+decisions* (when to jump, AI steering) use `input-systems` and `game-ai`. For
+platformer jump-feel specifics like coyote time/jump buffering, that's input/
+controller territory — see `input-systems` and the `platformer` genre.
+
+## Core workflow
+
+1. **Run physics on a fixed timestep.** Simulate at a constant rate (e.g. 50–60
+   Hz). A fixed `dt` makes the simulation deterministic-ish and stable; a
+   variable `dt` makes integration and collisions inconsistent.
+2. **Put physics work in the physics callback**, not the render frame. Apply
+   forces/velocities and read collisions in the fixed step (`FixedUpdate` /
+   `_physics_process`), using that step's `dt`.
+3. **Interpolate rendering between physics ticks.** The render frame rate ≠ the
+   physics rate, so smoothly interpolate transforms toward the latest physics
+   state, or enable the engine's Rigidbody interpolation, to remove visible
+   stutter.
+4. **Tune the body, not the scene.** Set mass for relative weight, drag for
+   damping, gravity scale per object, and restitution/friction via materials.
+5. **Stop tunneling with CCD** on small/fast bodies; cap maximum velocity.
+6. **Stabilize stacks/joints** with more solver iterations, sane mass ratios, and
+   sleeping for resting bodies.
+7. **Verify by feel and stress test.** Play at low and high frame rates; throw
+   fast objects at thin walls; stack and shove bodies. Report what you observed.
+
+## Patterns
+
+### 1. Fixed timestep for simulation, render interpolation for smoothness
+
+```gdscript
+# Physics callback: runs at the FIXED rate. Use its dt for all integration.
+func _physics_process(dt):                  # Unity: void FixedUpdate()
+    velocity += gravity * dt                # integrate with the FIXED dt
+    move_and_slide()                        # engine resolves collisions this step
+    _prev_pos = _curr_pos; _curr_pos = global_position   # record for interpolation
+
+# Render frame: runs as fast as the display. Interpolate between physics states.
+func _process(_frame_dt):                   # Unity: void Update()
+    var alpha = Engine.get_physics_interpolation_fraction()  # 0..1 within the tick
+    visual.global_position = _prev_pos.lerp(_curr_pos, alpha)
+# RIGHT: integrate in the fixed step, render via interpolation.
+# WRONG: applying forces in _process/Update with frame dt — speed and collisions
+# then depend on frame rate and jitter under load.
+```
+
+Most engines offer this for you: Godot's project setting
+`physics/common/physics_interpolation` (off by default; it interpolates every
+node, 2D and 3D) and Unity's `Rigidbody.interpolation = Interpolate`. Prefer the
+built-in before hand-rolling, and never do both on the same node.
+
+### 2. Stop tunneling: CCD + a speed cap
+
+```gdscript
+# Fast, small bodies skip past thin colliders between ticks. Two fixes:
+body.continuous_cd = true            # RigidBody3D bool (RigidBody2D: CCD_MODE_* enum)
+# Unity: rb.collisionDetectionMode = CollisionDetectionMode.ContinuousSpeculative (cheap, covers
+# dynamic bodies too) or ContinuousDynamic (fast vs fast); plain Continuous sweeps vs static only.
+# Cap velocity so a single step can't move more than ~one collider thickness.
+const MAX_SPEED := 40.0
+if velocity.length() > MAX_SPEED:
+    velocity = velocity.normalized() * MAX_SPEED
+# Rule of thumb: max_distance_per_step (= speed / physics_hz) should be < the
+# thinnest wall. Raise physics_hz or enable CCD when that fails.
+```
+
+### 3. Body tuning: mass, drag, gravity scale, material
+
+```gdscript
+# Mass is RELATIVE weight in collisions; it does NOT change fall speed (gravity
+# accelerates all masses equally). Use drag and gravity_scale to shape feel.
+body.mass = 2.0                      # heavier pushes lighter in collisions
+body.linear_damp = 0.5               # air drag: higher = stops sooner (Unity 6: linearDamping, was drag)
+body.gravity_scale = 1.5             # per-object gravity multiplier (Unity: Rigidbody2D.gravityScale)
+# Bounce/slide come from the physics material, not code:
+material.bounce = 0.2                # restitution 0..1 (Unity: PhysicsMaterial.bounciness)
+material.friction = 0.8              # surface grip
+body.physics_material_override = material
+```
+
+### 4. Collision layers and masks (who collides with whom)
+
+```gdscript
+# A body is ON its layer(s) and SCANS the layers in its mask. Both directions of a
+# pair must be configured for them to interact.
+player.collision_layer = LAYER_PLAYER
+player.collision_mask  = LAYER_WORLD | LAYER_ENEMY     # player detects world+enemies
+pickup.collision_layer = LAYER_PICKUP
+pickup.collision_mask  = LAYER_PLAYER                  # pickup only reacts to player
+# Unity equivalent: assign GameObject layers and edit the Physics collision matrix
+# (or Physics.IgnoreLayerCollision). Keep a named layer constant table, not magic numbers.
+```
+
+## Pitfalls
+
+- **Applying forces/movement in the render frame** (`Update`/`_process`) makes
+  behavior frame-rate dependent — faster PCs run faster, and collisions get
+  flaky. Do simulation in the fixed step.
+- **Visible jitter** even with a fixed step usually means no render
+  interpolation: the physics rate and display rate beat against each other.
+  Enable interpolation.
+- **Tunneling** through thin walls: discrete collision misses fast movers. Enable
+  CCD, cap speed, thicken walls, or raise the physics rate.
+- **Expecting heavier objects to fall faster.** Gravity is acceleration; mass
+  affects collision response, not fall speed. Use `gravity_scale`/drag for feel.
+- **Exploding stacks / jittery joints**: mass ratios too extreme, or too few
+  solver iterations. Keep mass ratios modest and raise iteration counts.
+- **Bodies that never rest** burn CPU and twitch. Enable sleeping and a sensible
+  sleep threshold for resting objects.
+- **One-directional layer setup**: A's mask includes B but B's mask excludes A.
+  Detection/collision can need both sides; verify the full matrix.
+- **Huge `dt` spikes** (load hitches, breakpoints) blow up integration. Clamp the
+  max physics step / substep count so a stall doesn't launch everything (Godot
+  `physics/common/max_physics_steps_per_frame`, Unity *Maximum Allowed Timestep*).
+- **Teleports smear across the screen** with interpolation on: the renderer
+  blends from the old position. Godot: call `reset_physics_interpolation()`
+  *after* moving the node. Unity: move interpolated bodies through the
+  Rigidbody; a direct `transform` write is ignored unless followed by
+  `Physics.SyncTransforms()`.
+- **Feel changes after raising the physics rate**: Godot (GodotPhysics and Jolt
+  alike) damps by multiplying velocity by `1 - damp / ticks_per_second` each
+  tick, an approximation that drifts as `damp` approaches the tick rate (at
+  `damp >= ticks_per_second` the body stops in one tick). Small damping values
+  barely change; re-tune large ones after changing `physics_ticks_per_second`.
+
+## References
+
+- `references/timestep-and-ccd.md` — the fixed-timestep accumulator loop,
+  interpolation math, substepping, CCD modes, solver/iteration tuning, sleeping,
+  and a stability checklist.
+
+## Related skills
+
+- `godot-physics`, `unity-physics` — concrete bodies, colliders, and callbacks.
+- `input-systems` — responsive controls, jump buffering, coyote time.
+- `game-ai` — agent movement that must agree with the physics step.
+- `platformer`, `fps-shooter` — genres whose feel depends on this tuning.

spriteforge/skills/builtin/pixel-art-prompting/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: pixel-art-prompting
+description: Prompt Muse Image for readable chunky sprites matching an approved palette and style anchor.
+---
+Use the approved style.json and anchor. Request one centered full-body subject on
+a flat solid magenta field, with chunky pixel clusters, consistent top-left light,
+and no text, watermark, gradients or anti-aliasing. A 48x48 character canvas should
+contain about 40x40 logical pixels of artwork. Requested provider dimensions are
+not guaranteed: process the decoded image and inspect the detected grid and logical
+size. Preserve accepted assets; use an edit reference for approved pose changes.
+Inspect at native size and nearest-neighbor enlargement. Report palette, outline,
+background-spill and silhouette failures instead of hiding them in the prompt.

spriteforge/skills/builtin/platformer/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: platformer
+description: >
+  Build a 2D platformer: run/jump control with coyote time, jump buffering, and variable jump
+  height, wall slide and wall jump, plus tiled levels and hazards. Use for a platformer or
+  Mario/Celeste-like, or tuning jump feel.
+---
+
+# Platformer
+
+A playbook for 2D platformers — the run/jump controller "feel", level structure, hazards,
+and goals. This is a **compositional** skill: it wires an engine movement skill, a tilemap
+skill, and design skills into a working game. It does **not** re-teach physics or tilemaps;
+it tells you what to build and how to make jumping feel good.
+
+## When to use
+
+- Use when building a side-scrolling or single-screen platformer, a "Mario-like" /
+  "Celeste-like", or any game whose core verb is **jump between surfaces**.
+- Use when a jump feels floaty, unresponsive, or "unfair" and you need feel fixes
+  (coyote time, jump buffering, variable height, corner correction).
+
+**When *not* to use:** top-down movement with no gravity → use the engine movement skill
+directly. 3D first-person traversal → `fps-shooter`. Grid/turn movement → `roguelike`.
+For the raw kinematic body API, use `godot-2d-movement` (or your engine's controller skill).
+
+## Core loop
+
+**Observe a gap/hazard → commit to a jump or move → land safely (or die) → reach the next
+checkpoint/goal.** A platformer lives or dies on the *moment-to-moment* feel of that single
+jump, repeated thousands of times. Tighten the controller first; everything else is content.
+
+## Must-have systems
+
+1. **Run/jump controller** — horizontal accel/decel, gravity, jump, with the feel aids below.
+2. **Solid + one-way collision** — ground, walls, and "jump-through" platforms.
+3. **Level geometry** — a tilemap or hand-placed colliders; the playable space.
+4. **Hazards + death/respawn** — spikes, pits, enemies; reset to the last checkpoint.
+5. **Checkpoints / level goal** — progress markers and a win condition (flag, door, exit).
+6. **Camera** — follows the player with a deadzone and look-ahead, clamped to level bounds.
+7. **Juice** — landing dust, squash/stretch, hit-stop, sound. Cheap, huge feel payoff.
+
+## Design knobs (make the jump feel right)
+
+Tune these by **outcome** (height in tiles, time to apex in seconds), not by raw numbers.
+
+| Knob | Effect | Sane starting point |
+|------|--------|---------------------|
+| Max jump height | reach | 3–4 tiles |
+| Time to apex | "weight"/snappiness | 0.30–0.40 s |
+| Fall gravity multiplier | snappy, non-floaty fall | 1.5–2.0× rise gravity |
+| Coyote time | jump just after leaving a ledge | 0.08–0.12 s (~5–7 frames @60) |
+| Jump buffer | press just before landing still jumps | 0.10–0.15 s |
+| Variable jump cut | tap = short hop, hold = full | cut upward velocity ×0.4–0.5 on release |
+| Apex hang | brief float at the top for air control | reduce gravity ×0.5 near `|vy|`<threshold |
+| Ground accel / friction | responsiveness vs. ice | reach top speed in 0.05–0.1 s |
+| Corner correction | nudge past a ledge clipped by 1–2 px | nudge up to ~4 px sideways |
+| Wall slide / wall jump | controlled descent and kick-off | wall grace, kick/steering lock, air-jump refresh policy; see refs §9 |
+
+Derive gravity and jump velocity from the *feel* values rather than guessing — see Pattern 1.
+
+## Patterns
+
+### 1. Solve jump physics from height + time (not magic numbers)
+
+```python
+# Pseudocode. Pick the FEEL you want, then derive the physics. y-axis points DOWN.
+# From kinematics: h = (g * t^2) / 2  and  v0 = g * t.
+JUMP_HEIGHT   = 3.5 * TILE      # how high, in world units
+TIME_TO_APEX  = 0.35            # seconds to reach the top
+
+gravity       = (2 * JUMP_HEIGHT) / (TIME_TO_APEX ** 2)   # rising gravity
+jump_velocity = -(2 * JUMP_HEIGHT) / TIME_TO_APEX         # negative = upward
+fall_gravity  = gravity * 1.8   # heavier on the way down → less floaty
+```
+
+### 2. Coyote time + jump buffer + variable height (the feel core)
+
+For wall or air jumps, replace this simple jump resolver with the unified resolver in refs §9;
+keep variable-height and gravity integration only once per tick.
+
+```python
+# Pseudocode in the per-frame update. dt = seconds since last frame.
+# Timers count DOWN; refresh coyote while grounded, buffer on a fresh press.
+if on_floor:
+    coyote_timer = COYOTE_TIME           # 0.1
+if jump_pressed_this_frame:
+    buffer_timer = JUMP_BUFFER           # 0.12
+coyote_timer -= dt
+buffer_timer -= dt
+
+# A jump is allowed if we pressed recently AND were grounded recently.
+if buffer_timer > 0 and coyote_timer > 0:
+    velocity.y   = jump_velocity
+    buffer_timer = 0
+    coyote_timer = 0                     # consume both so we can't double-jump
+
+# Variable height: releasing jump early while still rising cuts the arc short.
+if jump_released_this_frame and velocity.y < 0:
+    velocity.y *= 0.45
+
+# Asymmetric gravity: snappier fall than rise; clamp to a terminal speed.
+g = fall_gravity if velocity.y > 0 else gravity
+velocity.y = min(velocity.y + g * dt, MAX_FALL_SPEED)
+```
+
+### 3. One-way platforms
+
+Solid from above, pass-through from below. Use the engine's flag rather than collision math:
+Godot `CollisionShape2D.one_way_collision` (or the one-way option on a TileSet collision
+polygon), Unity a `PlatformEffector2D` with **Use One Way** on a collider set to be used by the
+effector, Phaser Arcade `platform.body.checkCollision.down = false` (plus `left`/`right` for thin
+ledges). Let the player **drop through** by ignoring that platform for ~0.1–0.2 s when they hold
+Down + Jump (refs §5).
+
+## Pitfalls / failure modes
+
+- **Per-frame movement not scaled by `dt`** → speed changes with frame rate. Every velocity
+  integration and timer must use `dt`. (See `physics-tuning`.)
+- **Jump height differs between machines** → the jump runs on a variable render `dt`. Simple
+  per-step integration lands a few percent short of the designed height, by a different amount
+  at each frame rate. Run the controller on the fixed physics tick (Godot `_physics_process`,
+  Unity `FixedUpdate`) or use the half-step update in refs §1.
+- **Player is flung off or doubles speed leaving a moving platform** → platform velocity added
+  twice. Godot's `CharacterBody2D` already carries the body and adds the platform's velocity on
+  leave (`platform_on_leave`); don't add it again in script (refs §6).
+- **Floaty jumps** → symmetric gravity. Make fall gravity heavier than rise gravity.
+- **"The jump didn't register"** → no input buffering. Buffer presses for ~0.1 s before landing.
+- **"I fell off and couldn't jump"** → no coyote time. Allow a jump for ~0.1 s after leaving ground.
+- **Wall jump overrides a ground jump or consumes the double jump** → resolve one buffered
+  press in ground/coyote → wall → air order, with an explicit air-jump refresh policy (refs §9).
+- **Sticking to walls / catching on tile seams** → use a single capsule/box collider, not
+  per-tile colliders, and add corner correction.
+- **Tunneling through floors at high speed** → enable continuous collision / smaller fixed
+  timestep for fast bodies (see `physics-tuning`).
+- **Camera snaps and induces nausea** → smooth/lerp the follow, add a deadzone, clamp to bounds.
+- **Difficulty wall from bad teaching** → introduce one mechanic per area before combining them.
+
+## Composition (build it from these skills)
+
+- **Controller body:** `godot-2d-movement` (Godot `CharacterBody2D`); for other engines use
+  the engine core + physics skill (`unity-physics`, `phaser-arcade-physics`, `pygame-core`).
+- **Levels:** `godot-tilemap` / `unity-tilemap-2d` for geometry; `level-design` for layout,
+  pacing, and teaching order.
+- **Feel/physics:** `physics-tuning` for timestep, CCD, and stability.
+- **Input:** `input-systems` for buffering, rebinding, and gamepad support.
+- **Polish:** `audio-design` for SFX/music; the engine animation skill for squash/stretch.
+- **Process:** `prototype-fast` to greybox the controller before building content.
+
+## References
+
+- For jump math derivation, wall slide/jump, a full feel-tuning table, corner correction, moving/one-way
+  platforms, and camera follow, read `references/feel-tuning.md`.

spriteforge/skills/builtin/puzzle/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: puzzle
+description: >
+  Build a puzzle game: grid/board state, move input, rule-based resolution (match-3 cascades, sokoban
+  pushes, tile logic), scoring, and undo. Use for a match-3, sokoban, or grid-logic puzzle.
+---
+
+# Puzzle
+
+A playbook for grid/board puzzle games — the board model, move input, rule resolution
+(matching, pushing, logic), scoring, undo, and level progression. This is a **compositional**
+skill: it models board state and rules and presents them through a tilemap/UI. It does not
+re-teach tilemaps; it defines the resolution loop and the correctness rules (clean state,
+deterministic resolution, undo) that keep a puzzle fair and bug-free.
+
+## When to use
+
+- Use when the game is a **discrete board** the player changes with moves, and the board
+  **resolves by rules**: match-3/tile-matching, sokoban/block-pusher, sliding puzzle, logic grid.
+- Use when designing match/cascade resolution, undo, level progression, or solvability.
+
+**When *not* to use:** real-time grid action with permadeath → `roguelike`. Card zones/turns →
+`card-game`. Physics-based "puzzle platformer" → `platformer` + `physics-tuning`. For the tile
+rendering, use `godot-tilemap` / `unity-tilemap-2d`.
+
+## Core loop
+
+**Read the board → plan a move → make the move → the board resolves by its rules (match, push,
+fall, fill, cascade) → see progress toward the objective → repeat until solved/failed.** The
+fun is the *planning*; the engine's job is to resolve each move **deterministically** and
+present it clearly.
+
+## Must-have systems
+
+1. **Board model** — a grid of cells holding pieces; the single source of truth (logic, not visuals).
+2. **Move input** — swap, push, drag, rotate, or place; validate legality before applying.
+3. **Rule resolution** — detect and apply the genre's rule (matches, pushes, logic) until stable.
+4. **Cascades/chains** — when resolution changes the board, re-resolve until no more changes.
+5. **Objectives + scoring** — win/lose conditions (score, clear all, reach goal); move/time limits.
+6. **Undo** — revert the last move (and its resolution) exactly; essential for thinky puzzles.
+7. **Level progression + (often) generation** — hand-authored or generated **solvable** boards.
+8. **Feedback ("juice")** — clear, satisfying animation/sound for matches, falls, and chains.
+
+## Design knobs
+
+| Knob | Effect | Notes |
+|------|--------|-------|
+| Grid size / shape | complexity | Square is standard; hex/irregular change feel. |
+| Match/push rule | genre identity | 3-in-a-row, shapes, push-into-goal, etc. |
+| Cascade scoring | reward depth | Bigger chains = exponential payoff. |
+| Move / time limit | pressure | Move-limited = puzzly; time = arcade. |
+| Difficulty curve | learning | Introduce one mechanic at a time. |
+| Undo depth | forgiveness | Single-step vs. full history. |
+| Solvability guarantee | fairness | Generated boards must be solvable. |
+| Deadlock handling | no dead ends | Detect no-moves; shuffle or end (refs). |
+
+## Patterns
+
+### 1. Board model + match detection (logic separate from visuals)
+
+```python
+# Pseudocode. The board is the truth; rendering reads from it. (0,0) top-left, y grows down.
+board = [[piece_or_empty for _ in range(W)] for _ in range(H)]
+
+def find_matches(board):
+    matched = set()
+    for y in range(H):                       # horizontal runs of >= 3 equal pieces
+        run = 1
+        for x in range(1, W):
+            if board[y][x] and board[y][x] == board[y][x-1]: run += 1
+            else:
+                if run >= 3: matched |= {(y, k) for k in range(x-run, x)}
+                run = 1
+        if run >= 3: matched |= {(y, k) for k in range(W-run, W)}
+    # ... repeat the same scan vertically (columns) ...
+    return matched
+```
+
+### 2. Resolve → collapse → refill → cascade (repeat to stability)
+
+```python
+# Pseudocode. One player move can trigger a chain; loop until the board stops changing.
+def resolve(board):
+    chain = 0
+    while True:
+        matches = find_matches(board)
+        if not matches: break                 # stable: resolution complete
+        chain += 1
+        score += score_for(matches, chain)    # later chain steps score more (see refs)
+        clear(board, matches)                  # remove matched pieces
+        apply_gravity(board)                   # pieces fall into the gaps
+        refill(board, rng)                      # spawn new pieces at the top (seeded RNG)
+    return chain
+```
+
+### 3. Undo via state snapshot or command
+
+```python
+# Pseudocode. Snapshot before each move; undo restores it exactly (board + score + counters + RNG).
+def make_move(move):
+    history.append(snapshot(board, score, moves_left, rng.state))   # push BEFORE applying
+    apply(move); resolve(board); moves_left -= 1
+
+def undo():
+    if history:
+        board, score, moves_left, rng.state = history.pop()   # exact revert, including refills
+```
+
+For large boards prefer the **command** pattern (store the move + enough to invert it) over full
+snapshots to save memory; snapshots are simplest and fine for small boards.
+
+## Pitfalls / failure modes
+
+- **Mixing logic and visuals** → animations desync from state and cause bugs. The board model is
+  the single source of truth; the view only renders it.
+- **Resolving only once** → cascades/chains are missed. Loop resolution until the board is stable
+  (Pattern 2).
+- **Undo that doesn't restore everything** → score/move-count/random-state drift. Snapshot *all*
+  state, or make the move fully invertible. If undo skips the RNG state, redoing the same move
+  refills different pieces and players learn to "reroll" by undoing.
+- **Unseeded refill RNG** → can't reproduce a level / no deterministic undo or daily puzzle. Seed it.
+- **Generated boards that aren't solvable** → unfair dead ends. Generate-and-verify, or generate
+  from a known solution backward (refs). A sliding-tile puzzle filled by a random shuffle is
+  unsolvable half the time; check the parity rule in refs §7.
+- **No deadlock detection** (match-3) → board with no valid moves softlocks. Detect "no moves"
+  and shuffle or end the level (refs).
+- **Difficulty spikes** → too many mechanics at once. Teach one mechanic per level before combining.
+- **Resolution mid-animation accepts input** → double-moves/corruption. Lock input until the
+  board is stable.
+
+## Composition (build it from these skills)
+
+- **Board rendering:** `godot-tilemap` / `unity-tilemap-2d` for the grid; `godot-ui-control` for HUD, score, and menus.
+- **Levels:** `level-design` for hand-authored puzzles and difficulty pacing; `procedural-gen` for solvable generated boards.
+- **Persistence:** `save-systems` for level progress, high scores, and seeded daily puzzles.
+- **Juice:** `game-feel` for match/cascade pop, screen shake, and chain feedback; the engine animation/`Tween` skill for swaps/falls/clears; `audio-design` for match and chain cues.
+- **Scripting:** `godot-gdscript` / `unity-csharp-scripting` for the resolution loop and rules.
+
+## References
+
+- For match-3 detection/gravity/refill/cascade detail, deadlock detection and reshuffles,
+  sokoban/rule-based puzzles, undo strategies, solvable generation, and scoring, read
+  `references/board-and-resolution.md`.