Archived on 2026-10-24. The Godot rewrite is cancelled. Migration decisions and work checklists below are withdrawn. Original claims, code examples, file paths, and completion statements have not all been revalidated. Use the current documentation and issue register for maintenance decisions.

Godot Implementation Task Plan

This is the execution checklist for rebuilding Tiny Chaos in Godot 4. It is based on docs/migration/godot-architecture-plan.md and docs/migration/system-redesign-analysis.md.

Use this document as the phase-by-phase task boundary. Do not implement multiple phases at once unless this document is deliberately updated first.

Current Implementation Rules

• Migrate behavior, not Unity C# code.
• Use pure typed GDScript.
• Keep scripts small and focused.
• Do not create a giant GameManager.
• Do not create a giant AbilityHolder.
• Do not put ability-specific logic inside AbilityRunner.
• Do not hardcode all upgrades in one script.
• Do not duplicate one full gameplay scene per stage.
• Do not let UI directly own core gameplay decisions.
• Do not copy the Unity folder tree wholesale.
• Do not create the Godot project inside the Unity repo unless this is deliberately overridden later.
• Treat the Unity project as reference/archive only until a curated Godot-ready asset pack is created.
• Use localization keys for UI text introduced during implementation.
• Use exact Unity numbers for the first Soldier / Alex and Stage 1 implementation pass.
• Keep PC local co-op first, while avoiding choices that block 1-4 local players or mobile controls later.
• When real Unity assets/data are needed, stop Godot implementation and create a Unity-project extraction prompt instead of guessing or bulk-importing.
• Asset packs are requested from the Unity project, then copied into the separate Godot project after they are shaped to the Godot architecture.

Unity Asset Handoff Rules

Use this flow when implementation reaches a real asset/data need:

1. The Godot project defines the exact scene/resource/data format first.
2. The Godot project creates a precise prompt for the Unity project.
3. The Unity project extracts only the requested production assets/data into a Godot-ready pack.
4. The Godot project imports or copies that pack and validates it.
5. Development continues in Godot until the next asset handoff is needed.

Do not ask the Unity project for a full content dump before the Godot formats are stable.

Phase 1: Project Foundation

Description: Create the clean Godot project foundation in a separate Godot project, target folders, project rules, and minimal boot/session boundaries. No gameplay logic yet.

Task List: - [ ] Create or confirm the separate Godot 4 project root and project.godot outside the Unity repo. - [ ] Create the target res://autoload, res://scenes, res://scripts, res://data, res://art, res://audio, and res://vfx folder tree from the architecture plan. - [ ] Add folder README notes for resource/data ownership rules where useful. - [ ] Configure project naming and typed GDScript conventions. - [ ] Create minimal GameSession autoload for selected stage, difficulty, player slots, and run setup data only. - [ ] Create minimal SceneLoader autoload for boot/menu/game scene transitions only. - [ ] Create placeholder boot or main scene entry that does not contain gameplay logic. - [ ] Add localization-key convention for any UI text created after this phase. - [ ] Add a short implementation status note that Phase 1 contains no gameplay.

Done Gate: - Godot project opens. - Target folder structure exists. - Minimal autoload decision exists. - No gameplay combat, ability, enemy, upgrade, save, shop, Steam, or leaderboard logic exists.

Not Included: - Player movement. - Combat. - Stage spawning. - Ability runtime. - Save migration.

Phase 2: Core Entity And Damage Path

Description: Create the shared entity and combat foundation that both player and enemy systems will use.

Task List: - [ ] Create EntityCore for shared damage intake, death state, status hook points, and feedback signals. - [ ] Create HealthComponent for current health, max health, damage application, healing, and death signal only. - [ ] Create DamageData as the shared damage payload with amount, source, owner player id, tags, crit fields, knockback fields, and effect metadata placeholders. - [ ] Create HitboxComponent for outgoing damage/contact areas. - [ ] Create HurtboxComponent for receiving hitbox events and forwarding DamageData to HealthComponent. - [ ] Create a temporary test player body that can emit one damage hitbox. - [ ] Create a temporary test enemy body that can receive damage and die. - [ ] Validate player-to-enemy damage through hitbox, hurtbox, damage data, and health. - [ ] Add debug-only visual or log feedback for hit, damage, and death events.

Done Gate: - A test player can damage a test enemy. - Enemy death is emitted through the shared entity path. - Player and enemy use the same base damage pipeline where practical. - No ability-specific, upgrade-specific, or boss-specific logic exists in the damage foundation.

