scripting: runtime attachment API — Attach/Detach/GetBoneTransform

[shadow-kernel]

Context

Sockets authored in the editor cover the static case (character starts with flashlight in hand). Gameplay needs the dynamic case: pick a weapon up from a table, holster it, drop it when the monster strikes, swap items. Gameplay lives in project scripts (VortexBehaviour) per the engine philosophy — so the socket system needs a script-facing API.

Goal

Vortex API surface: attach an entity to a bone of a skinned entity at runtime, detach it (keeping world position or resetting), and query bone/socket world transforms — e.g. the muzzle tip for Physics.Raycast hitscan.

Acceptance Criteria

• entity.AttachTo(target, boneName, localPos, localRot) and entity.Detach(keepWorldPosition: bool) callable from VortexBehaviour
• target.GetBoneWorldTransform(boneName) returns position/rotation usable for raycast origins and VFX spawn points
• Attach/detach mid-animation causes no pop when keepWorldPosition = true (world transform preserved, offset recomputed)
• Attaching an entity with a collider updates collision correctly; detaching re-enables independent physics behavior
• List sockets/attachments query (GetAttachedEntities)
• Sample: pickup script — player looks at pistol (raycast), presses E, pistol snaps into the hand socket

Technical Notes

Route through the same socket registry as the component version — one code path. Guard against attach-cycles (A to B to A). Works together with SetActive toggles (holstered weapon = attached + inactive).

Dependencies

• animation: bone socket system — entities attach to skeleton bones and follow animation exactly
• physics: Physics.Raycast for game scripts (+ RaycastHit, layers)
• scripting: entity & component enable/disable at runtime (SetActive, renderer/collider/source toggles)