From a7f1e9c7615454437ef45b93f63df1f1ee416c8f Mon Sep 17 00:00:00 2001 From: JOY Date: Thu, 28 May 2026 00:36:48 +0700 Subject: [PATCH] docs: define alpha animation system architecture --- ROADMAP.md | 9 + docs/ARCHITECTURE.md | 7 + docs/SUMMARY.md | 1 + docs/design/03-systems-index.md | 10 +- .../38-alpha-design-decision-register.md | 2 + .../44-alpha-body-rig-action-compatibility.md | 7 +- .../58-alpha-animation-system-architecture.md | 532 ++++++++++++++++++ 7 files changed, 563 insertions(+), 5 deletions(-) create mode 100644 docs/design/58-alpha-animation-system-architecture.md diff --git a/ROADMAP.md b/ROADMAP.md index bb367ede..4dafbae2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -140,6 +140,11 @@ Recommended views: #178, defining Unity 6000.5 Humanoid Avatar checks, semantic action coverage, weapon visibility, root-motion safety, scale, nameplate readability, and candidate body evidence requirements. +- [x] Alpha animation architecture documented, deciding that the project-owned + semantic action/profile layer is the source of truth; ExplosiveLLC remains a + prototype adapter and clip source, Opsive UCC is a later authority spike, and + BR200-style custom Playables animation is deferred until measured evidence + requires tick accuracy or performance work. - [x] Alpha art direction and asset buying guide documented, defining Anime-Ready Semi-Real as the buying target, clean PBR guardrails, medieval asset limits, character and environment reject criteria, Unity 6.5 URP import @@ -197,6 +202,10 @@ Recommended views: - [ ] Evaluate installing Unity Animation Rigging for Ida Faber and future semi-real bodies, then add authored look-at, weapon aim, two-bone hand IK, and foot IK constraints as a focused animation-import lane. Track in #263. +- [ ] Convert the prototype animation registry into explicit body, weapon, and + timing profile assets or structured catalogs, then add a missing-action smoke + matrix before importing another major character animation framework. Track in + #278. - [x] Prototype combat visuals now distinguish dual-swords from one-hand sword semantics and recover from one-shot attack, cast, dodge, pickup, gather, and hit-react poses back into body-aware idle states. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 97e27d78..f6cdc3ce 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -482,6 +482,13 @@ Unity owns visual animation presentation only. Fusion owns movement and combat authority, while Nakama owns durable stats and profile data. The current shared humanoid contract is split into two layers: +The alpha animation architecture decision lives in +[design/58-alpha-animation-system-architecture.md](design/58-alpha-animation-system-architecture.md). +That document keeps ExplosiveLLC as a prototype adapter and clip source, +keeps Opsive UCC as a later authority spike, and defers a BR200-style custom +Playables controller until evidence shows tick accuracy or performance requires +it. + - Gameplay and AI request `CharacterActionId` values such as `Talk`, `Attack`, `HitReact`, `Death`, or `Gather`. - `CharacterAnimationRegistry` maps those semantic action ids to the active diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index d7288470..da3bfc01 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -64,6 +64,7 @@ - [Alpha Visual Budget](design/42-alpha-visual-budget.md) - [Alpha Material and Shader Recipe](design/43-alpha-material-shader-recipe.md) - [Alpha Body Rig and Action Compatibility](design/44-alpha-body-rig-action-compatibility.md) +- [Alpha Animation System Architecture](design/58-alpha-animation-system-architecture.md) - [Art Direction and Asset Buying Guide](design/48-art-direction-and-asset-buying-guide.md) ## Technical Design diff --git a/docs/design/03-systems-index.md b/docs/design/03-systems-index.md index e21ed82e..62aa7866 100644 --- a/docs/design/03-systems-index.md +++ b/docs/design/03-systems-index.md @@ -93,11 +93,15 @@ The first alpha execution spine is: 18. [44-alpha-body-rig-action-compatibility.md](44-alpha-body-rig-action-compatibility.md) for the Unity 6000.5 Humanoid Avatar, action registry, weapon visibility, root motion, scale, nameplate, and candidate body evidence checklist. -19. [48-art-direction-and-asset-buying-guide.md](48-art-direction-and-asset-buying-guide.md) +19. [58-alpha-animation-system-architecture.md](58-alpha-animation-system-architecture.md) + for the alpha animation architecture decision, Explosive/Opsive/BR200 + evaluation, semantic action layer, body and weapon profiles, network + authority split, and AI-agent-friendly implementation plan. +20. [48-art-direction-and-asset-buying-guide.md](48-art-direction-and-asset-buying-guide.md) for Anime-Ready Semi-Real asset-buying guardrails, medieval asset limits, character and environment requirements, reject criteria, and Unity 6.5 URP import evaluation. -20. [45-inventory-and-equipment-system.md](45-inventory-and-equipment-system.md) +21. [45-inventory-and-equipment-system.md](45-inventory-and-equipment-system.md) for body carry inventory, account/soul stash, Garden stash, temporary Gate loot, equipment slots, custody lifecycle states, hostile / monster / boss body equipment rules, starter item definitions, death loss rules, UI flows, @@ -117,7 +121,7 @@ blockout tasks for the alpha. | 3 | Camera (top-down ARPG) | Core | MVP | Prototype | (TDD pending) | Player Controller | | 4 | Input system (Unity Input System) | Core | MVP | Prototype | - | Player Controller | | 5 | Zone scene management (1 zone vertical slice) | Core | MVP | Prototype | (TDD pending) | NetworkRunner | -| 6 | Combat (ARPG action) | Gameplay | MVP | Not started | [39-alpha-stats-and-skills-design.md](39-alpha-stats-and-skills-design.md), [26-alpha-game-design-document.md](26-alpha-game-design-document.md), [27-alpha-level-design.md](27-alpha-level-design.md) | Player Controller, Networked state | +| 6 | Combat (ARPG action) | Gameplay | MVP | Not started | [39-alpha-stats-and-skills-design.md](39-alpha-stats-and-skills-design.md), [58-alpha-animation-system-architecture.md](58-alpha-animation-system-architecture.md), [26-alpha-game-design-document.md](26-alpha-game-design-document.md), [27-alpha-level-design.md](27-alpha-level-design.md) | Player Controller, Networked state | | 7 | NPC dialogue and human-believable NPC agent model | Gameplay | MVP | Design | [13-human-believable-npc-agent-model.md](13-human-believable-npc-agent-model.md), [16-npc-society-multi-agent-architecture.md](16-npc-society-multi-agent-architecture.md), [21-permanent-npc-story-characteristics.md](21-permanent-npc-story-characteristics.md), [36-ai-npc-research-anchor-map.md](36-ai-npc-research-anchor-map.md), [37-ai-npc-backend-client-roadmap.md](37-ai-npc-backend-client-roadmap.md) | api.dos.ai model service (phase 2 ready), Profile persistence | | 8 | Quest system (linear, 3-5 quests slice scope) | Gameplay | VS | Not started | [35-alpha-content-and-copy-pack.md](35-alpha-content-and-copy-pack.md), [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md), [26-alpha-game-design-document.md](26-alpha-game-design-document.md), [27-alpha-level-design.md](27-alpha-level-design.md) | NPC dialogue, persistence | | 9 | Dungeon instance (1 dungeon, 1 boss) | Gameplay | VS | Not started | [27-alpha-level-design.md](27-alpha-level-design.md), [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md), [15-gate-dungeon-pioneer-charter-system.md](15-gate-dungeon-pioneer-charter-system.md) | Combat, NPC dialogue, Photon | diff --git a/docs/design/38-alpha-design-decision-register.md b/docs/design/38-alpha-design-decision-register.md index 55744e7b..a31e8cf5 100644 --- a/docs/design/38-alpha-design-decision-register.md +++ b/docs/design/38-alpha-design-decision-register.md @@ -74,6 +74,7 @@ first playable alpha. | Alpha starter kit | Sentinel or balanced contractor is still the recommended first playable kit. | `39-alpha-stats-and-skills-design.md` | | Alpha skill origin | Skill data must distinguish origin from slot and animation intent. The minimum useful origins are soul, body imprint, body physical, weapon, profession, agent routine, and anomaly. | `39-alpha-stats-and-skills-design.md` | | Skill carryover | Learned soul skills may survive body loss, but actual execution remains limited by current body stats, equipment, injury, policy, and soul-body sync. Body imprint and physical body skills are lost with the body by default. | `40-soul-skill-carryover-and-sync.md` | +| Animation architecture | Alpha uses a project-owned semantic animation intent layer plus body, weapon, and timing profiles. ExplosiveLLC remains a prototype adapter and clip source, Opsive UCC is a later authority spike, and a BR200-style custom Playables controller is deferred until evidence proves tick accuracy or performance requires it. | `58-alpha-animation-system-architecture.md` | | Art look-dev target | Prove Anime-Ready Semi-Real through one small look-dev scene before buying or importing a large asset family. | `32-alpha-art-audio-and-content-direction.md` | --- @@ -154,3 +155,4 @@ When a design question appears during implementation: | `38-alpha-design-decision-register.md` | Decision state and scope control. | | `39-alpha-stats-and-skills-design.md` | Alpha stat scale, skill origin, starter kits, and validation rules. | | `40-soul-skill-carryover-and-sync.md` | Learned skill carryover, body imprint loss, soul-body sync, and execution limits. | +| `58-alpha-animation-system-architecture.md` | Semantic animation architecture, Explosive/Opsive/BR200 evaluation, body/weapon/timing profiles, and authority split. | diff --git a/docs/design/44-alpha-body-rig-action-compatibility.md b/docs/design/44-alpha-body-rig-action-compatibility.md index b93d3a66..49c0929a 100644 --- a/docs/design/44-alpha-body-rig-action-compatibility.md +++ b/docs/design/44-alpha-body-rig-action-compatibility.md @@ -3,8 +3,11 @@ *Status: Alpha validation protocol for issue #178* *Created: 2026-05-23* *Source of truth level: Candidate body rig, scale, weapon, and animation -compatibility validation for Unity `6000.5.0b9`. This is not a final animation -controller rebuild plan.* +compatibility validation for Unity `6000.5.0b9`. This is not the alpha +animation architecture decision. Use +[58-alpha-animation-system-architecture.md](58-alpha-animation-system-architecture.md) +for the animation controller, vendor adapter, authority, and AI-agent +development direction.* --- diff --git a/docs/design/58-alpha-animation-system-architecture.md b/docs/design/58-alpha-animation-system-architecture.md new file mode 100644 index 00000000..b9be9474 --- /dev/null +++ b/docs/design/58-alpha-animation-system-architecture.md @@ -0,0 +1,532 @@ +# Alpha Animation System Architecture + +*Status: Alpha architecture baseline* +*Created: 2026-05-28* +*Source of truth level: Animation architecture decision for alpha. This file +decides how SECOND SPAWN should combine Unity, Photon Fusion, purchased +animation packs, body families, weapons, outfits, NPC actions, and AI-driven +development.* + +--- + +## 1. Purpose + +SECOND SPAWN needs many humanoid bodies, NPC-like actors, player-inhabited +Frames, hostile bodies, weapons, outfits, dialogue states, non-combat work +actions, and combat actions. The animation system must scale without forcing +gameplay code, AI agent code, or backend data to know vendor Animator state +names. + +This document answers three current production questions: + +1. Should the project use the ExplosiveLLC RPG Character Mecanim Animation + Pack animation controller as the main controller and extend it? +2. If that is not enough, should the project adopt another controller, such as + Opsive Ultimate Character Controller, for RPG character animation? +3. Should the project write a custom Playables animation system similar to the + Photon Fusion BR200 sample? + +--- + +## 2. Decision Summary + +Alpha should use a project-owned semantic animation architecture: + +- Gameplay, AI, skills, dialogue, and backend-facing data request semantic + actions such as `Talk`, `Attack`, `Cast`, `Dodge`, `Gather`, `HitReact`, and + `Death`. +- A project-owned animation registry maps those semantic actions to the active + body family, weapon archetype, outfit limitations, Animator parameters, + clip/profile timing, fallback state, and presentation-only events. +- Unity Humanoid retargeting remains the default for reusable human bodies. +- Unity Animator Controller plus Animator Override Controller remains the + default alpha implementation path because it is built into Unity, cheap to + inspect, easy for agents to edit, and compatible with the current prototype. +- ExplosiveLLC remains a prototype-native animation family and clip source, not + the long-term architecture owner. +- Opsive UCC is an evaluation candidate for character-controller and animation + patterns, not the default architecture owner. +- A BR200-style custom Playables controller is not an alpha default. It is a + future optimization path only if the project later needs tick-accurate + animation evaluation or 100-200 visible animated actors with server-side + animation cost constraints. +- Unity Animation Rigging should be evaluated next for look-at, hands, weapon + grips, aim correction, and foot IK, especially for Ida Faber semi-real bodies. +- Animancer or a small Playables adapter can be evaluated later if Animator + Controller graph complexity becomes a production blocker. + +Short version: keep the game architecture project-owned and semantic. Use +vendor controllers through adapters. Do not let any purchased animation +controller become the gameplay contract. + +--- + +## 3. Project Constraints + +SECOND SPAWN has constraints that are not the same as a normal single-character +action demo: + +- The player can inhabit many bodies over time. +- Important NPCs and player bodies share the same broad actor model. +- Offline AI agents and NPC agents must request actions through safe, + server-validated intent surfaces. +- Combat must be server-authoritative. Animation may present timing, but it + must not decide damage, rewards, inventory, TIME, SECOND, quest state, or body + death. +- The Unity client must support multiple body families, including low-poly + prototype bodies and semi-real Ida Faber bodies. +- The development workflow is mostly AI-agent-driven, so data-driven contracts + beat hand-edited Animator graph behavior. +- The root Unity integration workspace is shared by agents, so new animation + packages and controller rewrites must be done in small locked lanes. + +--- + +## 4. Answering JOY's Questions + +### 4.1 Should We Use Explosive AC And Extend It? + +Use it for alpha prototype coverage, but do not make it the core architecture. + +ExplosiveLLC is useful because the current prototype already has an action +surface, weapon actions, locomotion, animation events such as `Hit()` and +`Shoot()`, IK helpers, and enough RPG-flavored action clips to get visible +combat and non-combat states moving. It is a good source family for the +prototype. + +It is not a good long-term owner of SECOND SPAWN animation architecture because: + +- Its controller expects its own component stack and action strings. +- It brings movement/controller assumptions such as SuperCharacterController + and RPGCharacterMovementController that should not own Fusion movement. +- Its action availability depends on Mecanim state-machine context, which is + fine inside the pack but not safe as the game-level action contract. +- Its animation events are useful for presentation timing but cannot own + authority. +- Ida Faber and future semi-real body families already need body-family + correction, hand policy, and likely different override clips. + +Decision: + +> Keep Explosive AC behind the project registry as one body-family adapter. +> Extend the project semantic layer, not the vendor controller as the game +> contract. + +### 4.2 If Not Explosive AC, Whose AC Should We Use? + +Do not replace Explosive AC with another monolithic animation controller as the +core contract. + +For alpha, the best default is: + +- Project-owned `CharacterActionId` and animation profile data. +- Unity Humanoid Animator Controller as the common presentation baseline. +- Animator Override Controllers for body-family or archetype-specific clip + replacements. +- Avatar Masks and animation layers for upper-body, full-body, and additive + action separation. +- Animation Rigging for procedural correction. +- Optional adapters for ExplosiveLLC, Opsive, or later Animancer/Playables. + +Opsive UCC is still valuable. Its docs show an extensible ability system, +manual ability start/stop APIs, network synchronization support, and a layered +Animator design with movement, item, upper-body, additive, and full-body layers. +Those are useful patterns for an RPG with many weapons. + +However, Opsive should not become the default source of truth before a focused +Fusion authority spike proves: + +- The project can drive Opsive through semantic intents. +- Fusion remains authoritative for movement, combat, physics, and hit + validation. +- Opsive abilities do not become the only place where gameplay rules live. +- AI agents can request safe actions without knowing Opsive internals. +- Body swap, weapon swap, outfit swap, and NPC-only action coverage remain + data-driven enough for agent development. + +Decision: + +> Use Unity Humanoid plus the project semantic registry as the alpha backbone. +> Evaluate Opsive as an adapter/spike, not as the animation architecture owner. + +### 4.3 Should We Write Our Own BR200-Style Animation System? + +Not for alpha. + +Photon BR200 uses a custom Playables animation controller with tick-accurate +evaluation and dynamic performance scaling. It is built for a high-performance +third-person battle royale sample with up to 200 players and generic-rig baked +animations. Photon also notes that most games use render-accurate animation, +while tick-accurate animation is rare and mainly needed when animation affects +gameplay. + +SECOND SPAWN alpha should not use animated bone transforms for authoritative +combat. The server should validate range, cone, line of sight, cooldown, +impact time, hit masks, damage, death, rewards, TIME, SECOND, inventory, and +quest effects from gameplay data. That makes render-accurate animation enough +for alpha presentation. + +Writing a custom Playables controller now would create unnecessary risk: + +- More code for agents to maintain before the core game is proven. +- Less compatibility with purchased Unity animation packs. +- More debugging surface in Unity 6.5 beta. +- More chance of diverging from ordinary Unity workflows before the project has + enough production animation content to justify it. + +Decision: + +> Do not build a BR200-style controller for alpha. Keep it as a future +> performance or tick-accuracy option if evidence later demands it. + +--- + +## 5. Recommended Architecture + +```text +Player input / AI agent / NPC policy / skill request + -> Semantic action intent + -> Fusion or Nakama validation where gameplay state may change + -> Networked action state or presentation request + -> CharacterAnimationRegistry + -> BodyAnimationProfile + WeaponAnimationProfile + Outfit/prop policy + -> Animator / Override Controller / optional package adapter + -> Local presentation events only +``` + +### 5.1 Semantic Action Layer + +The action layer is the game-facing contract. It should use stable identifiers, +not vendor graph names. + +Minimum alpha action groups: + +| Group | Required Actions | +| ---- | ---- | +| Locomotion | Idle, Walk, Run, Stop, Turn | +| Dialogue | Talk, DialogIdle, Agree, Disagree, Listen | +| Combat | Attack, Cast, HitReact, Death, Revive | +| Defense and movement | DodgeLeft, DodgeRight, DodgeBackward, Block if scoped | +| Interaction | Interact, PickUpItem, Gather, FacilityWork, Sit | +| Presentation | Bored, LookAt, EmoteLight | + +Each gameplay skill should reference: + +| Field | Meaning | +| ---- | ---- | +| `animation_intent` | Semantic action id, such as `attack`, `cast`, or `gather`. | +| `body_pose_family` | Optional body-family requirement, such as one-hand melee, dual-swords, bow, staff, unarmed, or tool. | +| `timing_profile_id` | Presentation timing profile for anticipation, impact, recovery, and cancel windows. | +| `authority_profile_id` | Gameplay validation profile for server-side range, cone, cooldown, target rules, and damage. | +| `fallback_intent` | Safe fallback when the body lacks the ideal animation. | + +### 5.2 Body Animation Profile + +A `BodyAnimationProfile` should answer: + +- Which Animator Controller or package adapter should this body family use? +- Which Humanoid Avatar has been verified? +- Which scale normalization and nameplate offset apply? +- Which actions are required, optional, unsupported, or unsafe? +- Does the body support jump, dodge, block, aim, sit, gather, and talk? +- Does the body need finger filtering, hand IK, foot IK, look-at, weapon grip + correction, or hair/accessory secondary rigging? +- Which animation events are allowed as presentation-only timing signals? +- Which root-motion clips are banned, converted to in-place, or explicitly + handled by gameplay code? + +### 5.3 Weapon Animation Profile + +A `WeaponAnimationProfile` should answer: + +- Weapon archetype: unarmed, one-hand, dual-swords, two-hand, spear, bow, staff, + firearm, tool. +- Grip sockets and prop visibility policy. +- Upper-body versus full-body action preference. +- Attack timing defaults. +- Projectile or tracer presentation type. +- Sheathe, relax, dialogue, gather, and facility-work visibility rules. + +### 5.4 Timing Profile + +Animation timing is allowed to inform presentation, but not authority by itself. + +| Timing Field | Use | +| ---- | ---- | +| `anticipation_seconds` | Visual wind-up and UI/VFX lead-in. | +| `impact_seconds` | Suggested frame when local presentation should show impact. | +| `recovery_seconds` | Visual recovery and transient action cleanup. | +| `cancel_window_seconds` | Optional later combat feel tuning. | +| `server_hit_window_seconds` | Server validation window derived from gameplay design, not from a clip event alone. | + +Animation clip events such as `Hit()` and `Shoot()` can notify the local +animation bridge or a server-authority hook that the clip reached a timing +point. They must not directly apply damage. + +--- + +## 6. Vendor And Package Evaluation + +### 6.1 ExplosiveLLC RPG Character Mecanim Animation Pack + +Best use: + +- Prototype-native humanoid RPG action family. +- Quick coverage for attack, cast, dodge, relax, hit, shoot, footstep, weapon, + and simple interaction presentation. +- Reference for how to expose action handlers and context objects. + +Risks: + +- Vendor action strings and state assumptions can leak into gameplay. +- Movement/controller components conflict with Fusion authority if adopted + wholesale. +- Some clip curves do not fit semi-real hands. +- Not designed as a multi-body live-service content architecture. + +Project rule: + +- Keep it behind adapter/profile mapping. +- Use its clips and events where useful. +- Do not let gameplay or AI call Explosive state names directly. + +### 6.2 Opsive Ultimate Character Controller + +Best use: + +- Evaluation source for ability priority, layered Animator structure, item + layers, hands, additive reactions, and full-body overrides. +- Possible future adapter if its Fusion/network integration and authority + boundaries prove clean. + +Risks: + +- Large framework surface. +- Ability priority and item systems can become hidden gameplay rules. +- AI-agent-driven development is harder if behavior lives mainly in inspector + graphs and vendor components. +- Needs a separate spike before being trusted in a Fusion server-authoritative + MMO/ARPG loop. + +Project rule: + +- Evaluate after the minimal controller and Simple KCC path are stable. +- Do not import or wire it into core scenes as the default without a small + branch, console check, play smoke, and architecture review. + +### 6.3 Unity Animator Controller And Animator Override Controller + +Best use: + +- Alpha default. +- Shared humanoid state machine with per-body or per-archetype clip overrides. +- Agent-friendly because assets and code can be mapped through explicit data. + +Risks: + +- Large state graphs become hard to reason about. +- Triggers can be unreliable in complex networked setups. +- Runtime override swapping can reset state if used carelessly. + +Project rule: + +- Keep the graph small. +- Prefer stable bool/int/networked action state over trigger-heavy logic for + complex network presentation. +- Use Override Controllers for known body-family variants, not arbitrary runtime + clip mutation. + +### 6.4 Unity Animation Rigging + +Best use: + +- Look-at, aiming, hand IK, two-hand weapon grips, prop alignment, foot IK, and + accessory correction. +- Ida Faber and future semi-real bodies. + +Risks: + +- More per-body setup. +- Needs performance checks on repeated NPCs. +- Must remain presentation-only. + +Project rule: + +- Evaluate as the next focused presentation lane. +- Add constraints through body-family profiles. +- Do not let rig constraints become combat authority. + +### 6.5 Photon BR200-Style Custom Playables Controller + +Best use: + +- Future high-performance path if animation evaluation becomes a server or + client bottleneck. +- Future tick-accurate path if any mechanic truly depends on exact animation + state at simulation tick. + +Risks: + +- High engineering cost. +- More custom code for AI agents to maintain. +- Reduced compatibility with vendor Animator workflows. + +Project rule: + +- Do not build for alpha. +- Revisit only with measured evidence. + +### 6.6 Animancer Or Small Playables Adapter + +Best use: + +- Possible future option if Animator Controller graph complexity blocks + scalable action authoring. +- Code-driven clip selection can be friendlier to data catalogs and AI agent + editing. +- Photon explicitly lists Animator and Animancer as common render-accurate + animation solutions and notes Animancer can be wrapped for tick-accurate use + because it is Playables-based. + +Risks: + +- New dependency and license surface. +- Requires team/agent familiarity. +- Still needs project-owned semantic action data. + +Project rule: + +- Do not adopt immediately. +- Run a small spike only after the alpha Animator profile layer reveals a real + graph maintenance problem. + +--- + +## 7. Network Authority Model + +Animation is presentation. Authority stays elsewhere. + +| Concern | Owner | +| ---- | ---- | +| Movement position, velocity, interaction range | Fusion server | +| Combat range, facing, hit window, damage, death | Fusion server or Nakama path approved for prototype training | +| Durable body stats, inventory, TIME, SECOND, quest state | Nakama | +| Visual state, local blend, clip selection, IK, prop visibility | Unity animation layer | +| AI or NPC action choice | Agent policy emits intent, server validates | + +Photon's Fusion guidance supports render-accurate animation for most games and +warns not to use animated hierarchy transforms for accurate simulation +calculations. SECOND SPAWN should follow that guidance: never derive server hit +truth from hand, sword, or projectile bones in the Animator hierarchy. + +When a body starts a gameplay action: + +1. Player input or AI emits an allowed semantic intent. +2. Fusion/Nakama validates whether that action can start. +3. A networked action id, counter, or state is advanced. +4. Unity render code observes the validated state and plays presentation. +5. Local animation events may produce VFX, SFX, camera shake, or timing signals. +6. Damage/reward/body/economy mutation occurs only through server validation. + +--- + +## 8. AI Agent Development Requirements + +This architecture is chosen partly because AI agents will do most of the +development. To keep agent work reliable: + +- All gameplay-facing animation requests must be semantic ids. +- All per-body exceptions must live in body/weapon/action profile data. +- Docs must list required actions before code adds a new body family. +- The registry should expose missing-action reports in tests or editor tools. +- No agent should hand-edit a large Animator Controller as the first solution + when a profile mapping can solve the problem. +- Vendor package names should not appear in skill data, backend data, or NPC + policy data. +- Animation smoke tests should use a small matrix: body family, weapon archetype, + dialogue state, one-shot combat action, hit react, death, and recovery. + +Good action request: + +```json +{ + "actor_id": "body:sentinel-0101", + "intent": "attack", + "weapon_archetype": "dual_swords", + "timing_profile_id": "alpha_dual_swords_light_01" +} +``` + +Bad action request: + +```json +{ + "animator_state": "Swordsman-Combo-Attack-Right-02", + "vendor_controller": "Explosive" +} +``` + +--- + +## 9. Alpha Implementation Plan + +### Phase A - Freeze Contract + +- Treat `CharacterActionId` and `VisualAnimationIntent` as the semantic + contract. +- Add or update docs when a new action id is introduced. +- Keep skill data `animation_intent` semantic. + +### Phase B - Data-Driven Profiles + +- Move body-family, weapon, and action timing mappings toward ScriptableObject + assets or structured content files. +- Add validation that each playable body supports required alpha actions. +- Add missing-action reports for candidate bodies. + +### Phase C - Presentation Spikes + +- Run a locked Unity lane for Animation Rigging. +- Test Ida Faber look-at, hand IK, two-hand grip, foot IK, and finger policy. +- Test Explosive prototype bodies for full alpha action coverage. + +### Phase D - Vendor Controller Evaluation + +- Evaluate Opsive only after the current Fusion controller baseline is stable. +- The spike must prove semantic intent input, Fusion authority, AI compatibility, + body swap, and weapon swap. +- Reject or sandbox Opsive if gameplay rules become hidden in vendor ability + graphs. + +### Phase E - Future Playables Or Animancer Spike + +- Revisit only if Animator Controller profile maintenance becomes too brittle, + or if measured performance/tick-accuracy needs justify a lower-level system. + +--- + +## 10. Backlog Candidates + +| Priority | Task | Output | +| ---- | ---- | ---- | +| P0 | Convert current prototype animation registry into explicit body, weapon, and timing profile assets or structured catalogs. Track in [#278](https://github.com/DOS/Second-Spawn/issues/278). | Agent-editable data and validation tests. | +| P0 | Add animation compatibility smoke matrix. | Test or editor report for body x weapon x action coverage. | +| P1 | Run Unity Animation Rigging spike for Ida Faber and semi-real bodies. | Evidence screenshots/video, console result, performance notes. | +| P1 | Add semantic missing-action UI/debug output. | Faster agent triage when a body cannot perform an action. | +| P2 | Opsive UCC authority spike. | Keep/adapt/reject recommendation before deeper import. | +| P2 | Animancer/Playables spike. | Only if Animator graph complexity becomes a real blocker. | + +--- + +## 11. References + +- [Unity Manual: Retarget Humanoid animations](https://docs.unity3d.com/6000.1/Documentation/Manual/Retargeting.html) +- [Unity Manual: Animator Override Controllers](https://docs.unity.cn/6000.0/Documentation/Manual/AnimatorOverrideController.html) +- [Unity Animation Rigging package manual](https://docs.unity3d.com/Packages/com.unity.animation.rigging@1.3/manual/index.html) +- [Photon Fusion: Animation concepts and patterns](https://doc.photonengine.com/fusion/current/concepts-and-patterns/animation) +- [Photon Fusion: Animations technical sample](https://doc.photonengine.com/fusion/current/technical-samples/animations) +- [Photon Fusion BR200 Player documentation](https://doc.photonengine.com/fusion/current/game-samples/br200/player) +- [ExplosiveLLC RPG Character Mecanim Animation Pack ReadMe](https://demo.explosive.ws/RPGCharacterMecanimAnimationPackReadMe.pdf) +- [Opsive UCC Abilities documentation](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/) +- [Opsive UCC Animator Controller documentation](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) +- [Opsive UCC Animator Motion documentation](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/animator-motion/)