summer-engine 2.8.1 → 3.0.0

package/library/skills/brainstorming/resource.yaml

@@ -0,0 +1,23 @@
+id: skill/brainstorming
+kind: skill
+version: 1.0.3
+summary: "Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior."
+use_when:
+  - starting creative work — designing a game, picking a mechanic, building features or components, modifying behavior
+  - a request is ambiguous about goals or constraints and work would otherwise start on guesses
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - game-design
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/workflow/brainstorming

package/{skills/workflow → library/skills}/brainstorming/spec-document-reviewer-prompt.md

@@ -4,7 +4,7 @@ Use this template when dispatching a spec document reviewer subagent.
 
 **Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
 
-**Dispatch after:** Spec document is written to docs/superpowers/specs/
+**Dispatch after:** Spec document is written to `.summer/specs/` in the game project
 
 ```
 Task tool (general-purpose):

package/{skills/scene-and-project → library/skills}/browse-templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse-templates
-description: Use when the user wants to see available Summer Engine project templates, start from an existing template, or asks "what templates exist?" — fetches the live list from github.com/SummerEngine, presents the choices, and creates a project from the chosen template via `summer create <slug> <project-name>`. Trigger on "templates", "starter", "boilerplate", "from a template", "what's available", "show me templates", "third-person", "platformer", "multiplayer starter".
+description: Use when the user wants to see available Summer Engine project templates, start from an existing template, or asks "what templates exist?" — lists the pinned template registry via `summer list templates`, presents the choices, and creates a project from the chosen template via `summer create <slug> <project-name>`. Trigger on "templates", "starter", "boilerplate", "from a template", "what's available", "show me templates", "third-person", "platformer", "multiplayer starter".
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project
@@ -9,9 +9,9 @@ allowed-tools: Bash Read summer_get_project_context
 paths: ["**/project.godot"]
 ---
 
-# /browse-templates — Pick a community template and clone it
+# /browse-templates — Pick a registry template and create a project from it
 
-Summer's community templates live in [github.com/SummerEngine](https://github.com/orgs/SummerEngine/repositories) under `template-*` repos: `template-3d-third-person-controller`, `template-3d-lan-multiplayer-starter`, `template-2d-platformer`, and so on. They're working starter projects — open in Summer Engine and play immediately.
+Summer's templates are the pin manifests in `library/templates/<slug>/resource.yaml`, compiled into `registry/generated/templates-registry.json`: `3d-third-person-controller`, `3d-lan-multiplayer-starter`, `2d-platformer`, and so on. Each pinned template names a repo, an exact commit, and a tree digest; the two built-ins (`empty`, `3d-basic`) are generated locally. They're working starter projects — open in Summer Engine and play immediately.
 
 ## When to use this skill
 
@@ -22,7 +22,7 @@ Summer's community templates live in [github.com/SummerEngine](https://github.co
 
 ## When NOT to use this skill
 
-- User says "blank project" / "empty project" / "from scratch" → use `summer:new-project`.
+- User says "blank project" / "empty project" / "from scratch" → use `new-project`.
 - User wants to *make* a new template (contribute one) → that's not this skill; point them at the README's contributing section.
 
 ## Steps
@@ -33,15 +33,15 @@ Summer's community templates live in [github.com/SummerEngine](https://github.co
 summer list templates
 ```
 
-That hits the GitHub org API and prints both built-in templates (offline-friendly) and community templates with descriptions. **Always run this first — never recommend a template from memory.** The list evolves; what you remember may be stale, archived, or renamed.
+That prints the template registry — built-ins and pinned templates with status, systems, and preview notes. It reads the registry only; it does not query GitHub. **Always run this first — never recommend a template from memory.** The list evolves; what you remember may be stale, retired, or renamed.
 
