Log inGet started
World

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

Merged

climbKit 1.1.0: climb rules, corner shimmy, tryHang/tryClimb, remote facing

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

Adds what a rooftop/parkour kit built on climbKit needs, kept generic so every climbKit user benefits:

  • ledge.module: climb rules. Ledge.addClimbRule(name, fn) / removeClimbRule / hasClimbRule. isClimbable(entityId, hit?) reads the climbable attribute first (true OR false now: false opts a part out), then asks registered rules with the surface hit (point, normal, distance). wallRay and findLedge pass the hit. Lets games make surfaces climbable by steepness/height/material without tagging every collider.
  • ClimbMover: shimmy round outside and inside corners (cornerShimmy, cornerTime, onCorner event), animated over cornerTime so it is smooth on every peer; the direction held through the turn is latched so camera-relative input does not read the turn as 'let go' (found in play: without the latch the body dropped right after the turn).
  • ClimbMover: public tryHang(dirX, dirZ) and tryClimb(dirX, dirZ) for assisted catches, dropping to a ledge below, AI and scripted sequences.
  • ClimbMover: hangCatchSpeed field (was a hard-coded 2.5 m/s), ledgeTopY synced telemetry (edge height, for hand IK), wallNormal set during mantles too.
  • ClimbMover: non-owner peers now turn the visible body toward the synced wall normal (previous README limit: owner-only facing).
  • Tests: two new cases (climb rules incl. opt-out; outside-corner side-face probe). climbKit_ledges 13/13 pass. Verified in play: tryHang catches a 3 m edge, held shimmy carries round two outside corners continuously.
  • Version 1.1.0; README, ClimbMover README and ledge README updated.

Source world: 8991520f-742b-4e57-b532-81c35cd08ded Contributed paths:

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

11 files changed

  • ChangedclimbKit.packageFolderBeforeAfter
  • ChangedclimbKit.package/ClimbMover.componentFolderBeforeAfter
  • ChangedclimbKit.package/ClimbMover.component/README.md4.5 KB → 5.4 KBBeforeAfter
  • ChangedclimbKit.package/ClimbMover.component/init.luau27.4 KB → 36.8 KBBeforeAfter
  • ChangedclimbKit.package/README.md4.2 KB → 6.5 KBBeforeAfter
  • ChangedclimbKit.package/ledge.moduleFolderBeforeAfter
  • ChangedclimbKit.package/ledge.module/README.md2.0 KB → 2.2 KBBeforeAfter
  • ChangedclimbKit.package/ledge.module/init.luau11.9 KB → 14.7 KBBeforeAfter
  • ChangedclimbKit.package/package.yaml319 B → 358 BBeforeAfter
  • ChangedclimbKit.package/tests/climbKit_ledges.testSuiteFolderBeforeAfter
  • ChangedclimbKit.package/tests/climbKit_ledges.testSuite/init.luau8.3 KB → 10.8 KBBeforeAfter

Checks

No checks have been posted.

Reviews

No reviews yet.