Not Included: - Real Soldier / Alex weapon behavior. - Stage 1 enemy content. - XP drops. - UI polish.

Phase 3: Player Creation And Local Input

Description: Build the player-slot system correctly before implementing full player gameplay.

Task List: - [ ] Create PlayerSlot data with player id, character id, input profile id, UI slot id, and active state. - [ ] Create PlayerManager that owns active slots, spawned player registry, and active_players access. - [ ] Create PlayerSpawner that creates player scenes from CharacterData and PlayerInputProfile. - [ ] Create PlayerInputProfile resources or data definitions for keyboard_wasd, keyboard_arrows, and gamepad-ready routing. - [ ] Create input action names for movement, dash, confirm, cancel, pause, and future ability actions. - [ ] Route player input through input profiles instead of hardcoded player objects. - [ ] Spawn one player from slot data. - [ ] Validate a second local player slot can be assigned without duplicating player-manager logic. - [ ] Keep mobile input as a future profile path without designing final touch controls.

Done Gate: - One player can spawn from slot data. - WASD and arrow-key profiles exist. - Gamepad-ready routing exists even if full controller testing is later. - No gameplay system assumes fixed player[0] and player[1] as the complete world.

Not Included: - Full 3-4 player UI. - Online multiplayer. - Final mobile control layout.

Phase 4: Soldier / Alex Player Slice

Description: Implement the first real playable character using Soldier / Alex as the balance reference.

Task List: - [ ] Create CharacterData for Soldier / Alex using exact Unity id, base stats, movement values, stamina values, range, and starting ability reference. - [ ] Create PlayerEntity as the player scene root that coordinates movement, stats, entity core, weapon, ability runner, collection, and targeting children. - [ ] Create PlayerStats with base stats, runtime modifiers, and recalculation boundaries. - [ ] Implement player movement using the assigned PlayerInputProfile. - [ ] Implement dash with Soldier / Alex stamina cost, dash speed, and dash duration values. - [ ] Connect PlayerEntity to EntityCore and HealthComponent. - [ ] Add basic player feedback signals for hit, death, dash, and stat changes. - [ ] Validate one Soldier / Alex instance spawns and moves through the player manager path.

Done Gate: - Soldier / Alex spawns through PlayerManager and PlayerSpawner. - Movement and dash use exact Unity reference values. - Player stats are data-driven and not hardcoded in the player scene script. - Player gameplay is not coupled directly to UI pages.

Not Included: - All characters. - Character progression. - Full weapon evolution.

Phase 5: Basic Weapon And Projectile

Description: Create the first weapon/projectile path before adding broad abilities or upgrades.

Task List: - [ ] Create ProjectileBase.tscn with movement, lifetime, hitbox, owner context, and cleanup behavior. - [ ] Create projectile data for the first Soldier / Alex weapon shot using exact Unity reference values where known. - [ ] Create a player weapon controller that fires through data and owner context. - [ ] Connect projectile hitbox output to the shared damage pipeline. - [ ] Add target or aim behavior needed for the first Soldier / Alex weapon pass. - [ ] Add projectile pooling or a simple spawn path with a clear later pooling boundary. - [ ] Validate projectile damage, lifetime, cleanup, and owner attribution.

Done Gate: - Soldier / Alex can fire one basic weapon/projectile. - Projectile damage uses DamageData, HitboxComponent, HurtboxComponent, and HealthComponent. - No ability-specific projectile modifiers are hardcoded into the weapon controller.

Not Included: - All weapon modifiers. - All projectile types. - Companion/summon attacks.

Phase 6: Stage 1 Enemy State Composition

Description: Create the enemy scene composition model and migrate the first Stage 1 enemy behavior style.

Task List: - [ ] Create EnemyData for the first Stage 1 enemy using exact Unity stats, reward values, and ids where available. - [ ] Create EnemyEntity as the enemy scene root with EntityCore, stats, targeting, state machine, and reward-drop hook points. - [ ] Create EnemyStats for base stats and runtime modifiers. - [ ] Create EnemyStateMachine that owns state entry, update, exit, and transition flow. - [ ] Create reusable enemy state nodes for idle, chase, and contact/attack behavior. - [ ] Create the first Stage 1 enemy scene by composing reusable states under the enemy scene. - [ ] Connect enemy death to reward/drop hooks without implementing full XP flow yet. - [ ] Validate enemy movement, targeting, damage intake, death, and scene cleanup.