-If the command errors out (rate-limit, offline), tell the user and offer the built-ins (`empty`, `3d-basic`) plus the canonical URL: [github.com/SummerEngine](https://github.com/orgs/SummerEngine/repositories).
+If the command errors out, tell the user and offer the built-ins (`empty`, `3d-basic`), which need no network.
 
 ### 2. Help the user pick
 
 If the user has a specific game shape in mind, narrow before showing all options:
 
-> "Looking for a third-person 3D template — `3d-third-person-controller` looks right. Want me to clone it as `my-game`?"
+> "Looking for a third-person 3D template — `3d-third-person-controller` looks right. Want me to create it as `my-game`?"
 
 If they're undecided, show 3–5 options grouped by genre, with a one-line description each. **Don't dump the full list.** A long menu freezes decisions.
 
@@ -51,7 +51,7 @@ Default is the template slug (so `3d-third-person-controller` → directory `3d-
 
 > "What do you want to call your project? (default: `3d-third-person-controller`)"
 
-### 4. Clone
+### 4. Create
 
 ```
 summer create <template-slug> <project-name>
@@ -64,9 +64,9 @@ summer create 3d-third-person-controller hero-game
 ```
 
 This:
-- Clones the latest `main` (or default branch) of `template-3d-third-person-controller`
+- Fetches the exact commit pinned in the registry entry — never a default branch — and refuses if the tree digest does not match
 - Drops the `.git` directory so the user starts with their own history
-- Prints the source URL for transparency
+- Records the template pin into the project's `.summer/project.json` and prints the source for transparency
 
 Pass `--keep-git` if the user wants the upstream history (rare).
 
@@ -76,7 +76,7 @@ Pass `--keep-git` if the user wants the upstream history (rare).
 summer run <project-name>
 ```
 
-Confirm it opens. Then invoke `summer:play` to verify the template runs as expected before doing any custom work on top.
+Confirm it opens. Then invoke `play` to verify the template runs as expected before doing any custom work on top.
 
 ## Anti-patterns
 
@@ -85,21 +85,21 @@ Confirm it opens. Then invoke `summer:play` to verify the template runs as expec
 | Recommend a template from memory | List evolves. `summer list templates` is the source of truth. |
 | Dump the full template list as a wall of text | 5 curated picks beats 20 generic ones. Match to user intent. |
 | Default the project name to the slug | `3d-third-person-controller/` is a UX-hostile directory name. Always ask. |
-| Skip `summer run` after cloning | Templates can break upstream — verify the user has a working baseline before they edit. |
-| Clone into an existing directory | The CLI errors out; respect that and ask for a different name. |
+| Skip `summer run` after creating | Verify the user has a working baseline before they edit. |
+| Create into an existing directory | The CLI errors out; respect that and ask for a different name. |
 
 ## Edge cases
 
 - **`git` not installed** → `summer create` errors with a clear message. Tell the user to install git, or fall back to a built-in template.
-- **Template archived or moved** → the API filter excludes archived repos. If a user names one explicitly that's gone, the create command lists what's currently available.
-- **Network down** → fall back to `empty` or `3d-basic`. Don't pretend the remote ones exist.
+- **Template retired or renamed** → it leaves the registry (renames leave an alias). If a user names one explicitly that's gone, the create command lists what's currently available.
+- **Network down** → pinned templates cannot be fetched; fall back to `empty` or `3d-basic`, which are generated locally.
 
 ## After the user is in
 
 Once the project is created and running, hand off cleanly. The next skill that fires depends on the template:
 
-- Third-person controller → likely `summer:scene-composition` or `summer:gdscript-patterns` next.
-- Multiplayer starter → `summer:setup-multiplayer` or `summer:host-authoritative-state`.
-- 2D platformer → `summer:design-mechanic` for the platforming feel, then `summer:design-level`.
+- Third-person controller → likely `scene-composition` or `gdscript-patterns` next.
+- Multiplayer starter → `setup-multiplayer` or `host-authoritative-state`.
+- 2D platformer → `design-mechanic` for the platforming feel, then `design-level`.
 
 Don't auto-fire the next skill — wait for the user to say what they want to change first.

package/library/skills/browse-templates/resource.yaml

@@ -0,0 +1,23 @@
+id: skill/browse-templates
+kind: skill
+version: 1.0.4
+summary: List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create.
+use_when:
+  - the user wants to see available Summer Engine project templates, start from an existing template, or asks what templates exist
+  - picking a starting point and unsure which starter templates already exist
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - project
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/scene-and-project/browse-templates

package/library/skills/celeste-momentum-platforming/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: celeste-momentum-platforming
+description: "Use when building or tuning Celeste-style momentum-based precision platformer movement in SummerEngine (Godot 4): tuned gravity/fall, run acceleration, variable-height jumps with coyote time, dashes, wall jumps/slides, climb stamina, and pixel-scale corner correction, using the exact tuning constants extracted from Celeste's open-source Player class."
+license: MIT
+category: game-feel
+tags:
+  - platformer
+  - movement
+  - game-feel
+  - controller
+  - godot4
+confidence: extracted
+---
+
+# Celeste-Style Momentum Platforming (Movement System)
+
+## Outcome
+
+A 2D character controller for SummerEngine that reproduces the tuning architecture and forgiveness mechanics of Celeste's player movement: momentum-based running with distinct ground/air acceleration, variable-height jumping with coyote time, a multi-directional dash with cooldown and residual speed, wall interaction (jump, slide, climb with stamina), and pixel-scale corner corrections that make near-miss inputs succeed instead of fail.
+
+## When to Use
+
+- Building a precision 2D platformer in SummerEngine where movement feel is the core gameplay.
+- Porting or prototyping Celeste-style mechanics (dash, wall jump, climb stamina).
+- Tuning an existing platformer controller that feels "unfair" or unresponsive — the forgiveness systems below are the primary fix.
+
+Do not use for: 3D character controllers, physics-driven (RigidBody) movement, or games where floaty/arcade jump physics are desired over momentum precision.
+
+## Core Principle
+
+Celeste's movement is a **single controller class driven by an explicit integer state machine**, with all feel-critical numbers as a **flat compile-time constants table** at the top of the class. The retrieved source (Player.cs, 5,471 lines) defines states `Normal=0, Climb=1, Dash=2, Swim=3, Boost=4, RedDash=5, HitSquash=6, Launch=7, Pickup=8, DreamDash=9` (+ a Summit state), each with Begin/Update/End callbacks. State transitions are direct integer assignments.
+
+The second principle: **forgiveness at the pixel and millisecond scale**. The code repeatedly nudges the player 2–6 pixels or grants 50–200 ms windows so that inputs which are *almost* correct still succeed. This is the source of the "tightest" feel described in the originating post.
+
+## Tuning Constants (verbatim from Player.cs)
+
+Celeste's units are pixels/second for speeds and pixels/second² for accelerations at its native resolution; times in seconds. When porting, preserve the ratios more than the absolute numbers if your pixels-per-meter differs.
+
+### Gravity & Falling
+| Constant | Value | Feel role |
+|---|---|---|
+| Gravity | 900 | Base downward acceleration |
+| MaxFall | 160 | Terminal fall speed (normal) |
+| HalfGravThreshold | 40 | Below this vertical speed, gravity is halved (floaty apex) |
+| FastMaxFall | 240 | Terminal fall speed when fast-falling (hold down) |
+| FastMaxAccel | 300 | Acceleration toward FastMaxFall |
+
+### Running
+| Constant | Value | Feel role |
+|---|---|---|
+| MaxRun | 90 | Top ground speed |
+| RunAccel | 1000 | Ground acceleration (~11× MaxRun — near-instant response) |
+| RunReduce | 400 | Deceleration when input stops |
+| AirMult | 0.65 | Air control multiplier on acceleration |
+| HoldingMaxRun | 70 | Reduced top speed while carrying objects |
+| HoldMinTime | 0.35 | Min time before hold-reduction applies |
+| WalkSpeed | 64 | Slow-walk speed |
+| DuckFriction | 500 | Friction while crouched |
+
+### Jumping
+| Constant | Value | Feel role |
+|---|---|---|
+| JumpGraceTime | 0.1 | **Coyote time** — jump input valid 100 ms after leaving ground |
+| JumpSpeed | -105 | Initial jump velocity |
+| JumpHBoost | 40 | Horizontal boost added on jump |
+| VarJumpTime | 0.2 | **Variable jump** — held jump sustains/boosts for up to 200 ms |
+| CeilingVarJumpGrace | 0.05 | Grace before ceiling cancels variable jump |
+| UpwardCornerCorrection | 4 | px nudge to slip past near-miss ceiling corners while rising |
+| WallSpeedRetentionTime | 0.06 | Horizontal speed retained briefly after wall interactions |
+| BounceAutoJumpTime | 0.1 | Auto-jump window off bouncy surfaces |
+
+### Wall Interaction
+| Constant | Value | Feel role |
+|---|---|---|
+| WallJumpCheckDist | 3 | px probe distance for wall detection |
+| WallJumpForceTime | 0.16 | Duration of forced horizontal speed after wall jump |
+| WallJumpHSpeed | 130 | = MaxRun + JumpHBoost; forced away-from-wall speed |
+| WallSlideStartMax | 20 | Initial wall slide speed cap |
+| WallSlideTime | 1.2 | Time over which wall slide behavior ramps |
+| ClimbGrabYMult | 0.2 | Vertical speed multiplied by 0.2 on grab |
+
+### Super Variants
+| Constant | Value |
+|---|---|
+| SuperJumpH | 260 |
+| SuperWallJumpSpeed | -160 |
+| SuperWallJumpH | 170 (= MaxRun + JumpHBoost×2) |
+| SuperWallJumpForceTime | 0.2 |
+| SuperWallJumpVarTime | 0.25 |
+| BounceSpeed / SuperBounceSpeed | -140 / -185 |
+| DuckSuperJumpXMult / YMult | 1.25 / 0.5 |
+
+### Dash
+| Constant | Value | Feel role |
+|---|---|---|
+| DashSpeed | 240 | Speed during dash |
+| DashTime | 0.15 | Dash duration |
+| EndDashSpeed | 160 | Residual speed after dash ends (2/3 of dash speed) |
+| EndDashUpMult | 0.75 | Residual multiplier for upward dashes |
+| DashCooldown | 0.2 | Time before dash input re-accepted |
+| DashRefillCooldown | 0.1 | Refill timing after landing |
+| DashAttackTime | 0.3 | Active dash collision window |
+| DashCornerCorrection | 4 | px nudge on dash near-misses |
+| DashHJumpThruNudge | 6 | px nudge for horizontal dashes through one-way platforms |
+| DashVFloorSnapDist | 3 | px snap to floor after downward dash |
+
+### Climb / Stamina
+| Constant | Value | Feel role |
+|---|---|---|
+| ClimbMaxStamina | 110 | Total stamina pool |
+| ClimbUpCost | ~45.5/s (100/2.2) | Climbing upward drains ~2.4 s of pool |
+| ClimbStillCost | 10/s (100/10) | Hanging drains ~11 s of pool |
+| ClimbJumpCost | 27.5 (110/4) | Flat cost per climb-jump |
+| ClimbTiredThreshold | 20 | Below this, climb behavior degrades |
+| ClimbUpSpeed | -45 | Climb ascent speed |
+| ClimbDownSpeed | 80 | Climb descent speed |
+| ClimbSlipSpeed | 30 | Slip speed when exhausted |
+| ClimbAccel | 900 | Climb velocity acceleration |
+| ClimbCheckDist / UpCheckDist | 2 / 2 | px probe for grab detection |
+| ClimbHopX / HopY | 100 / -120 | Wall-hop impulse |
+| ClimbHopForceTime | 0.2 | Forced duration of hop impulse |
+| ClimbGrabYMult | 0.2 | Vertical damp on grab |
+
+### Other
+| Constant | Value |
+|---|---|
+| LaunchSpeed / LaunchCancelThreshold | 280 / 220 |
+| LiftYCap / LiftXCap | -130 / 250 |
+| JumpThruAssistSpeed | -40 (upward assist through one-way platforms) |
+| ReboundSpeedX / Y | 120 / -120 |
+| ReflectBoundSpeed | 220 |
+| ThrowRecoil | 80 |
+| DuckWindMult | 0 (ducking negates wind) |
+| SpacePhysicsMult | 0.6 (low-gravity zones) |
+
+## Scene / Node Shape (Godot 4)
+
+```
+Player (CharacterBody2D)
+├── CollisionShape2D          # compact rectangle; Celeste probes at 2–6 px, so shape must be tight
+├── WallProbeLeft (Area2D)    # or use move_and_collide probes at WallJumpCheckDist
+├── WallProbeRight (Area2D)
+├── StateMachine (ref in script)
+└── (AnimatedSprite2D / hair, particles optional)
+
+World
+├── TileMapLayer (static solids)
+├── OneWayPlatforms (TileMapLayer or StaticBody2D with one-way collision)
+└── JumpThru zones
+```
+
+## Reference Implementation Skeleton (GDScript)
+
+```gdscript
+extends CharacterBody2D
+
+# === Tuning table (values from Celeste Player.cs; rescale px if needed) ===
+const GRAVITY := 900.0
+const MAX_FALL := 160.0
+const HALF_GRAV_THRESHOLD := 40.0
+const FAST_MAX_FALL := 240.0
+const FAST_MAX_ACCEL := 300.0
+const MAX_RUN := 90.0
+const RUN_ACCEL := 1000.0
+const RUN_REDUCE := 400.0
+const AIR_MULT := 0.65
+const JUMP_GRACE_TIME := 0.1
+const JUMP_SPEED := -105.0
+const JUMP_H_BOOST := 40.0
+const VAR_JUMP_TIME := 0.2
+const UPWARD_CORNER_CORRECTION := 4
+const WALL_SPEED_RETENTION_TIME := 0.06
+const WALL_JUMP_CHECK_DIST := 3
+const WALL_JUMP_FORCE_TIME := 0.16
+const WALL_JUMP_H_SPEED := MAX_RUN + JUMP_H_BOOST  # 130
+const DASH_SPEED := 240.0
+const DASH_TIME := 0.15
+const END_DASH_SPEED := 160.0
+const END_DASH_UP_MULT := 0.75
+const DASH_COOLDOWN := 0.2
+const DASH_CORNER_CORRECTION := 4
+const CLIMB_MAX_STAMINA := 110.0
+const CLIMB_UP_COST := 100.0 / 2.2
+const CLIMB_STILL_COST := 100.0 / 10.0
+const CLIMB_JUMP_COST := 110.0 / 4.0
+const CLIMB_UP_SPEED := -45.0
+const CLIMB_DOWN_SPEED := 80.0
+const CLIMB_SLIP_SPEED := 30.0
+const CLIMB_CHECK_DIST := 2
+
+enum St { NORMAL, CLIMB, DASH, SWIM, BOOST, RED_DASH, HIT_SQUASH, LAUNCH, PICKUP, DREAM_DASH }
+
+var state: int = St.NORMAL
+var var_jump_timer: float = 0.0
+var jump_grace_timer: float = 0.0        # coyote time
+var dash_cooldown_timer: float = 0.0
+var dash_timer: float = 0.0
+var dash_dir: Vector2 = Vector2.ZERO
+var wall_jump_force_timer: float = 0.0
+var wall_speed_retention_timer: float = 0.0
+var stamina: float = CLIMB_MAX_STAMINA
+
+func _physics_process(delta: float) -> void:
+    match state:
+        St.NORMAL: _normal_update(delta)
+        St.DASH:   _dash_update(delta)
+        St.CLIMB:  _climb_update(delta)
+        # ... remaining states
+    move_and_slide()
+
+func _normal_update(delta: float) -> void:
+    # --- Gravity with apex float and fast-fall ---
+    var max_fall := MAX_FALL
+    if Input.is_action_pressed("ui_down") and not is_on_floor():
+        max_fall = FAST_MAX_FALL
+    var grav := GRAVITY
+    if absf(velocity.y) < HALF_GRAV_THRESHOLD and velocity.y < 0.0:
+        grav *= 0.5
+    velocity.y = minf(velocity.y + grav * delta, max_fall)
+
+    # --- Run acceleration, reduced in air ---
+    var input_x := Input.get_axis("ui_left", "ui_right")
+    var accel := RUN_ACCEL if is_on_floor() else RUN_ACCEL * AIR_MULT
+    if input_x != 0.0:
+        velocity.x = move_toward(velocity.x, input_x * MAX_RUN, accel * delta)
+    else:
+        velocity.x = move_toward(velocity.x, 0.0, RUN_REDUCE * delta)
+
+    # --- Coyote time bookkeeping ---
+    if is_on_floor():
+        jump_grace_timer = JUMP_GRACE_TIME
+    else:
+        jump_grace_timer -= delta
+
+    # --- Jump with variable height ---
+    if Input.is_action_just_pressed("ui_accept") and jump_grace_timer > 0.0:
+        velocity.y = JUMP_SPEED
+        velocity.x += signf(input_x) * JUMP_H_BOOST if input_x != 0.0 else 0.0
+        var_jump_timer = VAR_JUMP_TIME
+        jump_grace_timer = 0.0
+    if var_jump_timer > 0.0 and Input.is_action_pressed("ui_accept"):
+        var_jump_timer -= delta
+        # hold sustains upward velocity; release cuts it
+    elif var_jump_timer > 0.0:
+        var_jump_timer = 0.0
+        if velocity.y < 0.0:
+            velocity.y *= 0.5  # jump cut on release (standard platformer pattern)
+
+    # --- Wall probe and wall jump ---
+    var wall_dir := _probe_wall()  # raycast WALL_JUMP_CHECK_DIST px each side
+    if wall_dir != 0 and Input.is_action_just_pressed("ui_accept"):
+        velocity.x = -wall_dir * WALL_JUMP_H_SPEED
+        wall_jump_force_timer = WALL_JUMP_FORCE_TIME
+        velocity.y = JUMP_SPEED
+        var_jump_timer = VAR_JUMP_TIME
+
+    if wall_jump_force_timer > 0.0:
+        wall_jump_force_timer -= delta  # lock horizontal input during forced push
+
+    # --- Dash entry ---
+    if dash_cooldown_timer <= 0.0 and Input.is_action_just_pressed("dash"):
+        state = St.DASH
+        dash_dir = _aim_direction()  # 8-way from input axes
+        dash_timer = DASH_TIME
+        dash_cooldown_timer = DASH_COOLDOWN
+        velocity = dash_dir * DASH_SPEED
+
+func _dash_update(delta: float) -> void:
+    dash_timer -= delta
+    velocity = dash_dir * DASH_SPEED  # no gravity during dash
+    if dash_timer <= 0.0 or _collided_during_dash():
+        state = St.NORMAL
+        # Residual speed: keep EndDashSpeed, reduced for upward dashes
+        var residual := END_DASH_SPEED
+        if dash_dir.y < 0.0:
+            residual *= END_DASH_UP_MULT
+        velocity = dash_dir.normalized() * minf(velocity.length(), residual)
+
+func _climb_update(delta: float) -> void:
+    var input_y := Input.get_axis("ui_up", "ui_down")
+    if input_y < 0.0:
+        velocity.y = CLIMB_UP_SPEED
+        stamina -= CLIMB_UP_COST * delta
+    elif input_y > 0.0:
+        velocity.y = CLIMB_DOWN_SPEED
+    else:
+        velocity.y = minf(velocity.y + GRAVITY * delta * 0.1, CLIMB_SLIP_SPEED)
+        stamina -= CLIMB_STILL_COST * delta
+    velocity.x = 0.0
+    if stamina <= 0.0 or not _touching_wall():
+        state = St.NORMAL
+    if Input.is_action_just_pressed("ui_accept"):
+        stamina -= CLIMB_JUMP_COST
+        state = St.NORMAL
+        velocity.y = JUMP_SPEED
+
+func _probe_wall() -> int:
+    # Space-aware probe: returns -1 (wall left), 1 (wall right), 0 (none)
+    # Use move_and_collide or a WALL_JUMP_CHECK_DIST raycast against solids.
+    return 0
+```
+
+The skeleton above is a structural translation for Godot; the exact per-frame update bodies from Player.cs were not fully retrievable (see evidence limitations). The constants, state IDs, and confirmed behaviors (corner correction loops, variable-jump window logic, forced wall-jump timers, stamina costs, squish safety) are extracted directly from the source.
+
+## Confirmed Behavioral Patterns to Replicate
+
+1. **Corner correction:** on near-miss collisions (rising jump, dash), loop through ±4 px perpendicular offsets, test for clearance, and shift the player to the first clear position. Do not fail the move; nudge it through.
+2. **Variable-jump window:** `varJumpTimer` runs up to 0.2 s; a ceiling grace of 0.05 s prevents premature cancellation at the apex. The window zeroes on specific collision conditions, not on a raw timer expiry alone.
+3. **Forced wall-jump time:** for 0.16 s after a wall jump, horizontal input does not override the forced 130 px/s push. This prevents immediate re-stick to the wall.
+4. **Wall speed retention:** a 0.06 s timer retains horizontal speed across wall interactions; `NormalEnd` resets it along with `wallBoostTimer` and `hopWaitX`.
+5. **Squish safety:** if crushed, try (in order) ducking, repositioning to target, wiggle-nudging; only kill the player if all fail. Never instakill on a recoverable geometric overlap.
+6. **Jump-through assist:** one-way platforms apply a -40 (gentle upward) assist speed during pass-through.
+7. **Dash floor snap / jump-thru nudge:** after downward dashes, snap up to 3 px to the floor; horizontal dashes nudge up to 6 px through jump-throughs.
+
+## Implementation Steps
+
+1. Create the constants table first, exactly as listed. Keep it at the top of the player script as the single tuning surface (mirroring Player.cs structure).
+2. Implement the state machine as an enum + match, with per-state begin/update/end functions. Start with NORMAL, DASH, CLIMB; add BOOST, HIT_SQUASH, LAUNCH as encounters require.
+3. Implement gravity/fall tuning (apex float via HalfGravThreshold, fast-fall, MaxFall clamp) and run acceleration (RunAccel/RunReduce/AirMult).
+4. Implement jump + coyote time + variable jump height + jump cut on release.
+5. Implement wall probing (3 px), wall jump with forced-time lock, and wall slide.
+6. Implement dash with 8-way aim, cooldown, residual EndDashSpeed, and corner correction.
+7. Implement climb stamina with the three cost rates and tired threshold.
+8. Add forgiveness pass: upward corner correction on jump, dash nudges, jump-through assist, wall speed retention, squish-safety cascade.
+9. Rescale units if SummerEngine's pixels-per-meter differs from Celeste's native resolution: preserve ratios (e.g., DashSpeed ≈ 2.67× MaxRun; RunAccel ≈ 11× MaxRun).
+
+## Tunables
+
+All constants in the tables above. The highest-leverage feel knobs, in order:
+1. `JUMP_GRACE_TIME` (coyote) and `VAR_JUMP_TIME` — responsiveness.
+2. `RUN_ACCEL` vs `AIR_MULT` — ground crispness vs air drift.
+3. `DASH_SPEED` / `DASH_TIME` / `END_DASH_SPEED` — dash punch and recovery.
+4. `WALL_JUMP_FORCE_TIME` and `WALL_JUMP_H_SPEED` — wall jump commitment.
+5. `HALF_GRAV_THRESHOLD` — apex float amount.
+
+## Failure Modes & Gotchas
+
+- **Skipping coyote time or variable jump** makes the controller feel unfair even if every other value matches. These two forgiveness systems carry most of the "tight" perception.
+- **Letting horizontal input override the wall-jump force window** causes players to snap back onto the wall immediately.
+- **Applying RunAccel in the air without AirMult** gives full ground control mid-air and destroys momentum feel.
+- **Hard-failing near-miss collisions** instead of corner-correcting (±2–6 px probes) turns visual grazes into deaths.
+- **Instakilling on squish** — the source cascades duck → reposition → wiggle → die. Replicate the cascade.
+- **Treating stamina costs as per-frame instead of per-second** drains the pool ~60× faster.
+- **Copying pixel values without rescaling** if your game's world scale differs — use ratios.
+- **Over-abstracting the controller.** The source is deliberately one flat class with a constants table; splitting it into many components before the feel is dialed makes tuning iterations slow.
+
+## Verification
+
+After implementing, test each forgiveness system explicitly:
+1. Walk off a ledge and press jump up to ~100 ms later — should still jump (coyote).
+2. Tap vs. hold jump — distinct short and full arc heights (variable jump).
+3. Jump diagonally into a ceiling corner within ~4 px of clearance — should slip past, not bonk (corner correction).
+4. Wall jump and hold toward the wall — should still be pushed away for ~0.16 s.
+5. Dash into a wall edge within ~4 px — should correct rather than stop dead.
+6. Climb until stamina hits 0 — transition to slip/fall, not instant drop.
+7. Land from a dash — residual speed ≈ 160 px/s (or ×0.75 for upward), not zero.
+8. Get crushed by a moving platform — duck/wiggle recovery before any death.
+
+## Confidence
+
+`extracted` — All tuning values, state IDs, and confirmed behavioral patterns are taken directly from the retrieved Player.cs source. Per-state update-loop bodies from the middle of the 182 KB file were not retrievable (tool truncation); where the skeleton fills standard platformer patterns (e.g., jump-cut-on-release), this is noted as structural translation, not extracted code. Not yet verified inside SummerEngine.
+
+## Evidence
+
+- sources/web/celeste-player-cs/source.md — primary source record: constants tables, state machine, confirmed behavioral snippets, retrieval limitations.
+- sources/x/valigo-celeste-movement/source.md — originating post and primary-source identification.

package/library/skills/celeste-momentum-platforming/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/celeste-momentum-platforming
+kind: skill
+version: 0.1.1
+summary: "Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction."
+use_when:
+  - "make the platformer movement feel like Celeste"
+  - "add coyote time, variable jump height, and a dash to my 2D platformer"
+  - "add wall jumps, wall slides, or climb stamina to a 2D character"
+  - "my 2D platformer controller feels unfair or unresponsive"
+do_not_use_when:
+  - "3D character controllers, physics-driven RigidBody movement, or games that want floaty arcade jump physics over momentum precision"
+  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - gameplay
+    - character-controller
+    - game-design
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/design-mechanic
+    - skill/game-feel
+    - skill/debugging-game-feel
+source: official
+license: MIT
+status: preview
+recommended: false