# Animation Scene — Editor Tooling

This document tracks **Editor-only tooling** used with the runtime animation test workflow described in **`AnimationSceneSetup.md`**.

**Scene docs (runtime hierarchy, managers, APIs):** see `Assets/PerfectWorld/Scripts/_Doc/AnimationSceneSetup.md`.

**How to extend this file:** whenever you add or plan a new piece of Editor UI / automation for the animation scene, append a **`### Feature`** block under **[Feature log](#feature-log)** using the **[Feature template](#feature-template)** below. Keep one feature per numbered section so history stays searchable.

---

## Goals

| Goal | Notes |
|---|---|
| Faster iteration | Load and validate character models **from Play Mode**, driven by Editor menus where appropriate — **no Edit Mode `.ecm` preview** without a dedicated preview pipeline |
| Stable bootstrap | Respect the same prerequisites as runtime (`NPCManager`, `elementdataman`, `CECPlayer.InitStaticRes()`, etc.—see §Prerequisites below) |
| Traceability | Features and acceptance criteria live here **before or while** implementing the Editor scripts |

Suggested implementation locations (when you create them):

- Menu: e.g. `Tools / PerfectWorld / Animation Scene / …`
- Scripts: under `Assets/PerfectWorld/Scripts/Editor/` (or project convention for Editor assemblies)

---

## Prerequisites (runtime + Editor)

Anything the Editor tool drives must satisfy the same constraints as a Play Mode session:

| Prerequisite | Why |
|---|---|
| `AutoInitializer` in the open scene | Bootstraps `IAutoInitialize` types including **`ElementDataManProvider`**; runs **`EC_Game.Init()`**, **`SkillStubs.Init()`** |
| **`elementdataman` loaded** | **`CECPlayer.InitStaticRes()`** → **`BuildActionList()`** uses **`ElementDataManProvider.GetElementDataMan()`** |
| **`CECPlayer.InitStaticRes()`** called once **after** element data is usable | **`InitializePlayer`** does **not** register **`IAutoInitialize`** (interface commented); **not** invoked by **`CECGameRun.Init()`** alone. Normal login hits it via **`CECGameRun.InitCharacter`**. Animation scene tooling must arrange this explicitly if you rely on skill / action maps |
| `NPCManager` in scene | **`SetPlayerModel`** → **`NPCManager.Instance.GetModelPlayer(profession, gender)`** |
| `CECAttacksMan` in scene | **`PlayAttackEffect`**, **`SkillGfxMan.InstanceSub.Tick`** path (see **`AnimationSceneSetup.md` §12**) |
| `EC_ManMessageMono` in scene | **`SkillGfxMan`** resolves **`EC_ManMessageMono.Instance`** references |
| `CECHostPlayer` reference (selection or serialized) | **`await player.SetPlayerModel(byte profession, byte gender)`** is **`CECPlayer`** API; host implementation is **`CECHostPlayer`** |
| **`InGameGraphicOption`** in scene *(optional)* | **`EC_Game.InitSetting()`** adjusts render scale / MSAA via **`InGameGraphicOption`**. If omitted, **`MonoSingleton`** auto-creates a host component; **`InGameGraphicOption`** resolves URP from **`GraphicsSettings.defaultRenderPipeline`**. Fully custom scenes should still assign URP (+ optional Cinemachine) on **`InGameGraphicOption`** for predictable behavior.

**Editor caveat:** **`CECHostPlayer.LoadResources`** uses **`UnityGameSession.Instance.GetRoleInfo()`**. For offline Editor-driven loads, prefer calling **`SetPlayerModel`** directly (and/or setting **`m_iProfession`**, **`m_iGender`** on the player instance as your tool requires) rather than invoking full **`InitCharacter`** unless session is mocked.

---

## Feature log

### Feature 1 — Editor / Play Mode: bootstrap player model

**Status:** Planned (spec captured here; implementation optional).

**Problem:** In the animation test scene you need a repeatable way to load the `.ecm` player model **by profession and gender** without going through the server login flow.

**Proposed behavior:**

1. User opens the animation test scene (or any scene that contains the required managers + a **`CECHostPlayer`** instance).
2. **Play Mode required** for real **`SetPlayerModel`** / Addressables — Editor UI only **queues** work once Unity is playing (same constraint as Feature 2–3).
3. Tool or scene **`MonoBehaviour`** exposes **`Profession`** / **`Gender`** mapped to **`CECPlayer.SetPlayerModel(byte, byte)`**.
4. Sequence (recommended): wait until **`elementdataman`** load has succeeded → **`CECPlayer.InitStaticRes()`** once → **`await SetPlayerModel(profession, gender)`**.
5. Success: visible `.ecm` under **`Player`** per **`parentModel`** rules (**`CECPlayer.SetPlayerModel`** — first child if present, else root); Console filter **`AnimSceneBootstrap`** shows **`SetPlayerModel` BEGIN/END** when those logs exist.

**Out of scope:** Full **`InitCharacter`** / **`UnityGameSession`** parity unless explicitly mocked elsewhere.

**Acceptance criteria:**

- Model appears after bootstrap when **`NPCManager`**, Addressables, and element data are healthy.
- Failures are visible (**`NPCManager`** null, **`GetModelPlayer`** null, **`InvalidOperationException`** from **`SetPlayerModel`**).
- **`InitStaticRes`** either runs before skill/action-dependent tests or is intentionally skipped with a clear warning.

**Primary APIs:** **`CECPlayer.SetPlayerModel`**, **`CECPlayer.InitStaticRes`** — see **`AnimationSceneSetup.md`** §1, §10–11.

---

### Feature 2 — Editor: trigger Play Action (animation probe)

**Status:** Planned.

**Problem:** Quickly verify **`CECPlayerActionController` / Animancer** wiring without hunting hotkeys or server-driven triggers.

**Proposed behavior:**

1. Menu entry e.g. **`Tools / PerfectWorld / Animation Scene / …`** opens a small **EditorWindow** (or equivalent).
2. Window active **only in Play Mode**; references **`CECHostPlayer`** (object field or auto-find).
3. User enters **`PLAYER_ACTION_TYPE`** index (same **`int`** as **`CECPlayer.PlayAction(int iAction, bool bRestart)`** — **`ACT_STAND = 0`**, etc.; see **`CECPlayer`** enum).
4. Button **Play action** invokes **`host.PlayAction(index, true)`** on the live instance.

**Out of scope:** Driving **`PlaySkillCastAction`** / **`PlayAttackEffect`** from this panel (those belong to combat/skill tooling or separate Feature entries).

**Acceptance criteria:**

- With model loaded and action maps built (**`InitStaticRes`**), **`ACT_STAND`** / **`ACT_RUN`**-class actions behave like runtime calls.
- **`ACT_ATTACK_1..4`** may still refuse **`PlayAction`** by design (**`CECPlayer.PlayActionWithConfig`** blocks normal melee slots — use documented skill APIs instead).

**Primary API:** **`CECPlayer.PlayAction(int iAction, bool bRestart)`** on **`CECHostPlayer`**.

---

### Feature 3 — Offline host init: god stats + synthetic skills (below character level 80, human form)

**Status:** Planned.

**Problem:** **`OnMsgHstSkillData`** never runs offline, so **`m_aPtSkills`** / **`SkillWrapper`** stay empty — **`GetNormalSkill`** / cast checks cannot mirror a real character. You still want **most** combat skills usable for VFX/animation testing **without** shape-change prerequisites.

**Design summary:** After **`InitStaticRes`** and **`SetPlayerModel`**, synthesize a **`cmd_skill_data`-equivalent** payload in memory and apply the **same conceptual pipeline** as **`CECHostPlayer.OnMsgHstSkillData`**: **`ElementSkill.LoadSkillData`** → **`SkillWrapper.Instance.LoadData`** → instantiate **`CECSkill`** rows into **`m_aPtSkills`** / **`m_aPsSkills`** by skill **type** (positive vs passive/production/life). Optionally align **`m_iProfession` / `m_iGender`** with the loaded model before filtering.

**Simulated character limits:**

| Constraint | Intent |
|---|---|
| Player level ceiling **below 80** | Treat **maximum simulated level as 79** (or equivalent) when choosing skill **rank**: for each skill id, pick the **highest** rank whose **`SkillStub.GetRequiredLevel(skill)`** is **≤** that simulated level (exact comparison uses live **`Skill`** instance at each candidate rank). |
| Realm | Set **`m_RealmLevel`** (and any extend props you rely on) high enough so **`GetRequiredRealmLevel`** does not fail for included ranks. |
| SP / Mana / AP / Vigour / HP | Raise **`ROLEBASICPROP`** (**`iCurMP`**, **`iCurAP`**, **`iSP`**, **`iVigour`**, **`iCurHP`**, etc.) and matching **`ROLEEXTPROP`** caps (**`max_hp`**, **`max_mp`**, **`max_ap`**) so **`CheckSkillCastCondition`** resource checks succeed for typical casts. |
| **Exclude transform-shape-only skills** | **`ElementSkill.Condition`** tests **`(allow_forms & (1 << form_type))`** where **`form_type`** comes from **`m_iShape`** high bits (**`FORM_MASK_HIGH`**). Base human **`m_iShape = 0`** ⇒ **`form_type = 0`** ⇒ skill must allow **bit 0** in **`SkillStub.allow_forms`**. **Exclude** stubs where **`(allow_forms & 1) == 0`** (human/base form disallowed). Also **exclude** stubs flagged **`restrict_change`** when they denote transformation-only restrictions in data. |
| **Exclude combo-chain prerequisites** | Skip stubs with **`combosk_preskill != 0`** unless you also simulate combo state (**`CECComboSkillState`**). |
| **Exclude item / ammo gated skills** | Skip **`itemcost > 0`** or **`arrowcost > 0`** unless you populate inventory accordingly. |
| **Exclude goblin line** | Skip **`cls == 258`**. |
| **Profession filter** | Include **`stub.cls == playerProfession`** **or** **`cls == 255`** (general skills). |

**Caveats (document in tooltips):**

- **`restrict_weapons`**: skills may still return condition **invalid weapon** if no matching weapon sits in **`m_pEquipPack`** — either equip a dummy weapon per profession or accept skipped casts.
- **`cmd_skill_data.SKILL.id_skill`** is a **`short`** in **`GPDataType`**: skill ids **> 32767** cannot be represented; skip or warn.
- Passive / prerequisite graphs are imperfectly simulated — goal is **animation/VFX iteration**, not authoritative balance.

**Acceptance criteria:**

- **`GetPositiveSkillByID`** / **`GetNormalSkill`** resolve for a large subset of profession skills after injection.
- **`CheckSkillCastCondition`** returns **0** for a sampled skill **without** shape-change, assuming weapon/item caveats addressed.
- Transform-only skills (**`allow_forms`** missing human bit or **`restrict_change`**) do **not** appear in the injected list.

**Primary references:** **`CECHostPlayer.OnMsgHstSkillData`** (**`CECHostPlayer.Skill.cs`**), **`ElementSkill.Condition`**, **`SkillStub.allow_forms`**, **`ROLEBASICPROP`**, **`SkillWrapper`**.

---

### Feature 4 — `AnimScenePlayerBootstrap` inspector: play action + weapon slots (`action_type` index)

**Status:** Done.

**Problem:** Drive **`PlayAction`** and test **weapon-mesh + `action_weapon_suffix`** alignment without a separate EditorWindow; **`GetShowingWeaponType`** ignores attached meshes when **`m_uAttackType == DEFAULT_ACTION_TYPE`**, so animation tests must set **`m_uAttackType`** the same way as **`CECPlayer_Inventory.ShowEquipments`** (from **`WEAPON_SUB_TYPE.action_type`**).

**Implemented behavior:**

1. **`AnimScenePlayerBootstrapEditor`** (Play Mode): **Play action** (`int` + **Restart** → **`CECHostPlayer.PlayAction`**), **Re-apply active weapon slot**.
2. **`AnimScenePlayerBootstrap`**: **`AnimSceneWeaponSlot[15]`** (`rightHandModelPrefab` / `leftHandModelPrefab` per row **`i === action_type`**), **`activeWeaponActionTypeIndex`**, **`applyWeaponAfterModelLoad`**; after **`SetPlayerModel`**, **`ApplyWeaponForActiveSlot()`** runs when enabled.
3. **`CECPlayer.AnimSceneAttachWeaponPrefabs`**: clears **`_currentRightHandWeapon` / `_currentLeftHandWeapon`**, parents instances under **`HH_righthandweapon` / `HH_lefthandweapon`** (same as **`CECPlayer_Inventory.ShowEquipments`**), sets **`m_uAttackType`** when any side attaches; empty slot → **`DEFAULT_ACTION_TYPE`** and **`AttachWeapon()`**.

**Primary API / hooks:** **`CECPlayer.AnimSceneAttachWeaponPrefabs`**, **`AnimScenePlayerBootstrap.ApplyWeaponForActiveSlot`**, **`Assets/PerfectWorld/Scripts/Editor/AnimScenePlayerBootstrapEditor.cs`**

---

### Feature 1 legacy API snippet (reference only)

Use when implementing Feature 1 bootstrap:

```csharp
await player.SetPlayerModel((byte)profession, (byte)gender);
CECPlayer.InitStaticRes();
```

**Related runtime doc sections:** **`AnimationSceneSetup.md`** §1 (model loading), §9–11 (scene objects / init order).

---

### Feature template (copy for Feature 4, 5, …)

Paste and fill whenever you scope a **new** Editor capability:

```
### Feature N — <short title>

**Status:** Planned | In progress | Done

**Problem:** <what pain this removes>

**Proposed behavior:**
1. <step>
2. <step>

**Out of scope:** <explicit non-goals>

**Acceptance criteria:**
- <testable criterion>
- <…>

**Primary API / hooks:** `<class.method or menu path>`

**Related docs / code paths:** `<links to markdown or scripts>`
```

---

## Maintaining this doc

| When | Do |
|---|---|
| You start designing an Editor capability | Add a **`### Feature N`** section with **Status: Planned** and acceptance criteria |
| You implement or change behavior | Update **Status**, **Primary API**, and point to concrete script paths under `Assets/.../Editor/` |
| Behaviour diverges from runtime | Refresh **Prerequisites** and cross-check **`AnimationSceneSetup.md`** |

---

## Play Mode — Bootstrap log tag `[AnimSceneBootstrap]`

Scripts log a shared prefix **`[AnimSceneBootstrap]`** so you can filter the Unity Console while verifying initialization order:

| Typical order | Location |
|---|---|
| Scene `Awake` boot | **`AutoInitializer`**: BEGIN → `IAutoInitialize` count → `EC_Game.Init` → `SkillStubs.Init` → END |
| Element data finished (async after above) | **`ElementDataManProvider`**: SUCCESS or FAILED after `load_data` |
| Attacks/GFX composers | **`CECAttacksMan`**: `Awake` → `Start` → `SetupAttacksMan` → optional GFX preload kick |
| Action/skill tables (when you call it) | **`CECPlayer.InitStaticRes`**: BEGIN / END |

**`SetPlayerModel`** also logs BEGIN / END with the same prefix when loading the player `.ecm`.

**Filter:** Console search **`AnimSceneBootstrap`**.