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.

Unity Stage And Spawn Mapping

Purpose

Map current stage assets, difficulty maps, spawner data, boss references, game durations, creep waves, special waves, and boss transitions.

Current migration decision: Stage 1 is the first Godot gameplay target. Stage 1 enemy content should be migrated before other stages, using exact Unity numbers and behavior. Use the regular Stage 1, Stage 2, and Stage 3 sources; do not use Stage 1 new or Stage 3 ZhangYG unless they are manually promoted later.

Stage Asset Map

Stage Asset	Stage Name	Availability	Boss / Music	Difficulty Maps
Assets/Resources/Stage/Stage_1.asset	Meadow	isAvailable: 1	boss guid e9bb8d8dda983e24da8f057fea2afa5a; music guid 09ecc48ee2584ee41b17c556d1560e81	1_EASY 300s unlocked, 1_MEDIUM 720s unlocked, 1_HARD 720s unlocked, 1_INSANE 900s unlocked, 1_CHAOS 900s locked
Assets/Resources/Stage/Stage_2.asset	Crystal Mine	isAvailable: 1	boss guid e757716d454d5e1468e42e5ce2026ea6; music guid 57bd8e4f6282e6c49aef37e0b88dfdef	2_EASY 300s unlocked, 2_MEDIUM 720s unlocked, 2_HARD 720s unlocked, 2_INSANE 900s locked, 2_CHAOS 900s locked
Assets/Resources/Stage/Stage_3.asset	Snowdrift Vale	isAvailable: 1	boss guid dd7d841e7766011459c4321eae3b048f; music guid 382be39207b737b49b94a0a6227ce399	3_EASY 300s locked, 3_MEDIUM 720s locked, 3_HARD 720s locked, 3_INSANE 900s locked, 3_CHAOS 900s locked
Assets/Resources/Stage/Stage_4.asset	Crimson Desolate	isAvailable: 0	none assigned	4_EASY, 4_MEDIUM, 4_HARD; all locked and using placeholder spawner reference
Assets/Resources/Stage/Stage_5.asset	Drake Mountain	isAvailable: 0	Unknown / needs manual confirmation	5_EASY, 5_MEDIUM, 5_HARD; all locked and using placeholder spawner reference
Assets/Scriptable Object/Stage/Experimental.asset	Experimental	isAvailable: 0	Unknown / needs manual confirmation	EX_EASY through EX_CHAOS, all unlocked and 999999999 seconds

Spawner Asset Groups

Group	Location	Contents / Naming
Stage 1 original	Assets/Scriptable Object/Spawner/Stage 1	Production migration source. 1-Creep-1-Easy through 1-Creep-5-Chaos; 1-SP-1-Easy through 1-SP-5-Chaos
Stage 1 new	Assets/Scriptable Object/Spawner/Stage 1 new	Do not use for production migration unless manually promoted later. Newer creep assets such as 1-Creep-2-Normal Other, 1-Creep-3-Hard, 1-Creep-4-Insane, 1-Creep-5-Chaos; special-wave pairing remains reference-only.
Stage 2	Assets/Scriptable Object/Spawner/Stage 2	2-Creep-1-Easy through 2-Creep-5-Chaos; 2-SP-1-Easy through 2-SP-5-Chaos
Stage 3	Assets/Scriptable Object/Spawner/Stage 3	Production migration source. 3-Creep-1-Easy through 3-Creep-5-Chaos; 3-SP-1-Easy through 3-SP-5-Chaos
Stage 3 ZhangYG	Assets/Scriptable Object/Spawner/Stage 3 ZhangYG	Do not use for production migration unless manually promoted later. Alternate Stage 3 creep assets named 3-Creep-1-Easy ZYG through 3-Creep-5-Chaos ZYG.
Experimental	Assets/Scriptable Object/Spawner/EX-Creep-1.asset, EX-SP-1.asset	experimental long-duration stage spawners

SpawnEvent Data Fields

Field	Meaning In Current Unity
timeSpawn	Start time for this wave/event window.
maxTimeToSpawn	End time for this wave/event window.
enemy	Enemy prefab reference.
spawnRate	Delay/rate value used by SpawnerEventManager spawn coroutine.
direction flags	Which side/direction the enemy can spawn from. Exact field names are in SpawnerData.SpawnEvent.
isSpawning	Runtime flag used to prevent duplicate spawn coroutine starts. Serialized into assets.
isActive	Runtime flag used by special/miniboss logic. Serialized into assets.

Runtime Flow

1. GameSession stores the selected LevelData and difficulty.
2. GameManager and GameInitialization prepare the run.
3. SpawnerEventManager receives the selected StageMap creep and special SpawnerData.
4. Every Update, SpawnerEventManager runs creep spawn checks, special spawn checks, and miniboss timer logic.
5. Creep waves spawn while the run timer is inside the SpawnEvent time window, the battle state is Battle, and isMiniBossSpawn is false.
6. Special waves spawn while inside the special event window and battle state is Battle.
7. If the special enemy type is Miniboss, SpawnerEventManager announces the miniboss, sets isMiniBossSpawn = true, and sets minibossFightTimer = 60f.
8. While isMiniBossSpawn is true, creep spawning is suppressed.
9. MiniBossDeath clears the miniboss state only if the death id matches the active special spawn's enemy kill id.
10. If the spawned event enemy type is Boss, SpawnerEventManager changes battle state to BossFight, switches music, and later spawns the stage boss.

Boss Transition Flow

Step	Current Unity Behavior
Enter boss fight	SpawnerEventManager.SpawnEnemy detects an enemy of type Boss and sets battle state to BossFight instead of spawning it as a normal wave.
Pre-boss cleanup	SpawnBoss stops timers, locks camera, resets creep flags, and makes existing enemies flee.
Spawn effect	Boss spawn effect is pooled before boss spawn.
Boss spawn	Boss prefab from LevelData.boss is pooled at the boss spawn position.
UI/audio	Boss health bar and boss music are activated.
Stage continuation	ChangeStage restarts timers, resets creep flags, returns battle state to Battle, hides health bar, and unlocks camera.

Runtime Fields Mixed Into SpawnerData

Runtime Field	Evidence	Risk
SpawnEvent.isSpawning	Field exists on SpawnEvent; inspected assets show some saved as isSpawning: 1.	A wave can begin the run already marked as spawning if play-mode state was serialized.
SpawnEvent.isActive	Field exists on SpawnEvent; inspected assets show some saved as isActive: 1.	Special/miniboss matching may use stale active state.
isMiniBossSpawn	Runtime field in SpawnerEventManager.	Suppresses creep waves for up to 60 seconds if death/clear event is missed.
minibossFightTimer	Set to 60 seconds for miniboss events.	Can look like the reported one-minute stuck state when only creep spawning is paused.

Problems / Risks

• Spawn schedule data and per-run flags are mixed in SpawnerData.
• Stage 4 and Stage 5 use placeholder spawner references and are unavailable.
• Stage 3 has both normal and ZhangYG spawner variants; use regular Stage 3 for migration, not Stage 3 ZhangYG.
• Special/miniboss clear depends on death id matching active special spawn data.
• Boss transition does heavy state work, camera changes, enemy cleanup, pooled effects, music changes, and UI changes in one flow.

Open Questions

• Are isSpawning and isActive values currently dirty because of play mode serialization?
• Which enemy prefabs correspond to each spawner GUID? This should be resolved in Unity editor or by GUID map.
• Unknown / needs manual confirmation.