Done Gate: - At least one Stage 1 enemy is built through scene/state composition. - Enemy behavior is not implemented as one script per enemy. - Enemy stats are data-driven. - Enemy death uses the shared entity path.

Not Included: - All Stage 1 enemies. - Boss behavior. - Complex ranged/summon/mortar states.

Phase 7: Stage 1 Spawn Flow

Description: Create the reusable gameplay scene and Stage 1 spawn director.

Task List: - [ ] Create GameScene.tscn as the reusable run scene. - [ ] Create StageData for Stage 1 with id, display key, duration, music key placeholder, background placeholder, boss reference placeholder, and spawn schedule reference. - [ ] Create SpawnScheduleData for the first Stage 1 wave subset using exact Unity timings where confirmed. - [ ] Create StageController that loads Stage 1 data, starts timer, and owns stage state. - [ ] Create SpawnDirector that reads immutable spawn schedule data and stores runtime spawn state outside resources. - [ ] Spawn Stage 1 enemy scenes from schedule data. - [ ] Track active enemies without scene-wide searches. - [ ] Validate stage timer, wave spawn timing, enemy cleanup, and no runtime mutation of data resources.

Done Gate: - GameScene.tscn can run Stage 1 data. - Stage timer runs. - Stage 1 enemy waves spawn from schedule data. - Runtime spawn flags do not live in StageData or SpawnScheduleData.

Not Included: - All Stage 1 waves beyond the selected first-slice subset. - Stage 2+. - Boss transition.

Phase 8: XP, Reward Pause, And One Upgrade

Description: Implement the first progression loop inside a run: enemy death, XP pickup, level-up reward, and one upgrade effect.

Task List: - [ ] Create ItemDrop.tscn for XP pickup with owner-neutral collection behavior. - [ ] Create player collection area or collector component for XP pickup. - [ ] Create LevelUpController for XP thresholds, current level, and level-up event. - [ ] Create RewardDirector that owns reward queue, reward state requests, and selected reward application. - [ ] Create RunState reward-state handling separate from pause-menu handling. - [ ] Create minimal Page_LevelUp.tscn that displays localization-key-backed reward text. - [ ] Create one UpgradeData for a basic stat upgrade using exact Unity value. - [ ] Create one UpgradeEffect that applies the stat upgrade without a giant switch. - [ ] Validate reward selection pauses stage progression but keeps reward UI, animations, and feedback responsive. - [ ] Validate reward selection cannot conflict with pause-menu state.

Done Gate: - Enemy drops XP. - Player collects XP and levels up. - Reward UI shows one or more choices. - Selected upgrade applies through UpgradeEffect. - Reward pause and pause menu are separate enough to avoid the old soft-lock class.

Not Included: - Full reward pool. - Chests. - Boss rewards. - Weapon evolution. - Shop progression.

Phase 9: Ability Runner And Soldier Ability

Description: Create the ability runtime structure and implement one Soldier / Alex ability without recreating AbilityHolder.

Task List: - [ ] Create AbilityData with id, display key, icon reference placeholder, cooldown, stamina cost, trigger type, base stats, and scaling placeholders. - [ ] Create AbilityRegistry for looking up available ability data by id. - [ ] Create AbilityInstance for owner, level, cooldown, stacks, runtime state, and modified stats. - [ ] Create AbilityRunner for active ability instances, cooldown ticking, trigger routing, and activation requests. - [ ] Create one Soldier / Alex AbilityBehavior for the first ability behavior pass. - [ ] Connect ability activation to player, weapon, or dash events as required by the Soldier / Alex behavior. - [ ] Keep ability-specific logic out of AbilityRunner. - [ ] Add minimal cooldown/debug HUD signal output. - [ ] Validate cooldown, trigger, activation, and cleanup behavior.

Done Gate: - Soldier / Alex has one working ability through AbilityRunner. - Cooldown state lives in AbilityInstance, not AbilityData. - Adding another ability would not require editing a giant holder script.

Not Included: - All abilities. - Full ability UI. - Ability evolutions. - Character-specific progression.

Phase 10: Stage 1 Boss As Enemy Variant

Description: Validate that bosses remain enemy-derived behavior with encounter presentation handled outside boss attack logic.

