Ledgework: Mantle, Ledge Climb and Wall Climb for Any Character
- 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
- 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_ledgesin 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
climbableattribute up the chain decides (true → true, false → false). Rules run in insertion order, and replacing a rule keeps its slot. Answers:nilmeans no opinion,falsestops,truepasses. A rule that errors is pcall'd and skipped, so callers never break. The behaviour matches the--!descand 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 atdistance - 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, honourhangEnabled/climbEnabledand the idle state, and answer truthfully. - Remote facing (init.luau:800-810): the non-owner branch writes no Sync field. It reads
state/wallNormalX/Zand only rotates the local anchor throughfaceTowardwith a 14 rad/s clamp. I did not run a two-peer session to watch it.
Problems
- Latch and corner state survive the end of a hang (ClimbMover init.luau:817). Only
corneringis reset when the state leaveshanging, andlatchActivenever 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 bytryHang()in the same frame, before update runs, starts the new hang withcorneringstill true, so it continues the old corner tween. Fix: change :817 toif st ~= "hanging" then cornering = false; latchActive = false end. Better still, move the corner/latch locals up besidehangTopY(:97) and clear them intryHang(:385) andhandBack(:297). ledgeTopYgoes stale after a corner (init.luau:685 and :708).tryCornerupdateshangTopY = topYbut notpublic.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: setpublic.ledgeTopY = topYinstartCorner(:619) or next to bothhangTopYassignments.- New public
tryHang/tryClimbhave 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: addif not ownsBody() then return false endat the top of both (and ideallytryMantle/release, which had this gap before this PR). - A failing climb rule floods the log (ledge.module init.luau:122).
isClimbableruns on every wall ray (3 perwallAhead, 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 ashared.warned[name]table cleared inaddClimbRule.
Nits (non-blocking)
- ledge.module init.luau:275:
findLedgehands rules the top surface hit (normal ≈ up, distance down the probe column), whilewallRayhands them the wall face. The README example rule (|normal.y| < 0.3) therefore answers no opinion for every ledge top. ClimbMover never readsledge.climbable, so behaviour is unaffected, but the README/--!descshould say which surfacehitdescribes. - 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.
- ledge.module climb rules: the nearest
- claude-code @ auraAgent
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).
- claude-code @ auraAgent
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.
- 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.
- ledgeTopY: FIXED. startCorner sets public.ledgeTopY = hangTopY (:633), and both tryCorner callers assign hangTopY = topY first (:697, :720).
- Ownership guards: FIXED. tryMantle (:849), tryHang (:861), tryClimb (:872) and release (:886) all return early when the peer does not own the body.
- 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.