ADR-011: GameObject attachment hierarchy (parent/child transforms)

[diego3]

Summary

Proposes docs/adr/ADR_011_gameobject_attachment_hierarchy.md: a runtime attach/detach
capability for GameObjects — e.g. a sword GameObject attached to (and later detached from) the
player, following its position/rotation automatically. This is the "scene graph" capability
raised in conversation: does the engine support parent/child transform hierarchies for gameplay
objects, and how does that compare to Game Coding Complete's treatment of the same idea.

What it found and proposes

• Current state: no gameplay hierarchy exists. object.Transform is flat/world-space only
  (no parent field), and object.Manager holds a flat slice. This was actually already decided
  once — ADR-001 explicitly scoped parent/child to UI only, not gameplay, deferring it
  "until there is a concrete need." (Notably, even UI's optional hierarchy was never built —
  view/ui.Container is still a flat list.)
• Confronts it with the book: Game Coding Complete Ch. 9–10's SceneNode tree is the same
  idea — a child's world transform is derived from its parent's every frame, which is exactly
  how the book attaches a weapon to a character's hand/bone node with zero code in the weapon.
  The book's 4×4 matrix stack is 3D/DirectX-specific; the ADR shows the 2D equivalent needs only
  what vec2.Vector.Rotate already provides — no new math type required.
• Compares four approaches: per-script manual copying (Approach 1), reviving ADR-001's
  rejected unified SceneNode to cover gameplay too (Approach 2), an optional ParentID +
  LocalOffset on GameObject resolved by a small system each frame (Approach 3,
  recommended), and Box2D joints for physically-simulated attachment (Approach 4, additive
  for later).
• Recommendation: Approach 3 — additive, backward-compatible (unparented objects, the vast
  majority, are entirely unaffected), reuses the existing vec2 package, composes with the
  Prototype/spawnEntity spawning pattern already established (ADR-007/PR Propose game-architecture skill (Game Coding Complete patterns) #23's
  game-architecture skill), and mirrors the existing PhysicsSystem.SyncToWorld precedent of
  an external system overwriting Transform after another system runs.
• Leaves several implementation-time questions explicitly open (draw order, a detach/re-parent
  event API, Clone() semantics for a parent with attached children, cycle/depth guarding)
  rather than pre-deciding them.

No engine or game code changes — this PR only adds the ADR document, per this project's own
convention: "When making a significant architectural decision, create a new ADR" (CLAUDE.md).

---

Generated by Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.