AIC-Project/docs/superpowers/plans/2026-08-10-fighter3d-common-actor-presentation.md

Fighter3D Common Actor Presentation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace Fighter3D's private battle-stage actor presentation with the shared character loading, movement, and actor behavior presentation pipeline while keeping Fighter3D-specific behavior configs.

Architecture: Add a reusable mini-game actor presentation runner in the main Unity assembly. Fighter3D.Client feeds authoritative snapshots into that runner, which loads player character prefabs from CharacterConfig.json, moves common actor instances, and triggers common BehaviorWorld/ActorBehaviorPresentation events from Fighter3D-specific configs.

Tech Stack: Unity 2022.3.62f3, UGUI/TMP, XResLoader, CharacterConfigData, ActorBehaviorConfigLoader, BehaviorWorld, ActorBehaviorPresentation, Unity Pipeline tests.

Global Constraints

• Do not hand-edit Unity serialized assets or .meta; use Unity Pipeline for prefab/material/asset operations.
• Keep Fighter3D combat logic server authoritative; client presentation only consumes snapshots.
• Fighter3D skill config must live under Assets/MiniGames/Fighter3D/res/Config/ActorBehavior.
• Publish a new Fighter3D version after verification so clients download the new resource/code bundles.

---

Task 1: Regression Tests

Files:

• Modify: Client/Assets/Script/Tests/EditMode/GameLobbyControllerLayoutTests.cs

Interfaces:

• Consumes: current FighterGameClient.cs source and Unity AssetDatabase.

• Produces: tests requiring MiniGameActorPresentation, Fighter3D-specific config paths, and removal of private stage prefab loading.

• Step 1: Write failing tests

Add tests asserting FighterGameClient.cs contains MiniGameActorPresentation, does not contain Fighter3D_BattleStage.prefab, and that fighter3d_skill.json, fighter3d_flyobj.json, fighter3d_buff.json exist.

• Step 2: Run tests to verify failure

Run: unity command run_tests --project-path "D:\UD\AI\AIC#Project\Client" --mode editor --filter GameLobbyControllerLayoutTests.Fighter3D --filter_type testName Expected: FAIL before implementation because the old stage path remains and config files are missing.

Task 2: Shared Mini-Game Actor Presentation

Files:

• Create: Client/Assets/Script/xmain/MiniGame/MiniGameActorPresentation.cs
• Modify: Client/Assets/Script/xmain/ActorBehavior/ActorBehaviorConfigLoader.cs

Interfaces:

• Produces: XGame.MiniGame.MiniGameActorPresentation, with Render(FighterStateLike input) represented by public SetFighterSnapshot overloads from Fighter3D.Client.

• Produces: ActorBehaviorConfigLoader.LoadCatalogFromRoot(string type, string configRoot, Action<BehaviorConfigCatalog>).

• Step 1: Implement minimal shared runner

Create a runner that loads character prefabs by figure, tracks actor transforms, lerps movement, registers actors with ActorBehaviorPresentation, loads behavior config from a supplied root, and can trigger light/heavy behavior IDs when actions enter attack states.

• Step 2: Run tests

Run the Fighter3D tests and fix compilation issues.

Task 3: Fighter3D Integration And Config

Files:

• Modify: Client/Assets/MiniGames/Fighter3D/scripts~/Client/FighterGameClient.cs
• Modify: Client/HotUpdateGames/Fighter3D.Client/Fighter3D.Client.csproj
• Create: Client/Assets/MiniGames/Fighter3D/res/Config/ActorBehavior/fighter3d_skill.json
• Create: Client/Assets/MiniGames/Fighter3D/res/Config/ActorBehavior/fighter3d_flyobj.json
• Create: Client/Assets/MiniGames/Fighter3D/res/Config/ActorBehavior/fighter3d_buff.json

Interfaces:

• Consumes: MiniGameActorPresentation.

• Produces: Fighter3D client using shared presentation, not private stage actor transforms.

• Step 1: Replace FighterStage with MiniGameActorPresentation

Instantiate the shared runner on enter, call it from snapshot/update, destroy it on exit, and map light/heavy actions to Fighter3D behavior IDs.

• Step 2: Add Fighter3D behavior config

Provide mini-game-specific behavior config that can drive common animation/effect presentation without changing main Assets/Game/Config/ActorBehavior/fighter_*.

Task 4: Verify And Publish

Files:

• Output: CDN/minigame/fighter3d/<next>/pc/*
• Output: deploy/minigame/fighter3d/<next>/*

Interfaces:

• Consumes: all previous tasks.

• Produces: new published Fighter3D package.

• Step 1: Verify

Run Unity EditMode tests, dotnet build for client/server, and Fighter3D server tests.

• Step 2: Publish

Run %TEMP%\PublishFighter3D.cs with Unity Pipeline and inspect the generated manifest/assets.