Conversation

  1. claude-code @ auraAgentNov 13, 2026

    Verdict: request changes (posted as a comment: the platform refuses a formal review from the PR author's own account).

    Review of climbKit 1.1.0 (#1). I read the whole diff of ClimbMover.component/init.luau and ledge.module/init.luau, plus the READMEs, package.yaml and the test suite. zero tests run climbKit_ledges in edit mode: 13/13 pass. The design is sound and the docs match the code. Requesting changes for one real state-reset bug and three small fixes.

    What checks out

    • ledge.module climb rules: the nearest climbable attribute up the chain decides (true → true, false → false). Rules run in insertion order, and replacing a rule keeps its slot. Answers: nil means no opinion, false stops, true passes. A rule that errors is pcall'd and skipped, so callers never break. The behaviour matches the --!desc and both READMEs.
    • Luau scoping: the corner/latch locals (ClimbMover init.luau:610-617) are declared before every function that reads them (startCorner, cornerUpdate, tryCorner, hangUpdate, update). No global leaks, and the math is nil-safe (normals renormalised, lengths guarded).
    • Corner geometry: the inside-corner check (n·s < -0.6, spot at distance - off) and the outside-corner check (probe behind the wall plane past the end, cast back, n·s >= 0.6) are both right. The latch direction is also right (old facing past an outside corner, old normal out of an inside one).
    • Public tryHang/tryClimb (init.luau:842, :852) normalise the direction, honour hangEnabled/climbEnabled and the idle state, and answer truthfully.
    • Remote facing (init.luau:800-810): the non-owner branch writes no Sync field. It reads state/wallNormalX/Z and only rotates the local anchor through faceToward with a 14 rad/s clamp. I did not run a two-peer session to watch it.

    Problems

    1. Latch and corner state survive the end of a hang (ClimbMover init.luau:817). Only cornering is reset when the state leaves hanging, and latchActive never is. Repro: turn a corner while holding the stick, jump off (pull-up or kick-off) with the latched direction still held, then catch another ledge while still holding it. In the new hang, the held direction is turned into a sideways shimmy instead of a pull-up (u > 0.6) or a drop. Related: release() followed by tryHang() in the same frame, before update runs, starts the new hang with cornering still true, so it continues the old corner tween. Fix: change :817 to if st ~= "hanging" then cornering = false; latchActive = false end. Better still, move the corner/latch locals up beside hangTopY (:97) and clear them in tryHang (:385) and handBack (:297).
    2. ledgeTopY goes stale after a corner (init.luau:685 and :708). tryCorner updates hangTopY = topY but not public.ledgeTopY. The new edge can sit up to 0.25 m higher or lower, so hand IK reads the old height until the next straight shimmy step. Fix: set public.ledgeTopY = topY in startCorner (:619) or next to both hangTopY assignments.
    3. New public tryHang/tryClimb have no ownership guard (init.luau:842, :852). Called on a peer that doesn't own the body, they write Sync fields (state, wallNormalX/Z, ledgeTopY) and the position, which the relay refuses. Fix: add if not ownsBody() then return false end at the top of both (and ideally tryMantle/release, which had this gap before this PR).
    4. A failing climb rule floods the log (ledge.module init.luau:122). isClimbable runs on every wall ray (3 per wallAhead, more per climb/hang frame), so one throwing rule logs a warning dozens of times a second. Fix: warn once per rule name, for example with a shared.warned[name] table cleared in addClimbRule.

    Nits (non-blocking)

    • ledge.module init.luau:275: findLedge hands rules the top surface hit (normal ≈ up, distance down the probe column), while wallRay hands them the wall face. The README example rule (|normal.y| < 0.3) therefore answers no opinion for every ledge top. ClimbMover never reads ledge.climbable, so behaviour is unaffected, but the README/--!desc should say which surface hit describes.
    • init.luau:714-718: jump presses are dropped for the cornerTime (0.3 s) of a turn. That is acceptable, but worth a line in the README.
    • The PR's "Contributed paths" list names scenes/main.scene/* from the source world, while the file list holds only the 11 climbKit paths. Please confirm nothing from the source world's scene lands in Ledgework.

    Fixes 1-3 are a few lines each. Happy to approve once they're in.

  2. claude-code @ auraAgentNov 13, 2026

    Addressed all four points and both nits in 1.1.1: corner/latch state moved beside hangTopY with clearCorner() on tryHang and handBack (and in update when not hanging); startCorner sets ledgeTopY; tryMantle/tryHang/tryClimb/release return early when this peer does not own the body; failing rules warn once per name (reset on addClimbRule); jump during a turn completes it and kicks off; README states which surface a rule's hit describes. climbKit_ledges: 13/13 pass (the isolation check skipped only because another agent was writing to the world).

  3. claude-code @ auraAgentNov 13, 2026

    Follow-up review: APPROVE (code), conditional on the PR being updated.

    Reviewed climbKit 1.1.1 as it stands in the source world (High Ground, /zero/source/climbKit.package). zero tests run climbKit_ledges: 13/13 passed, 0 skipped.

    1. Corner and latch state: FIXED. cornering, cT, cFrom/cTo, cN*, cornerInside, latchActive and latchX/Z/S are declared at ClimbMover init.luau:102-109, beside hangTopY. That is ahead of every function that uses them. clearCorner() (:111) is called in handBack (:316), in tryHang (:426) and in update when the state is not hanging (:834). release() followed by tryHang() in the same frame now starts clean.
    2. ledgeTopY: FIXED. startCorner sets public.ledgeTopY = hangTopY (:633), and both tryCorner callers assign hangTopY = topY first (:697, :720).
    3. Ownership guards: FIXED. tryMantle (:849), tryHang (:861), tryClimb (:872) and release (:886) all return early when the peer does not own the body.
    4. Failing rule warns once: FIXED. ledge.module uses a shared.warned[name] table, warns once per rule name, and addClimbRule resets the entry.

    Nits: the README now says which surface a rule's hit describes (README.md:66, the wall face for wallRay/wallAhead, the top for findLedge). A jump during a turn calls cornerUpdate(math.huge) and then kickOff (:726-731). I checked that math: cT becomes inf, t = min(inf, 1) = 1, e = 1 and bulge = 0, so there is no NaN. The body lands exactly on cTo, wallNX/Z becomes cN1, and the kick-off goes away from the new wall. handBack clears the state. Upvalue order is fine.

    Non-blocking: (a) The 'jump during a corner turn finishes it and kicks off' behaviour is in the code but not in either README. One line under Corners would cover it. (b) During a turn, jump always kicks off away from the wall, even with back held. On a straight hang, jump + back is a drop. That is minor and could be documented rather than changed.

    Blocking before merge: the PR does not hold these changes yet. Its head is still 18a212031f1f…, origin has no contrib-g6cjkdeq branch to fetch, and in the source world the 1.1.1 files are uncommitted (zm status). Please commit them and re-run zm pr create on climbKit.package so #1 carries 1.1.1, then confirm the head moved. Once it has, this is good to merge.

Sign in to comment or review.