Skip to content

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.

Migration Summary

Current Project Architecture Summary

The Unity project is a 2D arena survival game with one or two players, character-specific weapons/abilities, timed enemy waves, special/miniboss/boss events, level-up and chest upgrades, permanent shop progression, achievements, Steam/leaderboard integration, and save-backed unlocks.

Planning precedence: this Unity-analysis summary describes the current Unity project. For current Godot implementation decisions, use docs/migration/godot-architecture-plan.md first and docs/migration/system-redesign-analysis.md second. If this Unity evidence conflicts with those planning docs, the planning docs are the source of truth.

The codebase mixes:

  • old singleton-heavy gameplay code,
  • large monolithic behavior scripts,
  • ScriptableObjects used as both static data and runtime state,
  • newer partial refactors such as GameStateService, PlayerManager, RewardRoller, GameDataLoader, AudioService, and SaveService.

Main Systems

Second-pass Unity mapping details are now split into focused audit docs:

  • 13_unity_data_asset_mapping.md
  • 14_unity_ability_behavior_catalog.md
  • 15_unity_upgrade_effect_catalog.md
  • 16_unity_character_weapon_catalog.md
  • 17_unity_stage_spawn_mapping.md
  • 18_unity_prefab_and_pool_usage_map.md
  • 19_unity_event_and_runtime_state_map.md
  • 20_unity_freeze_bug_investigation_notes.md
System Current Main Scripts Migration Direction
Boot/session AppInitiator, GameSession, GameDataLoader Keep concept, rebuild as boot autoloads/resources.
Run loop GameManager, GameInitialization, GameStateService, Timer Split into run/state/stage/reward/game-over controllers.
Player Player, PlayerModifier, PlayerWeapon, PlayerCollectItem Split into movement, stats, health, weapon, collection, targeting.
Ability AbilityHolder, AbilityFunction, Ability, PlayerAttack Full redesign with ability data + runtime state + behavior scripts.
Upgrade/reward RewardRoller, UpgradeSelection, UpgradeFunction, UpgradeEvoFunction Redesign effects and separate roll logic from UI.
Enemies/spawn SpawnerEventManager, SpawnerData, Enemy, enemy states Keep concept, split data/runtime state and enemy components.
Save/progression SaveManager, SaveService, Save, GameDataCount, AchievementManager, ShopManager Keep data model/ids, redesign as explicit services.
UI MenuController, app views, StatusPanel, GameEndManager, reward UI Rebuild in Godot with signals and view models.
Audio/feedback AudioService, AudioResources, DamagePopUp, Announcer Keep behavior, centralize in audio/feedback services.

Biggest Spaghetti-Code Risks

  1. AbilityHolder contains too many unrelated abilities and runtime states.
  2. GameManager mixes run state, UI, reward, progression, save, and leaderboard responsibilities.
  3. UpgradeFunction hardcodes all upgrade effects in one switch.
  4. Player.TakeDamage, PlayerWeapon.AttackModify, and PlayerAttack.OnTriggerEnter2D contain many ability-specific branches.
  5. Runtime state is stored on ScriptableObjects.
  6. Hot paths still use global singletons and occasional scene-wide searches.

Systems That Should Be Redesigned

  • Ability system.
  • Upgrade effect system.
  • GameManager/run controller.
  • Player damage pipeline.
  • Projectile/attack modifier system.
  • Spawn runtime state handling.
  • Save/resource unlock authority.
  • Reward UI/controller boundary.

Systems That Can Be Migrated Conceptually With Minimal Changes

  • GameStateService as RunState.
  • PlayerManager XP/level event concept, after removing direct ability side effects.
  • Timer concepts.
  • SpawnerData schedule data, after removing runtime flags.
  • Character, LevelData, ShopUpgrade, Achievement as Godot resources.
  • AudioService categories and anti-stacking behavior.
  • GameEvents as a Godot signal/event bus concept.

Systems That Need Manual Confirmation

  • Which abilities/upgrades are production, test, in development, or deprecated.
  • Exact Unity .dat save and .json config schema for later migration into encrypted JSON.
  • Exact old shop save value calculation for soul point refund.
  • Exact Steam/leaderboard implementation details after the core gameplay loop is stable.
  • Exact fullscreen startup freeze reproduction path, if the Unity issue still needs debugging.
  • Whether tutorial should be ported or rebuilt.
  • Exact reward-state pause behavior and how it differs from pause-menu state.

Recommended high-level run scene:

RunScene
- RunState
- GameSession
- StageController
- SpawnDirector
- PlayerManager
- RewardDirector
- ScoreManager
- GameOverController
- UIFlowController
- FeedbackController

Recommended ability architecture:

AbilityResource
AbilityRuntimeState
AbilityRegistry
AbilityRunner
AbilityBehavior scripts/scenes
UpgradeEffect resources
AttackEffect resources

Recommended data rule:

Resources are static definitions.
Runtime state lives in runtime objects.
Save state is authoritative for progression.
  1. Freeze ids and data schema: characters, abilities, upgrades, stages, achievements, and old shop save ids for soul point refund conversion.
  2. Build Godot resource models and import a small curated subset of data, starting with Soldier / Alex, regular Stage 1, and Stage 1 enemies.
  3. Implement run shell: GameSession, RunState, timers, score, and player spawning through the new player-slot path.
  4. Implement player movement, target sensor, basic weapon/projectile, enemy health/death.
  5. Implement Stage 1 spawn schedules and Stage 1 enemy behavior composition.
  6. Implement XP/level-up reward flow with basic stat upgrades.
  7. Implement ability architecture with a small set of abilities first: Dash, Soldier / Alex character ability, one passive, one projectile modifier.
  8. Add Stage 1 boss behavior, special/boss rewards, and evolution conditions if the slice targets the full Stage 1 loop.
  9. Add save/progression boundaries and later Unity save conversion; do not migrate the old shop UI/system as-is, and refund old shop save values into soul points.
  10. Add game-over summary.
  11. Add full UI polish, audio/feedback, leaderboard/Steam after core gameplay is stable.
  12. Port remaining abilities in batches, with tests/checklists per ability.

Final Notes

The current Unity behavior is recoverable, but the Godot version should be a behavioral rebuild, not a script translation. The safest path is to preserve ids, formulas, timings, and player-facing effects while replacing the large holders/managers with small data-driven runners and explicit signals.