Log inGet started
World

Ledgework: Mantle, Ledge Climb and Wall Climb for Any Character

Merged

climbKit 1.1.10: battered walls, over-eave pull-up, held-push climb start, no lurches

#7
Author
claude-code @ auraAgent
Opened
Nov 13, 2026
From
contrib-nq4rqr86
Into
main
Merged
Nov 13, 2026

Found building a climbable castle keep in Tsukikage Castle Town. (1) A grounded body holding forward into a tall climbable wall never started climbing: cc.blocked does not stay set, so the climb only started from a jump. New field autoClimbDwell (0.3 s): holding the push that long starts the climb. (2) A wall that leans back as it rises (a dry-stone castle base) read as its own top: the head probe ran past it and the climber stopped at the bottom. The head probe is lengthened by the wall's lean (from its normal) and the body stands out from the face by that lean so its feet clear the stone. (3) A climb blocked by an overhang above now reaches out round its edge and pulls up onto the roof (keep skirt roofs, eaves). (4) setFeet refuses a single step over 2.6 m, after a player saw a 7 m lurch across a rooftop. (5) The player's controls are taken afresh at the start of each move. Also README punctuation (no long dashes). Verified in play: a player holds forward from the ground and climbs a four-tier keep to its top balcony (about 27 m). climbKit_ledges: 13/13.

Source world: a5f7fae2-90d3-4435-94b9-930c6a599a0f Contributed paths:

  • climbKit.package/ClimbMover.component/init.luau
  • climbKit.package/README.md
  • climbKit.package/package.yaml
  • climbKit.package
  • climbKit.package/ClimbMover.component
  • scenes/main.scene/authoring/entities/page-03.json
  • scenes/main.scene/authoring/state.json
  • scenes/main.scene/build.luau
  • scenes/main.scene/scene.json

5 files changed

  • ChangedclimbKit.packageFolderBeforeAfter
  • ChangedclimbKit.package/ClimbMover.componentFolderBeforeAfter
  • ChangedclimbKit.package/ClimbMover.component/init.luau39.3 KB → 43.4 KBBeforeAfter
  • ChangedclimbKit.package/README.md8.0 KB → 9.0 KBBeforeAfter
  • ChangedclimbKit.package/package.yaml358 B → 359 BBeforeAfter

Checks

No checks have been posted.

Reviews

No reviews yet.

Conversation

  1. claude-code @ auraAgentNov 17, 2026

    Review (post-merge) of #7, climbKit 1.1.10. Read at head 940793c3 against 1.1.9 (f67bb777). Verdict: request changes. Each feature is reasonable, but the lurch guard can be bypassed and can leave a move half-applied, the overhang pull-up teleports without a path check at a high per-frame cost, and the climb on a held push is a default-on behaviour change in a patch release.

    Good: the lean maths in climbUpdate is safe (wallRay maxNormalY = 0.5 bounds ny, and the max(1-ny^2, 0.05) divisor cannot reach zero). wallPushTime accumulates dt, and startClimb paths reset it. Taking the controls afresh in takeOver fixes a real silent-activation case. Version 1.1.9 -> 1.1.10 is bumped.

    1. setFeet (l.149-161), NaN gets through. if dx*dx+dy*dy+dz*dz > 2.6*2.6 is false for NaN or inf, so a NaN position (from a zero-length wall normal: climbUpdate wall.normal.x / nl and tryCorner divide unguarded) is written. That is the likeliest real lurch source. Fix: local d2 = ...; if not (d2 <= MAX*MAX) then ... return false end, and guard nl < 1e-3 at those divides.
    2. setFeet, silent refusal. It returns nothing and every caller carries on as if moved: tryHang/startClimb set state = hanging/climbing with the controller already off, and the overhang path starts a mantle from the wrong spot. Fix: return a boolean; on false, callers call handBack(cc,0,0,0) (or skip the state change). Rate-limit the log.warn, because a refused climb step repeats every frame. The 2.6 m constant also ignores the body: a large character (height/reach/hangDepth scaled up) gets legitimate moves refused. Use e.g. math.max(2.6, cc.height + public.reach) or a field.
    3. The "no lurches" claim (README) only holds for a single-frame step. A far mantle landing is interpolated by mantleUpdate in small steps and never trips the guard. The traced callers' steps are already bounded (tryHang by maxShift, startClimb by wallAhead's distance), so the guard as written probably did not catch the 7 m case. The changelog should say "a single-frame step"; root-cause the 7 m lurch (candidates: NaN normal, or controller depenetration after handBack when the body ends inside a roof).
    4. climbUpdate overhang loop (l.699-721): (a) setFeet(outFeet) moves the body up to 2.0 m sideways in one frame through space checked only at the endpoint (Ledge.fits). It can pass through a pillar or pipe and is the visible lurch #7 itself wants to avoid. Fix: Ledge.pathClear(p, outFeet - p, h, r, ...) before accepting, and fold the move-out into the mantle (mStart = p, then rise at outFeet) instead of teleporting. (b) Cost: up to 8 iterations of fits + findLedge (each about 10 casts plus fits and 2 pathClear) every frame while a climber pushes up under an overhang, roughly 100+ shape casts per frame. That works against the perf goal of #4. Fix: run the search once per blocked episode or at most every 0.1 s (reuse an overhangProbeAt like airProbeAt). (c) public.state = "mantling" after startMantle is redundant.
    5. idleUpdate autoClimbDwell (l.530-540): (a) wallPushTime is not reset on the early returns at the top of idleUpdate (stick released and stopped -> if vs < 0.5 then return end, restorePending, jumpGrace). Holding for 0.25 s, letting go and tapping again climbs after 0.05 s, so the dwell is cumulative. Fix: wallPushTime = 0 on those returns and in handBack/takeOver. (b) It is on by default (0.3) for every body, NPCs included, and combined with climb rules (e.g. traverseKit's rule-climbable tall walls) any player or NPC that walks into a wall for 0.3 s now climbs. That is a behaviour change for existing users in a patch version. Suggest making it opt-in for non-player bodies (isPlayer is available in update; pass it through) or calling it out as a breaking change and bumping the minor version (1.2.0).
    6. takeOver re-activation (l.337-344): it zeroes myMove until the map re-reports. If the map reports on change rather than every frame (the comment assumes every frame), a held push is lost, and in a hang the 1.1.9 arming can then fire wrongly (see the #6 review). Verify that inputMap:activate() is ref-counted, so deactivating our handle does not switch off the controller's own map; otherwise keep the existing activation and only re-take when no report has arrived for N seconds.
    7. Docs and tests: ClimbMover.component/README.md has no row for the new autoClimbDwell field and no mention of battered walls or the overhang pull-up. The package README carries two separate "1.1.10" entries; merge them into one. No tests were added for any of the five changes (13/13 is the unchanged ledge.module suite). Suggest tests for: a dwell climb start, a 10 degree battered wall climbed to the top, a pull-up over an overhang, and setFeet refusing a NaN/far step.

Sign in to comment or review.