diff --git a/docs/COMPLETION.md b/docs/COMPLETION.md
index 45d0e20..67f187c 100644
--- a/docs/COMPLETION.md
+++ b/docs/COMPLETION.md
@@ -22,13 +22,15 @@ verify each against the current owner before treating that historical list as a
## Confirmed defects and remaining gaps
-- **Intro sword prop attachment, repaired.** A static prop retained the standalone resting lift/hip turn
- after being attached to another actor's bone. The intro's separate rapier could consequently miss its
- intended position in the corpse. Attached static props now take the mounting frame without that extra
- resting pose, and are placed after the parent's animation advances. Standalone props and ordinary held
- weapons retain their existing poses. The expanded synthetic regression fails on the previous code and
- passes after the repair, including restoration of the standalone pose after detachment. The owned-disc
- intro was checked on an isolated rendered display, with the sword visible again.
+- **Intro sword prop attachment, repaired.** The previous check established visibility but missed the
+ inverted placement of grip and embedded blade. Attached actors kept a separate position while scripted
+ glides moved the engine's actor node; drawing then replaced that node's transform and discarded the
+ script's offsets. Position and heading now stay in the engine's motion state, while only the drawing
+ follows the mounting bone. The static standalone rest animation stops while attached and resumes on
+ detachment. A synthetic field verifies the tip at the mounting point, the raised grip at the hand,
+ instant and timed relative glides, handoff and detachment, without retail content. The owned-disc intro
+ was replayed on an isolated display through the corpse close-up, raised grip, withdrawal and subsequent
+ hand attachment. This is focused placement verification, not complete cutscene equivalence.
- **Attached weapon geometry during close-ups, repaired.** The close-camera projector walked all skinned
meshes in an actor but evaluated their binds through the body's skeleton, including a weapon's separate
diff --git a/docs/FIELD.md b/docs/FIELD.md
index 820d449..c9c2875 100644
--- a/docs/FIELD.md
+++ b/docs/FIELD.md
@@ -109,6 +109,13 @@ The room sub-section after the geometry is the collision map.
## Characters
+Attached actors retain their bone-local position and heading in the engine's actor motion state, so
+scripted glides and turns continue to apply. `EventActor.Apply` places only the drawing skeleton in the
+parent bone's frame; it never replaces the motion node with that world transform. Static props stop
+their standalone `rest` animation while attached and restore it and their original drawing frame on
+detachment. The synthetic projection contract exercises the embedded tip, raised grip and handoff,
+including instant and timed relative glides.
+
Close-camera projection resolves the skeleton bound to each skinned mesh. Attached weapons can
have their own skeleton and global attachment transform; their numeric or named skin binds must
never be evaluated through the body skeleton. Hidden attachment parents remain hidden during
diff --git a/scenes/field/EventActor.cs b/scenes/field/EventActor.cs
index 5014b58..71a683d 100644
--- a/scenes/field/EventActor.cs
+++ b/scenes/field/EventActor.cs
@@ -21,25 +21,27 @@ public sealed class EventActor
public readonly Node3D Node;
public readonly Skeleton3D? Skeleton;
public readonly AnimationPlayer? Player;
+ private readonly Transform3D _skeletonSpace;
+ private bool _attached;
/// The engine's field the actor stands in, which places, turns and shapes it.
public Wol.Engine.World.FieldScene? Scene { get; init; }
///
/// Where the actor stands, in map units: the engine's place for it, turned into retail space (bone-local, and kept
- /// here, while it is attached to another actor).
+ /// in the engine's motion node while attached to another actor).
///
public Vector3 Position
{
- get => Parent == null && Scene != null && Scene.Actors.TryGetValue(Id, out var node) ? RetailSpace.AffineInverse() * node.Position : _position;
- set { if (Parent == null && Scene != null && Scene.Actors.ContainsKey(Id)) Scene.SetActorPosition(Id, RetailSpace * value); else _position = value; }
+ get => Scene != null && Scene.Actors.TryGetValue(Id, out var node) ? RetailSpace.AffineInverse() * node.Position : _position;
+ set { if (Scene != null && Scene.Actors.ContainsKey(Id)) Scene.SetActorPosition(Id, RetailSpace * value); else _position = value; }
}
private Vector3 _position;
/// The way it faces, 4096 a turn about retail's (downward) y: the engine's heading, which turns the other way.
public float Facing
{
- get => Parent == null && Scene != null && Scene.ActorHeadings.TryGetValue(Id, out float heading) ? Mathf.PosMod(-heading * 4096 / Mathf.Tau, 4096) : _facing;
- set { if (Parent == null && Scene != null && Scene.Actors.ContainsKey(Id)) Scene.UpdateCharacterDirection(Id, false, Mathf.Wrap(-value * Mathf.Tau / 4096, -Mathf.Pi, Mathf.Pi)); else _facing = value; }
+ get => Scene != null && Scene.ActorHeadings.TryGetValue(Id, out float heading) ? Mathf.PosMod(-heading * 4096 / Mathf.Tau, 4096) : _facing;
+ set { if (Scene != null && Scene.Actors.ContainsKey(Id)) Scene.UpdateCharacterDirection(Id, false, Mathf.Wrap(-value * Mathf.Tau / 4096, -Mathf.Pi, Mathf.Pi)); else _facing = value; }
}
private float _facing;
/// Its extra angles (4096 a turn about retail's x, y and z): the engine's body shape, turned back into retail space.
@@ -92,6 +94,7 @@ public EventActor(string id, int character, Node3D node)
Character = character;
Node = node;
Skeleton = node.FindChildren("*", "Skeleton3D", true, false) is { Count: > 0 } skeletons ? (Skeleton3D)skeletons[0] : null;
+ _skeletonSpace = Skeleton?.Transform ?? Transform3D.Identity;
Player = node.FindChildren("*", "AnimationPlayer", true, false) is { Count: > 0 } players ? (AnimationPlayer)players[0] : null;
}
@@ -575,15 +578,24 @@ public void Apply()
// first two bones inherit the mounting frame instead of adding the humanoid rest turn/lift.
if (Player?.AssignedAnimation == "rest" && Skeleton is { } own)
{
+ Player.Stop(true);
own.ResetBonePose(0);
if (own.GetBoneCount() > 1) own.ResetBonePose(1);
}
var bone = skeleton.GlobalTransform * skeleton.GetBoneGlobalPose(held);
- Scene?.UpdateCharacterDirection(Id, false, 0);
- Scene?.SetActorBody(Id, Basis.Identity);
- Node.GlobalTransform = bone * Local() * ModelSpace.AffineInverse();
+ // Keep the actor node in the engine's motion space. Glides and turns continue there,
+ // including the script's offset that places a prop's grip above its embedded tip.
+ // Only the drawing follows the mounting bone; overwriting Node lost those glides.
+ if (Skeleton is { } drawing) drawing.GlobalTransform = bone * Local();
+ _attached = true;
return;
}
+ if (_attached && Skeleton is { } detached)
+ {
+ detached.Transform = _skeletonSpace;
+ if (Player?.AssignedAnimation == "rest") { Player.Play("rest"); Player.Advance(0); }
+ _attached = false;
+ }
if (Scene == null || !Scene.Actors.ContainsKey(Id)) { Node.Transform = RetailSpace * Local() * RetailSpace.AffineInverse(); return; }
Node.Basis = Basis.Identity;
if (Scene.TryGetActorShape(Id, out var shape)) Scene.SetActorBody(Id, shape.Body);
diff --git a/tests/ActorProjectionContracts.cs b/tests/ActorProjectionContracts.cs
index fb0df62..d2bd40a 100644
--- a/tests/ActorProjectionContracts.cs
+++ b/tests/ActorProjectionContracts.cs
@@ -2,6 +2,7 @@
using System;
using Godot;
using Wol.Games.Vagrant.Scenes.Field;
+using Wol.Engine.World;
namespace Wol.Games.Vagrant.Tests;
/// Synthetic attached rigs must keep their own skeleton when projected near the eye; no game data.
@@ -84,10 +85,61 @@ public override void _Ready()
if(!propBones.GetBonePose(0).IsEqualApprox(Transform3D.Identity)
|| !propBones.GetBonePose(1).IsEqualApprox(Transform3D.Identity))
throw new InvalidOperationException("Attached prop added its standalone lift/turn to the mounting frame.");
- standalone.Parent=null; player.Advance(0);
+ player.Advance(0);
+ if(!propBones.GetBonePose(0).IsEqualApprox(Transform3D.Identity) || !propBones.GetBonePose(1).IsEqualApprox(Transform3D.Identity))
+ throw new InvalidOperationException("The standalone rest animation overwrote the attached prop's pose.");
+ standalone.Parent=null; standalone.Apply();
if(propBones.GetBonePosePosition(0).Y!=3) throw new InvalidOperationException("Detaching a prop did not restore its standalone pose.");
root.Free(); root=null;
- GD.Print("ACTOR_PROJECTION_CONTRACTS_OK: numeric/named skin binds, body independence, moving and hidden attachments, static prop attachment pose");
+ root = new FieldScene(); AddChild(root);
+ var field = (FieldScene)root;
+ field.SetProcess(false); field.SetPhysicsProcess(false);
+ using var source = Json.ParseString("""{"schema":1,"models":[],"objects":[{"id":0,"model":-1,"position":[0,0,0]},{"id":1,"model":-1,"position":[0,0,0]}],"walkmeshes":[]}""").AsGodotDictionary();
+ if(field.LoadField(source,new())!=Error.Ok) throw new InvalidOperationException("Cannot load the synthetic prop motion field.");
+ var mount = new Skeleton3D {Transform=new Transform3D(new Basis(Vector3.Back,-Mathf.Pi/2).Scaled(Vector3.One/128),new Vector3(3,1,-4))};
+ field.Actors["0"].AddChild(mount);
+ mount.AddBone("b0"); mount.AddBone("b1"); mount.SetBoneParent(1,0);
+ mount.SetBoneRest(0,Transform3D.Identity);
+ mount.SetBoneRest(1,new Transform3D(Basis.Identity,new Vector3(-100,0,0))); mount.ResetBonePoses();
+ var swordBones = new Skeleton3D {Transform=EventActor.ModelSpace}; field.Actors["1"].AddChild(swordBones);
+ swordBones.AddBone("b0"); swordBones.AddBone("b1"); swordBones.AddBone("b2");
+ swordBones.SetBoneParent(1,0); swordBones.SetBoneParent(2,1);
+ swordBones.SetBoneRest(0,Transform3D.Identity); swordBones.SetBoneRest(1,Transform3D.Identity);
+ swordBones.SetBoneRest(2,new Transform3D(Basis.Identity,new Vector3(50,0,0))); swordBones.ResetBonePoses();
+ var mounted = new EventActor("1",0,field.Actors["1"]) {Scene=field,Parent=new EventActor("0",0,field.Actors["0"]) {Scene=field},Visible=true};
+ var offset = new Vector3(-100,0,0);
+ if(field.Present(default,new ActorGlide("1",EventActor.RetailSpace*offset,true,0) {FrameRate=30},_=>{})!=Error.Ok)
+ throw new InvalidOperationException("Cannot place the synthetic sword with a relative glide.");
+ mounted.Apply();
+ var grip=swordBones.GlobalTransform*swordBones.GetBoneGlobalPose(1).Origin;
+ var tip=swordBones.GlobalTransform*swordBones.GetBoneGlobalPose(2)*new Vector3(50,0,0);
+ var hand=mount.GlobalTransform*mount.GetBoneGlobalPose(1).Origin;
+ if(grip.DistanceTo(hand)>.0001f || tip.DistanceTo(mount.GlobalPosition)>.0001f || grip.Y<=tip.Y)
+ throw new InvalidOperationException("The scripted offset did not embed the tip with the grip at the raised hand.");
+ if(mounted.Position.DistanceTo(offset)>.0001f || field.Actors["1"].Position.DistanceTo(EventActor.RetailSpace*offset)>.0001f)
+ throw new InvalidOperationException("Drawing an attachment overwrote its logical glide position.");
+ if(field.Present(default,new ActorGlide("1",EventActor.RetailSpace*new Vector3(0,0,128),true,8) {FrameRate=30},_=>{})!=Error.Ok)
+ throw new InvalidOperationException("Cannot start the attached sword's timed glide.");
+ field.AdvancePresentation(); mounted.Apply();
+ if(mounted.Position.Z<=0 || mounted.Position.Z>=128) throw new InvalidOperationException("The attached glide did not advance over time.");
+ for(int tick=0;tick<32;tick++) {field.AdvancePresentation(); mounted.Apply();}
+ if(mounted.Position.DistanceTo(offset+new Vector3(0,0,128))>.0001f)
+ throw new InvalidOperationException("An attached relative glide lost its destination across drawing updates.");
+ if(field.Present(default,new ActorFace("1",Mathf.Pi/2),_=>{})!=Error.Ok)
+ throw new InvalidOperationException("Cannot turn an attached sword.");
+ mounted.Apply();
+ grip=swordBones.GlobalTransform*swordBones.GetBoneGlobalPose(1).Origin;
+ tip=swordBones.GlobalTransform*swordBones.GetBoneGlobalPose(2)*new Vector3(50,0,0);
+ if(tip.DistanceTo(grip+mount.GlobalBasis*new Vector3(0,0,100))>.0001f)
+ throw new InvalidOperationException("The attachment ignored its scripted heading.");
+ field.Present(default,new ActorFace("1",0),_=>{});
+ mounted.ParentBone=1; mounted.Position=Vector3.Zero; mounted.Apply();
+ grip=swordBones.GlobalTransform*swordBones.GetBoneGlobalPose(1).Origin;
+ if(grip.DistanceTo(hand)>.0001f) throw new InvalidOperationException("Reattachment did not place the grip at the grabbing hand.");
+ mounted.Parent=null; mounted.Apply();
+ if(!swordBones.Transform.IsEqualApprox(EventActor.ModelSpace)) throw new InvalidOperationException("Detaching retained the mounting frame in the drawing.");
+ root.Free(); root=null;
+ GD.Print("ACTOR_PROJECTION_CONTRACTS_OK: numeric/named skin binds, body independence, moving and hidden attachments, static prop attachment pose, embedded tip/grip, instant/timed relative glides and handoff");
GetTree().Quit();
}
catch(Exception error){root?.Free();camera?.Free();GD.PrintErr("ACTOR_PROJECTION_CONTRACTS_FAILED: "+error);GetTree().Quit(1);}