feat(rig lab): drag the anchors themselves, not just the gun under them

The lab could move the GUN and not the anchor points the hands are solved onto.
`grip_offset` slides the weapon around inside the fist; `gun_fore` and
`gun_stock` are distances ALONG the barrel, so the trigger and support hands
could travel up and down the weapon's own axis and nowhere else. Nothing could
take a hand off that axis, which is what a handguard below the bore, an angled
foregrip, or a pistol whose grip is nowhere near its barrel line all need.

Two things fix that.

`grip_shift` and `fore_shift` give the two hand anchors real three-dimensional
freedom, expressed in the GUN's own across/up/along frame so a sideways nudge
stays sideways as the weapon pitches between low ready and ADS. Zero is exactly
the old behaviour. Their z overlaps the along-axis distances, which is redundant
and deliberate: keeping those separate is what lets the reach solver slide the
support hand back down the handguard without undoing a considered sideways
offset.

And the markers are now draggable. They already showed the anchors; now they
are handles. The one under the mouse swells and draws through the body — depth
testing is right for judging whether a hand reached its target and wrong for a
handle, because at any useful framing the hands occlude all three.

Verified three ways, and each one had to be rebuilt once:

  anchor_shift_check first compared absolute positions and reported a 3.5 mm
  error that was the character BREATHING — there is a sin() on the muzzle pitch,
  so no anchor is ever in the same place twice. Measuring each anchor relative
  to the one it hangs off, rotated into the current gun basis, cancels the
  breathing, the ADS blend and the recoil exactly. 48 checks, six characters,
  both poses.

  anchor_drag_check asserts the drag writes the knob the MOUSE asked for,
  derived independently from the camera: 0.00-0.01 mm on all three. It does not
  assert the marker lands under the cursor, because it does not — the anchors
  hang off the shoulder and the arm chasing them moves the shoulder, so a drag
  settles at 0.77x-1.13x. Small enough to ignore interactively.

  That feedback first read as 1.5x-1.8x, because the cases were compounding on
  each other, and waiting LONGER for the pose to settle made it worse rather
  than better — which is the opposite of how a settling error behaves and is
  what gave it away.