Task List: - [ ] Create BossData for the Stage 1 boss using exact Unity id, health, stats, reward, and display key where available. - [ ] Create BossBase.tscn as an EnemyEntity variant with boss tag/data. - [ ] Create reusable boss state or mechanic nodes for the Stage 1 boss movement/attack behavior. - [ ] Create BossEncounterController for boss start, boss end, boss HUD signal, music hook placeholder, and stage-flow notification. - [ ] Trigger Stage 1 boss from StageController or SpawnDirector without hardcoding boss logic into the stage script. - [ ] Show minimal boss health bar through UI signal routing. - [ ] Trigger post-boss or bonus-stage hook placeholder if required by current Stage 1 flow. - [ ] Validate boss death, boss reward hook, health bar cleanup, and return to stage/game-over flow.

Done Gate: - Stage 1 boss behaves as an enemy specialization. - Boss attack/movement logic lives in boss state/mechanic nodes. - Boss UI/camera/audio/transition flow lives outside the boss behavior script.

Not Included: - All bosses. - Full cinematic transitions. - Full bonus-stage implementation unless required to complete Stage 1 validation.

Phase 11: HUD, Pause, Game Over, And Feedback

Description: Add the minimal UI and feedback required to play, pause, understand, and finish the first slice.

Task List: - [ ] Create UIFlowController for page routing and UI state requests. - [ ] Create Page_GameHUD.tscn for health, XP, level, timer, and ability cooldown display. - [ ] Create pause menu flow that requests pause through RunState. - [ ] Create Page_GameOver.tscn with run result summary fields needed for the slice. - [ ] Create minimal damage popup or hit feedback route with caps. - [ ] Create minimal audio routing placeholders for music, SFX, and feedback buses. - [ ] Ensure UI observes gameplay state through signals or explicit adapters. - [ ] Validate HUD updates for player health, XP, level, timer, reward, pause, boss, and game over.

Done Gate: - First slice is playable from run start to game over. - UI does not directly apply upgrade effects or own gameplay decisions. - Pause menu does not conflict with reward pause. - Feedback is capped enough to avoid obvious runaway spawning.

Not Included: - Full menu UI. - Full UI polish. - Collection screens. - Achievement UI. - Leaderboard UI.

Asset Handoff Checkpoint A: First Playable Test Pack

Description: Stop and request a small Unity extraction pack once the Godot project has proven the first playable slice structure and needs real production assets/data for a more accurate test.

Trigger: - Use this checkpoint after the core player, enemy, stage, weapon/projectile, XP/reward, ability, boss, and minimal HUD paths are structurally working with placeholders or tiny samples.

Task List: - [ ] List the exact Godot scenes/resources that now need real Unity assets or data. - [ ] List only the first-test content needed: Soldier / Alex, regular Stage 1, selected Stage 1 enemies, Stage 1 boss if included, one weapon/projectile path, one XP pickup, one ability, one upgrade, minimal UI/audio/localization assets. - [ ] Confirm the Godot target paths and resource fields are already defined before asking Unity to extract anything. - [ ] Create a Unity-project prompt that requests only this first playable test pack. - [ ] Require the Unity extraction output to include migration_manifest.md and import_notes.md. - [ ] Require exclusions for Unity .meta, .prefab, .unity, .cs, .controller, .anim, .mat, URP, plugins, TextMesh Pro, and non-production test/dev assets. - [ ] Pause broad content migration until this first pack is imported and validated in Godot.

Done Gate: - The Unity-project extraction prompt is specific enough that the Unity chat does not need to guess. - The requested pack is limited to first playable test content. - Godot implementation can resume after the pack is copied/imported.

Not Included: - All characters. - All abilities. - All upgrades. - All stages. - Full save migration. - Full production asset migration.

Phase 12: Content Expansion Prep

Description: Prepare the project to migrate more content safely after the Stage 1 slice proves the architecture and Godot resource/scene formats.