The buttstock case also failed for a while on a bug entirely in the test: it
read an absent knob as zero when `pocket_hip` defaults to (30, -70, 60) mm. The
lab has a note about that trap in `_reset`. It is just as easy to walk into from
a test, and now has one there too.

Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
Nicholas Butzke
2026-07-28 01:05:37 -04:00
co-authored by Claude Opus 5
parent 700d0925d7
commit b1c8bab714
9 changed files with 566 additions and 11 deletions
+165
View File
@@ -0,0 +1,165 @@
extends SceneTree
## Does dragging an anchor marker in the rig lab move that anchor where the
## mouse went?
##
## The maths behind a viewport drag has four frames in it — screen, world,
## skeleton, gun — and every one is a chance to transpose an inverse or lose a
## handedness. All of those mistakes still MOVE the marker, so "the number
## changed" proves nothing. What is asserted here is that the number changed by
## the RIGHT AMOUNT, in the frame that knob is written in, derived independently
## from the camera.
##
## Deliberately NOT asserted: that the marker lands exactly under the mouse. It
## does not, and the reason is a real property of the hold rather than a bug in
## the drag — see THE FEEDBACK below. The screen-space check kept here is a
## direction-and-order-of-magnitude one, which is the band the transform
## mistakes above actually live in: a swapped axis or a lost handedness sends
## the marker the wrong way entirely.
##
## THE FEEDBACK. Every anchor hangs off the shoulder — `stock_pos = shoulder +
## pocket`, and the grip and fore anchors are measured out from there. The
## shoulder is driven by the arm, and the arm is chasing the anchor. So moving
## an anchor moves the shoulder, which moves the anchor again. Measured from a
## clean slate it settles at 0.77x-1.13x of the drag depending on which anchor,
## which is small enough to be invisible interactively — you stop dragging when
## it looks right.
##
## It is worth the paragraph because of how it first showed up. Without the
## `_reset` between cases below, each drag started on top of the last one still
## working its way through the arm, and the ratio read 1.5x-1.8x; waiting LONGER
## for the pose to settle made it worse rather than better, which is the
## opposite of how a settling error behaves and is what gave the compounding
## away.
##
## godot --path . -s res://debug/anchor_drag_check.gd
const LAB := "res://debug/rig_lab.tscn"
const DRAG := Vector2(60, 0)
## Metres. What the knob is checked to — this part is exact maths, so it can be.
const KNOB_TOLERANCE := 0.0005
## The screen-space check is direction and order of magnitude only. See above.
const MIN_TRAVEL := 0.5
const MAX_TRAVEL := 2.2
var _fails := 0
func _init() -> void:
await process_frame
var lab: Node = load(LAB).instantiate()
root.add_child(lab)
# The pose layer chases its targets exponentially at a rate times DELTA, and
# a headless run is uncapped, so each frame advances the blend by almost
# nothing and the hold takes hundreds of frames to stop moving on its own.
for _i in 300:
await process_frame
if lab._model == null or not lab._model.loaded or lab._model._pose_mod == null:
_expect(false, "the lab built a character with a pose layer")
_done()
return
_expect(true, "the lab built a character with a pose layer")
# Frame the hands, so a pixel is a small distance in the world — a drag
# measured at arm's length is mostly noise.
lab._pivot = lab._model.skeleton.global_transform * lab._model._pose_mod.dbg_grip
lab._dist = 0.6
lab._update_camera()
for _i in 20:
await process_frame
for case in [[0, "trigger hand", "grip_shift"], [1, "support hand", "fore_shift"],
[2, "buttstock", "pocket_hip"]]:
await _drag_case(lab, case[0], case[1], case[2])
_done()
func _drag_case(lab: Node, marker: int, label: String, key: String) -> void:
# From a clean slate each time, or the second case measures the first's
# shift still working its way through the arm.
lab._reset("hold")
for _i in 120:
await process_frame
var m: Node3D = lab._markers[marker]
if not m.visible:
_expect(false, "the %s marker is visible" % label)
return
var before: Vector2 = lab._cam.unproject_position(m.global_position)
_expect(lab._marker_under(before) == marker,
"the %s marker is grabbable where it is drawn" % label)
# What the drag SHOULD write, worked out from the camera here rather than
# from the lab's own code, so the two have to agree independently.
var want: Vector3 = _expected(lab, marker, m.global_position, before, before + DRAG)
var was: Vector3 = _knob(lab, key)
lab._begin_drag(marker, before)
# In steps, as a real drag arrives — a single jump would hide an error that
# accumulates per motion event.
for step in 6:
lab._drag_to(before + DRAG * (float(step + 1) / 6.0))
await process_frame
lab._drag_marker = -1
var wrote: Vector3 = _knob(lab, key) - was
var err: float = (wrote - want).length()
_expect(err <= KNOB_TOLERANCE,
"the %s drag wrote %s into '%s' (wanted %s, off by %.2f mm)"
% [label, _mm(wrote), key, _mm(want), err * 1000.0])
# ...and the marker really did go that way on screen.
for _i in 150:
await process_frame
var now: Vector2 = lab._cam.unproject_position(m.global_position)
var moved: Vector2 = now - before
var along: float = moved.dot(DRAG.normalized()) / DRAG.length()
_expect(along >= MIN_TRAVEL and along <= MAX_TRAVEL,
"the %s marker followed the drag (%.2fx of it; the shoulder feedback puts this over 1)"
% [label, along])
## The knob delta a drag from `a` to `b` ought to produce, in that knob's frame.
func _expected(lab: Node, marker: int, at: Vector3, a: Vector2, b: Vector2) -> Vector3:
var world := _plane(lab._cam, at, b) - _plane(lab._cam, at, a)
var v: Vector3 = lab._model.skeleton.global_transform.basis.inverse() * world
if lab.MARKER_KNOB[marker][1] == "gun":
v = lab._model._pose_mod.dbg_gun_basis.inverse() * v
return v
func _plane(cam: Camera3D, at: Vector3, mouse: Vector2) -> Vector3:
var origin := cam.project_ray_origin(mouse)
var dir := cam.project_ray_normal(mouse)
var n := -cam.global_transform.basis.z
return origin + dir * (((at - origin).dot(n)) / dir.dot(n))
## An absent knob reads as its DEFAULT, not as zero.
##
## Those are the same thing for `grip_shift` and `fore_shift` and not for
## `pocket_hip`, whose default is (30, -70, 60) mm. Reading it as zero made a
## perfectly correct 60 px drag look like a 97 mm error — the difference was
## exactly the default. The lab has a note about this trap in `_reset`; it is
## just as easy to walk into from a test.
func _knob(lab: Node, key: String) -> Vector3:
var v = lab._knobs["hold"].get(key, WeaponHoldTuning.default_for(key))
return v if v is Vector3 else Vector3.ZERO
func _mm(v: Vector3) -> String:
return "(%.0f, %.0f, %.0f) mm" % [v.x * 1000.0, v.y * 1000.0, v.z * 1000.0]
func _expect(ok: bool, what: String) -> void:
if ok:
print(" OK: %s" % what)
else:
print(" FAIL: %s" % what)
_fails += 1
func _done() -> void:
print("\n=== ANCHOR DRAG ===\nFailures: %d" % _fails)
quit(1 if _fails > 0 else 0)
+140
View File
@@ -0,0 +1,140 @@
extends SceneTree
## Do the hand anchors move where they are told, in the frame they are told in?
##
## `grip_shift` and `fore_shift` exist because the two hand anchors could only
## ever slide along the barrel: `gun_stock` and `gun_fore` are distances along
## the weapon's own axis, so the trigger and support hands travelled up and down
## the gun and nowhere else. What could move freely was the GUN, under anchors
## that stayed put.
##
## Two things have to hold, and only the first is obvious:
##
## 1. the anchor moves by the amount asked for;
## 2. it moves in the GUN's frame, not the skeleton's. A sideways nudge has to
## stay sideways relative to the weapon whether the muzzle is pitched down
## at low ready or level at ADS — otherwise the same number means two
## different places in the two poses, and a skeleton-space implementation
## passes check 1 happily.
##
## MEASURED IN THE GUN'S FRAME, and it has to be. The hold BREATHES — there is a
## `sin(_time * 2.2) * 0.012` on the muzzle pitch — so no anchor is ever at the
## same world position twice, and the first version of this check compared
## absolute positions and reported a 3.5 mm error that was just the character
## inhaling. Taking each anchor relative to the one it hangs off and rotating
## into the current gun basis cancels the breathing, the ADS blend and the
## recoil kick exactly, because all three move the basis and the anchor together.
##
## godot --headless --path . -s res://debug/anchor_shift_check.gd
## All three axes, deliberately asymmetric, so an axis swap or a sign flip
## cannot pass.
const SHIFT := Vector3(0.05, -0.03, 0.02)
const TOLERANCE := 0.0015
## Long enough for the ADS blend and the hold's take-up to settle. The gun-frame
## measurement is invariant to both, but a half-blended pose is a bad place to
## be reading anything.
const SETTLE := 40
var _fails := 0
func _init() -> void:
await process_frame
await process_frame
var weapon := _first_weapon()
var data = JSON.parse_string(FileAccess.get_file_as_string(
"res://assets/characters/skins/skins.json"))
for entry in data["skins"]:
await _check(entry["id"], entry.get("model", ""), weapon)
print("\n=== ANCHOR SHIFTS ===\nFailures: %d" % _fails)
quit(1 if _fails > 0 else 0)
func _first_weapon() -> String:
var db = root.get_node("LoadoutManager").weapon_db
var ids: Array = db.keys()
ids.sort()
for id in ids:
var s: String = db[id].get("script", "")
if s != "" and ResourceLoader.exists(s):
return s
return ""
## The two anchors in the gun's own across/up/along frame:
## grip, relative to the buttstock == (0, 0, gun_stock) + grip_shift
## fore, relative to the grip == (0, 0, fore_dist) + fore_shift
func _local(pm) -> Array:
var inv: Basis = pm.dbg_gun_basis.inverse()
var grip: Vector3 = pm.dbg_grip
var fore: Vector3 = pm.dbg_fore
var stock: Vector3 = pm.dbg_stock
return [inv * (grip - stock), inv * (fore - grip)]
func _check(id: String, path: String, weapon: String) -> void:
if path == "" or not ResourceLoader.exists(path):
return
var model := SkinnedPlayerModel.new()
model.model_path = path
model.skin_id = id
root.add_child(model)
for _i in 4:
await process_frame
model.set_weapon(weapon)
for _i in 6:
await process_frame
# Both poses, because the gun's pitch differs between them and that is the
# whole point of expressing the shift in the gun's frame.
for pose in [["low ready", 0.0], ["ADS", 1.0]]:
var pm = model._pose_mod
if pm == null:
_expect(false, "'%s' has a pose layer" % id)
break
model.set_hold_tuning({})
model.update_state("ground", 0.0, false)
model.set_locomotion(0.0, 0.0, pose[1])
for _i in SETTLE:
await process_frame
var base: Array = _local(pm)
# Each anchor on its own. `fore` hangs off `grip`, so shifting the grip
# legitimately carries the support hand with it — moving where the
# trigger hand holds a rifle moves the whole rifle, handguard included.
# Testing them together would just measure that, and the first version
# of this check did, and reported the sum as a 2x error.
for which in [["grip_shift", 0, "trigger"], ["fore_shift", 1, "support"]]:
model.set_hold_tuning({which[0]: SHIFT})
for _i in 6:
await process_frame
var now: Array = _local(pm)
var moved: Vector3 = now[which[1]] - base[which[1]]
# x and y are across the barrel — the freedom that did not exist
# before. z is along it, and for the support hand the reach solver
# owns that, so it is not ours to predict.
var across := Vector2(moved.x, moved.y)
var want := Vector2(SHIFT.x, SHIFT.y)
_expect(across.distance_to(want) <= TOLERANCE,
"'%s' %s: %s anchor moved %.0f, %.0f mm across the barrel (wanted %.0f, %.0f)"
% [id, pose[0], which[2], across.x * 1000.0, across.y * 1000.0,
want.x * 1000.0, want.y * 1000.0])
model.set_hold_tuning({})
for _i in 6:
await process_frame
var back: Array = _local(pm)
var residue: Vector3 = back[which[1]] - base[which[1]]
_expect(Vector2(residue.x, residue.y).length() <= TOLERANCE,
"'%s' %s: clearing %s restores the derived anchor"
% [id, pose[0], which[0]])
model.queue_free()
func _expect(ok: bool, what: String) -> void:
if ok:
print(" OK: %s" % what)
else:
print(" FAIL: %s" % what)
_fails += 1
+1
View File
@@ -0,0 +1 @@
uid://cmh6vowe1f6d5
+1
View File
@@ -0,0 +1 @@
uid://colk7su4vk56m
+190 -9
View File
@@ -28,14 +28,27 @@ extends Node3D
## for the game to run correctly.
##
## CONTROLS
## left drag orbit wheel zoom
## middle drag pan F frame the hands
## R reset knobs S save C copy JSON to clipboard
## drag a MARKER move that anchor left drag orbit
## middle drag pan wheel zoom
## F frame the hands
## R reset knobs S save C copy JSON to clipboard
##
## The three coloured markers are the points being solved for — red is the
## trigger grip, green the support hand on the handguard, blue the buttstock. If
## a hand is not on its marker the IK could not reach, which is a different
## problem from the marker being in the wrong place.
## The three coloured markers ARE the anchors — red is the trigger grip, green
## the support hand on the handguard, blue the buttstock — and they can be
## dragged. The marker under the mouse swells; drag it and the hand follows.
##
## Dragging an anchor is not the same as any slider above it. The sliders move
## the GUN: `grip_offset` slides the weapon around inside the fist, and
## `gun_fore` / `gun_stock` slide the hands along the weapon's own axis. Neither
## can take a hand OFF that axis, which is what a handguard below the bore, an
## angled foregrip or a pistol grip all need. A drag writes `grip_shift` or
## `fore_shift`, in the gun's own across/up/along frame, so a nudge sideways
## stays sideways as the weapon pitches; the buttstock marker writes the shoulder
## pocket for whichever pose is showing.
##
## If a hand is not ON its marker, the IK could not reach — a different problem
## from the marker being in the wrong place, and dragging the marker further will
## not fix it.
const POSES := [
["Low ready", "ground", 0.0, 0.0],
@@ -162,7 +175,8 @@ func _build_world() -> void:
# Depth-tested on purpose. Drawn through the body they look like they are
# floating in front of the chest when they are in fact behind an arm,
# which is exactly the wrong impression for judging whether a hand is on
# its target.
# its target. `_process` lifts this for the marker under the mouse, so
# the one you are about to grab is the one you can see.
mat.no_depth_test = false
m.material_override = mat
add_child(m)
@@ -269,6 +283,155 @@ func _process(_delta: float) -> void:
for i in _markers.size():
_markers[i].global_position = to_world * pts[i]
_markers[i].visible = pts[i] != Vector3.ZERO
# The one being dragged, or the one the mouse is over, swells AND
# draws through the body.
#
# Depth testing is right for the other two: drawn through the mesh
# they look like they are floating in front of the chest when they
# are in fact behind an arm, which is the wrong impression for
# judging whether a hand reached its target. But it is wrong for the
# one being grabbed — at any useful framing the hands occlude all
# three markers, and a handle you cannot see is a handle you cannot
# find. `_marker_under` never cared about occlusion; this makes that
# visible rather than a secret.
var hot: bool = (i == _drag_marker) or (_drag_marker < 0 and i == _hover_marker)
_markers[i].scale = Vector3.ONE * (1.9 if hot else 1.0)
var mat := _markers[i].material_override as StandardMaterial3D
if mat:
mat.no_depth_test = hot
# ── dragging the anchors ──────────────────────────────────────────────────────
#
# The markers are the anchor POINTS the hands are solved onto. Until now they
# could only be moved through the sliders, and two of the three could only move
# along the barrel — `gun_stock` and `gun_fore` are distances along the gun's own
# axis, so the trigger and support hands slid up and down the weapon and nowhere
# else. What the sliders DID move freely was the gun itself, under anchors that
# stayed put.
#
# So: grab a marker and drag it. Each one writes to the knob that expresses that
# motion, in the frame that knob is written in — which is why the pose layer now
# publishes the gun's basis. A drag left has to mean "left across the weapon"
# whether the muzzle is down at low ready or level at ADS.
## marker index -> [knob key, frame]. "gun" is the weapon's own across/up/along
## basis; "skeleton" is the model's, which is where the shoulder pocket lives.
const MARKER_KNOB := [
["grip_shift", "gun"],
["fore_shift", "gun"],
["pocket", "skeleton"], # resolved to pocket_hip / pocket_ads by pose
]
## How close, in pixels, the mouse has to be to a marker to take hold of it.
const GRAB_RADIUS := 26.0
var _drag_marker := -1
var _hover_marker := -1
## The plane a drag is measured on: fixed at grab time so it does not drift
## toward the camera as the marker follows the mouse.
var _drag_plane_at := Vector3.ZERO
var _drag_last := Vector3.ZERO
## The stock anchor is a blend of two knobs; a drag edits whichever one this
## pose is actually showing. Dragging at low ready must not silently rewrite the
## aiming pocket.
func _stock_knob() -> String:
return "pocket_ads" if POSES[_pose][3] > 0.5 else "pocket_hip"
func _knob_for(marker: int) -> String:
var key: String = MARKER_KNOB[marker][0]
return _stock_knob() if key == "pocket" else key
func _marker_under(mouse: Vector2) -> int:
var best := -1
var best_d := GRAB_RADIUS
for i in _markers.size():
if not _markers[i].visible:
continue
var p: Vector3 = _markers[i].global_position
# Behind the camera projects to a nonsense point that can still land
# within the grab radius.
if _cam.is_position_behind(p):
continue
var d := _cam.unproject_position(p).distance_to(mouse)
if d < best_d:
best_d = d
best = i
return best
## Where the mouse ray meets the drag plane — through the grab point, facing the
## camera.
func _plane_hit(mouse: Vector2) -> Vector3:
var origin := _cam.project_ray_origin(mouse)
var dir := _cam.project_ray_normal(mouse)
var n := -_cam.global_transform.basis.z
var denom := dir.dot(n)
if absf(denom) < 1e-5:
return _drag_last
return origin + dir * (((_drag_plane_at - origin).dot(n)) / denom)
func _begin_drag(marker: int, mouse: Vector2) -> void:
_drag_marker = marker
_drag_plane_at = _markers[marker].global_position
_drag_last = _plane_hit(mouse)
_status.text = "Dragging the %s anchor (%s)" % [
["trigger hand", "support hand", "buttstock"][marker], _knob_for(marker)]
func _drag_to(mouse: Vector2) -> void:
if _model == null or _model._pose_mod == null or _model.skeleton == null:
return
var now := _plane_hit(mouse)
var world_delta := now - _drag_last
_drag_last = now
# World -> skeleton, because that is the space the pose layer works in.
var delta: Vector3 = _model.skeleton.global_transform.basis.inverse() * world_delta
if MARKER_KNOB[_drag_marker][1] == "gun":
# ...and on into the gun's frame for the two hand anchors. Orthonormal,
# so the inverse is the transpose, but say what is meant.
delta = _model._pose_mod.dbg_gun_basis.inverse() * delta
var key := _knob_for(_drag_marker)
var spec := _spec_for("hold", key)
var cur: Vector3 = _knobs["hold"].get(key, WeaponHoldTuning.default_for(key))
if not (cur is Vector3):
cur = Vector3.ZERO
var lo: float = spec[2]
var hi: float = spec[3]
_set_knob("hold", key, Vector3(
clampf(cur.x + delta.x, lo, hi),
clampf(cur.y + delta.y, lo, hi),
clampf(cur.z + delta.z, lo, hi)))
func _spec_for(group: String, key: String) -> Array:
for spec in _specs(group):
if spec[0] == key:
return spec
return ["", "", -1.0, 1.0, true, Vector3.ZERO]
## Write a knob from somewhere other than its own slider, and keep the slider in
## step. Without the write-back the sliders would silently disagree with the
## model the moment anything was dragged, and Save would store the sliders.
func _set_knob(group: String, key: String, value) -> void:
_knobs[group][key] = value
var entry = _sliders[group].get(key)
if entry != null:
if entry.spec[4]:
entry.x.set_value_no_signal(value.x)
entry.y.set_value_no_signal(value.y)
entry.z.set_value_no_signal(value.z)
else:
entry.x.set_value_no_signal(float(value))
_refresh_label(group, key)
_push(group)
# ── knobs ─────────────────────────────────────────────────────────────────────
@@ -406,7 +569,7 @@ func _build_ui() -> void:
_status = Label.new()
_status.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
_status.custom_minimum_size = Vector2(400, 40)
_status.text = "left drag orbit · wheel zoom · middle drag pan · F frame hands"
_status.text = "DRAG A MARKER to move that anchor · left drag orbit · wheel zoom · middle drag pan · F frame hands"
box.add_child(_status)
# Reflect whatever the shot arguments or the defaults selected, or the
# dropdown says one thing while the scene shows another.
@@ -581,6 +744,14 @@ func _update_camera() -> void:
func _unhandled_input(e: InputEvent) -> void:
if e is InputEventMouseMotion:
# An anchor drag OWNS the left button — otherwise grabbing a marker
# would also orbit the camera, and the anchor would appear to move
# because the view did.
if _drag_marker >= 0:
_drag_to(e.position)
return
_hover_marker = _marker_under(e.position) \
if e.button_mask == 0 else _hover_marker
if e.button_mask & MOUSE_BUTTON_MASK_LEFT:
_yaw -= e.relative.x * 0.006
_pitch = clampf(_pitch - e.relative.y * 0.006, -1.4, 1.4)
@@ -589,6 +760,16 @@ func _unhandled_input(e: InputEvent) -> void:
var b := _cam.global_transform.basis
_pivot += (b.x * -e.relative.x + b.y * e.relative.y) * _dist * 0.0015
_update_camera()
elif e is InputEventMouseButton and e.button_index == MOUSE_BUTTON_LEFT:
if e.pressed:
var hit := _marker_under(e.position)
if hit >= 0:
_begin_drag(hit, e.position)
elif _drag_marker >= 0:
_status.text = "%s is now %s — Save to keep it" % [
_knob_for(_drag_marker),
_knobs["hold"].get(_knob_for(_drag_marker), Vector3.ZERO)]
_drag_marker = -1
elif e is InputEventMouseButton and e.pressed:
if e.button_index == MOUSE_BUTTON_WHEEL_UP:
_dist = maxf(_dist * 0.9, 0.15)