Task List: - [ ] Create content triage list for production, testing, in-development, need-revamp, and deprecated assets. - [ ] Freeze authoritative ids for characters, abilities, upgrades, enemies, stages, achievements, and old shop save values. - [ ] Create import/mapping checklist for Unity assets that are actually needed. - [ ] Define the copy-pasteable TinyChaos_GodotAssetPack layout with art, audio, vfx, data, localization, legacy_save_aliases, migration_manifest.md, and import_notes.md. - [ ] Create the Unity-project prompt for the broader curated Godot asset migration pack after the Godot formats are stable. - [ ] Import/copy the broader curated Godot asset migration pack only after it is produced by the Unity project. - [ ] Exclude Unity .meta, .prefab, .unity, .cs, .controller, .anim, .mat, URP, plugin, and TextMesh Pro files from active Godot content. - [ ] Keep Assets/Scriptable Object content out of production migration unless manually promoted. - [ ] Add additional Stage 1 enemies through the existing enemy state composition pattern. - [ ] Add additional upgrades through UpgradeData and UpgradeEffect. - [ ] Add additional abilities through AbilityData, AbilityInstance, AbilityRunner, and separate AbilityBehavior. - [ ] Add content validation checklist for exact Unity numbers and behavior comparisons. - [ ] Document every intentionally skipped Unity asset or behavior.

Done Gate: - New content can be added without changing core managers. - Content ids are stable enough for future save migration. - Test/in-development assets are not accidentally imported as production. - The asset pack can be copied into the separate Godot project without bringing Unity folder noise.

Not Included: - Full save migration. - Shop replacement design. - Steam/leaderboard.

Asset Handoff Checkpoint B: Full Production Asset Pack

Description: Stop and request the broader Unity extraction pack once gameplay systems are stable enough to receive production content without reshaping the pack repeatedly.

Trigger: - Use this checkpoint after Phase 12 defines stable content schemas, target folders, id rules, and import validation.

Task List: - [ ] List every stable Godot target folder and resource type that can receive production content. - [ ] List the production Unity sources to extract: regular Stage 1, Stage 2, Stage 3, production characters, production abilities/upgrades from Assets/Resources, production enemies/bosses, localization CSVs, required art/audio/vfx, and old save alias data. - [ ] Exclude Stage 1 new, Stage 3 ZhangYG, experimental content, testing assets, in-development assets, need-revamp assets, and old shop UI/system content unless manually promoted. - [ ] Request old shop save data only for soul point refund calculation. - [ ] Request stable ids and source-to-target mapping in migration_manifest.md. - [ ] Request unresolved behavior notes in import_notes.md instead of guessing. - [ ] Import/copy the full pack into Godot only after the manifest is reviewed.

Done Gate: - Full production asset migration prompt is ready for the Unity project. - The prompt follows the Godot architecture instead of Unity folder names. - Broad content migration can proceed without bulk-copying the Unity Assets folder.

Not Included: - Recreating Unity prefabs directly. - Reintroducing Unity ScriptableObject runtime state. - Old shop UI/system. - Platform-specific Steam/Stove/PlayStore integration.

Phase 13: Save Migration Planning

Description: Plan and then implement save/progression only after ids and first-slice behavior are stable.

Task List: - [ ] Audit current Unity .dat player data shape. - [ ] Audit current Unity .json config shape. - [ ] Identify saved fields that use ids, asset names, localized names, or manually typed strings. - [ ] Define Godot encrypted JSON save schema. - [ ] Define id mapping for characters, stages, abilities, upgrades, achievements, currencies, and old shop values. - [ ] Define old shop conversion rule as soul point refund only. - [ ] Create SaveManager boundary that does not call platform APIs directly. - [ ] Create migration test fixtures from representative Unity saves. - [ ] Validate migrated save data loads without mutating static Resources.

Done Gate: - Legacy save fields are mapped. - Godot encrypted JSON target schema is defined. - Old shop values refund to soul points only. - Save/progression authority is separate from static Resources.

Not Included: - Steam cloud. - Leaderboards. - Final character-specific progression UI unless separately planned.

Phase 14: Platform, Mobile, And Long-Tail Systems

Description: Add platform and long-tail systems only after the core gameplay loop, content ids, and save boundary are stable.

Task List: - [ ] Define platform adapter boundary for Steam, leaderboard, achievements, and future mobile services. - [ ] Add Steam integration only if PC launch scope requires it. - [ ] Add leaderboard service after score/run summary fields are stable. - [ ] Add achievement service after progression ids are stable. - [ ] Define final mobile control layout after PC local input is proven. - [ ] Add mobile-specific platform services only behind adapters. - [ ] Add tutorial only after final gameplay systems are stable. - [ ] Add full localization polish after UI flow is stable.

Done Gate: - Platform code does not leak into core gameplay systems. - PC and mobile platform needs are separated. - No platform feature blocks the core run loop.

Not Included: - Rewriting completed core gameplay systems to satisfy platform code. - Recreating Unity-specific fullscreen startup behavior.