From dabd056e8b9a799ac6ea920c387bf9231128f4ef Mon Sep 17 00:00:00 2001 From: voffka81 <84612470+voffka81@users.noreply.github.com> Date: Sun, 7 Jun 2026 18:27:25 +0300 Subject: [PATCH] Create Architecture Migration Plan for Gnome's Bounty Add an architecture migration plan for the Gnome's Bounty Unity project, detailing the purpose, goals, current context, constraints, architecture issues, high-level migration phases, and a detailed task backlog for the coding model. --- Assets/Docs/ArchitectureMigration.md | 681 +++++++++++++++++++++++++++ 1 file changed, 681 insertions(+) create mode 100644 Assets/Docs/ArchitectureMigration.md diff --git a/Assets/Docs/ArchitectureMigration.md b/Assets/Docs/ArchitectureMigration.md new file mode 100644 index 0000000..370e82f --- /dev/null +++ b/Assets/Docs/ArchitectureMigration.md @@ -0,0 +1,681 @@ +# Gnome’s Bounty — Architecture Migration Plan for Coding Model + +## 1. Purpose + +This document is written for a coding model / AI coding agent that will work on the current Unity project for **Gnome’s Bounty**. + +The purpose is to guide the model through a **safe, incremental architecture migration** based on the **current project structure**, not an idealized rewrite. + +The agent should use this file as an execution plan. + +--- + +## 2. Main Goal + +Refactor and extend the current Unity project so it better matches the intended game concept: + +- 2D puzzle-platformer +- player uses a **throwing hammer** +- hammer can **stun enemies** and **break certain walls** +- player opens chests, finds a key, and exits through a door +- enemies should create pressure over time +- enemy AI should eventually react to **noise** +- the project structure should become cleaner without requiring a full rewrite + +The goal is **not** to rebuild the game from scratch. +The goal is to **improve the current project safely**. + +--- + +## 3. Current Project Context + +The current Unity project already contains the following relevant files and systems: + +- `PlayerController.cs` +- `Hammer.cs` +- `HammerThrower.cs` +- `EnemyAI.cs` +- `CharacterSpawner.cs` +- `BreakableWall.cs` +- `Chest.cs` +- `KeyChest.cs` +- `Door.cs` +- `DoorInteract.cs` +- `InputManager.cs` +- `UiManager.cs` +- `Character.cs` +- `CameraFollow.cs` +- `TreasureSO.cs` +- `MapElementSO.cs` + +The project also includes folders and assets related to: + +- controllers +- environment objects +- managers +- map elements +- scriptable objects +- prefabs +- scenes +- animations +- sprites + +This means the project already has a prototype-level gameplay foundation. + +--- + +## 4. Important Constraints for the Coding Model + +### 4.1 General Rules +- Do **not** rewrite unrelated systems. +- Do **not** perform a full architecture rewrite. +- Prefer **small, safe, incremental changes**. +- Keep the project **Unity-friendly** and inspector-friendly. +- Preserve existing gameplay where possible. +- Keep naming consistent and readable. +- Avoid unnecessary abstractions. +- Use simple `MonoBehaviour` patterns unless something more advanced is clearly required. + +### 4.2 Refactoring Rules +- If renaming files/classes, clearly list all renamed files. +- If Unity references may break because of renaming or moving scripts, explicitly mention required Unity setup steps. +- If a class is currently too generic, improve it gradually instead of replacing it immediately. +- Prefer **adding missing gameplay systems** over rewriting existing ones. +- If a task is risky, choose the safest implementation that preserves compatibility. + +### 4.3 Output Rules +For each task, the coding model must return: +1. A short summary of what was changed +2. A list of files changed +3. Full code for every **new file** +4. Full code for every **modified file** +5. Unity setup instructions (if required) +6. Notes about assumptions, risks, or possible scene/prefab reference issues + +--- + +## 5. Architecture Issues to Solve + +The current project already aligns with the concept in several areas, but the following architectural gaps should be addressed: + +1. `UiManager.cs` should be normalized to `UIManager.cs` +2. `HammerThrower.cs` and `Hammer.cs` should have clearly separated responsibilities +3. There is no explicit `GameManager.cs` +4. There is no explicit `LevelManager.cs` +5. There is no dedicated `NoiseSystem.cs` +6. `EnemyAI.cs` is likely too generic and should gradually support enemy states +7. Hammer gameplay should clearly support: + - cooldown + - projectile behavior + - stun + - destructible wall interaction + - self-destruction on impact +8. The chest → key → door → exit loop should be centralized and explicit + +--- + +## 6. High-Level Migration Phases + +--- + +## Phase 1 — Safe Cleanup and Structural Preparation + +### Objective +Improve naming and separate responsibilities without changing game behavior too much. + +### Tasks +1. Rename `UiManager.cs` to `UIManager.cs` +2. Review `Hammer.cs` and `HammerThrower.cs` +3. Ensure: + - `HammerThrower` handles throw input, direction, cooldown, and projectile spawn + - `Hammer` handles projectile movement, collision detection, stun, breakable wall interaction, and self-destruction +4. Review `EnemyAI.cs` +5. Do **not** deeply refactor `EnemyAI` yet +6. Keep all current gameplay working + +### Expected Result +- cleaner naming +- clearer hammer responsibilities +- no major gameplay breakage + +### Acceptance Criteria +- project compiles +- hammer still works +- no scene references are silently broken + +--- + +## Phase 2 — Add Core Gameplay Managers + +### Objective +Introduce missing orchestration for game state and level progression. + +### Tasks +1. Create `GameManager.cs` +2. Create `LevelManager.cs` +3. `GameManager` should manage: + - whether the player has the key + - treasure count + - simple level complete action + - future extensibility for restart, game over, or scene transition +4. `LevelManager` should manage: + - key collection flow + - door unlock flow + - level completion request when player reaches exit +5. Integrate current `Door`, `DoorInteract`, `Chest`, and `KeyChest` systems with these managers + +### Expected Result +The gameplay loop becomes explicit: + +1. open chest +2. get key +3. unlock door +4. reach exit +5. complete level + +### Acceptance Criteria +- when the player gets the key, game state updates correctly +- door unlocking is controlled through level logic +- reaching exit with the key triggers level completion logic +- project compiles without removing current gameplay + +--- + +## Phase 3 — Implement Noise System + +### Objective +Add one of the missing core mechanics from the design: **enemy reaction to noise**. + +### Tasks +1. Create `NoiseSystem.cs` +2. Add a public API such as: + - `Emit(Vector3 position, float radius)` +3. Update `BreakableWall.cs` so breaking a wall emits noise +4. Update `Hammer.cs` so impact can emit noise +5. Update `EnemyAI.cs` so it can respond to noise events via a method such as: + - `OnNoise(Vector3 sourcePosition)` +6. Keep the implementation simple and compatible with the current project + +### Expected Result +Enemy behavior becomes influenced by player actions. + +### Acceptance Criteria +- breaking a wall emits noise +- hammer impact emits noise +- nearby enemies are notified +- enemies change behavior when hearing noise +- exposed tuning fields are available in Inspector where useful + +--- + +## Phase 4 — Improve EnemyAI with States + +### Objective +Make enemy behavior clearer, more predictable, and closer to the intended troll-like pressure behavior. + +### Tasks +1. Update `EnemyAI.cs` to support a simple internal state model +2. Add states such as: + - `Patrol` + - `Investigate` + - `Chase` + - `Stunned` +3. Add logic for: + - reacting to noise + - changing target position when investigating + - entering a stunned state when hit by the hammer + - recovering from stun after a delay +4. Keep implementation simple +5. Do **not** create an overcomplicated AI framework + +### Expected Result +Enemies behave in a controlled and readable way. + +### Acceptance Criteria +- enemy can be stunned +- enemy can recover from stun +- enemy can investigate noise +- enemy can still chase or patrol if such behavior already exists +- code is maintainable and understandable + +--- + +## Phase 5 — Finalize Hammer Gameplay Logic + +### Objective +Make the hammer fully aligned with the intended design. + +### Tasks +1. Update `HammerThrower.cs` to include: + - cooldown + - throw permission checks + - projectile spawning +2. Update `Hammer.cs` to include: + - collision with breakable walls + - collision with `EnemyAI` + - self-destruction on impact + - optional impact noise emission +3. Ensure the hammer: + - does not kill enemies + - can stun enemies + - can break only destructible walls + - disappears on impact + - becomes available again after cooldown + +### Expected Result +The hammer becomes a proper tactical tool rather than a generic projectile. + +### Acceptance Criteria +- hammer cannot be spammed without cooldown +- hammer breaks only valid destructible objects +- hammer stuns enemies +- hammer disappears on impact +- gameplay remains responsive + +--- + +## Phase 6 — Integrate Chest → Key → Door Loop Properly + +### Objective +Make the main level progression loop robust and explicit. + +### Tasks +1. Review `Chest.cs` and `KeyChest.cs` +2. Ensure `KeyChest.cs` informs `GameManager` and/or `LevelManager` when key is collected +3. Update `Door.cs` so it clearly supports locked/unlocked state +4. Update `DoorInteract.cs` so player interaction is separate from progression logic +5. Ensure door completion checks are performed through `GameManager` and/or `LevelManager` + +### Expected Result +The core objective loop becomes stable: + +- open chest +- obtain key +- unlock or enable exit +- reach exit +- complete level + +### Acceptance Criteria +- opening key chest grants key +- door unlocks only when appropriate +- player can finish level through door flow +- project compiles and current gameplay remains functional + +--- + +## Phase 7 — Optional Folder and Naming Cleanup + +### Objective +Improve long-term maintainability without breaking the current project. + +### Tasks +1. Consider moving scripts into clearer folders, for example: + - `HammerThrower.cs` → player-related folder + - `Hammer.cs` → projectile or combat-related folder + - `EnemyAI.cs` → enemy-related folder + - `BreakableWall.cs` → environment or world-related folder +2. Rename `CharacterSpawner.cs` to `EnemySpawner.cs` **only if** it is truly enemy-specific +3. Do not move or rename files unless the required Unity follow-up steps are clearly documented + +### Expected Result +The project structure becomes easier to understand and extend. + +### Acceptance Criteria +- structure becomes clearer +- moved scripts still work in Unity +- all renames/moves are documented + +--- + +## 7. Detailed Task Backlog for the Coding Model + +Each task below should preferably be executed in a separate interaction or small batch. + +--- + +## Task 1 — Normalize UI Manager Naming + +### Instruction +Rename `UiManager.cs` to `UIManager.cs` and update the class name accordingly. +Check for all references in the project and update them if necessary. +Do not change any unrelated logic unless required for compilation. + +### Deliverables +- renamed file +- updated class name +- note about scene/prefab references if Unity reattachment is required + +### Definition of Done +- project compiles +- no broken references remain undocumented + +--- + +## Task 2 — Separate Hammer Throw Logic and Hammer Projectile Logic + +### Instruction +Review `HammerThrower.cs` and `Hammer.cs`. + +Refactor them so: +- `HammerThrower` manages player input integration, throw direction, throw permission checks, cooldown, and projectile spawn +- `Hammer` manages projectile movement, collision detection, stun application, destructible wall interaction, optional noise emission, and self-destruction on impact + +Do not remove existing functionality unless replacing it with equivalent or better behavior. + +### Deliverables +- full updated `HammerThrower.cs` +- full updated `Hammer.cs` +- short explanation of each class responsibility + +### Definition of Done +- hammer still throws correctly +- responsibilities are clearly separated + +--- + +## Task 3 — Add GameManager + +### Instruction +Create a new `GameManager.cs` MonoBehaviour singleton. + +It should manage: +- whether the player has the key +- treasure count +- a basic level completion action +- future-friendly structure for restart or scene transition + +Keep implementation simple and compatible with the current project. + +### Deliverables +- new `GameManager.cs` +- explanation of where to place it in the scene +- any required setup steps + +### Definition of Done +- other systems can check key ownership via `GameManager` +- treasure is tracked centrally + +--- + +## Task 4 — Add LevelManager + +### Instruction +Create a new `LevelManager.cs` MonoBehaviour. + +It should manage: +- response to key collection +- door unlock flow +- level completion request when the player reaches exit + +Integrate it with `Door.cs`, `DoorInteract.cs`, `Chest.cs`, and/or `KeyChest.cs` as needed. + +### Deliverables +- new `LevelManager.cs` +- updated related files if required +- integration notes + +### Definition of Done +- level progression logic is centralized +- door flow is no longer spread across unrelated classes + +--- + +## Task 5 — Add Noise System + +### Instruction +Create a simple `NoiseSystem.cs` singleton for noise events in the world. + +Requirements: +- expose a public method to emit noise using world position and radius +- detect nearby enemies +- notify them through a method like `OnNoise(Vector3 sourcePosition)` + +Integrate the system with: +- `Hammer.cs` +- `BreakableWall.cs` +- `EnemyAI.cs` + +### Deliverables +- new `NoiseSystem.cs` +- updated `Hammer.cs` +- updated `BreakableWall.cs` +- updated `EnemyAI.cs` with a basic noise reaction entry point + +### Definition of Done +- gameplay events can emit noise +- nearby enemies can react to that noise + +--- + +## Task 6 — Add Enemy States to EnemyAI + +### Instruction +Refactor `EnemyAI.cs` to support a simple internal state system. + +Required states: +- `Patrol` +- `Investigate` +- `Chase` +- `Stunned` + +Required behaviors: +- change target or focus when hearing a noise +- enter stunned state when hit by hammer +- recover from stun after delay + +Do not overengineer. + +### Deliverables +- full updated `EnemyAI.cs` +- brief explanation of state transitions + +### Definition of Done +- enemies respond to noise +- enemies can be stunned and recover +- code stays readable + +--- + +## Task 7 — Add Hammer Cooldown and Tactical Rules + +### Instruction +Update hammer gameplay to fully support the intended tactical role. + +Requirements: +- player cannot throw continuously without cooldown +- hammer disappears on impact +- hammer stuns enemies but does not kill them +- hammer breaks only destructible walls +- hammer impact may emit noise +- all tunable values should be inspector-friendly where appropriate + +### Deliverables +- updated `HammerThrower.cs` +- updated `Hammer.cs` +- notes about tuning values exposed in Inspector + +### Definition of Done +- hammer behavior matches design +- gameplay is tunable without code changes + +--- + +## Task 8 — Integrate KeyChest with Game State + +### Instruction +Update `KeyChest.cs` so that opening it informs `GameManager` and/or `LevelManager` that the key has been collected. + +This must trigger: +- key ownership update +- door unlock flow or unlock eligibility + +Do not break the existing chest interaction flow. + +### Deliverables +- updated `KeyChest.cs` +- updated `Chest.cs` if needed +- scene setup notes if references are required + +### Definition of Done +- opening the key chest updates game state correctly + +--- + +## Task 9 — Improve Door Flow + +### Instruction +Refactor `Door.cs` and `DoorInteract.cs` so that: +- `Door` owns locked/unlocked state +- `DoorInteract` handles player interaction only +- final completion checks are performed through `GameManager` and/or `LevelManager` + +### Deliverables +- updated `Door.cs` +- updated `DoorInteract.cs` +- explanation of class responsibilities + +### Definition of Done +- door lock state is explicit +- player interaction is separated from progression logic + +--- + +## Task 10 — Optional Folder Cleanup Plan + +### Instruction +Propose and optionally apply a safer folder structure cleanup for the current scripts. + +Suggested direction: +- player-related scripts in a player or controllers folder +- enemy scripts in an enemies folder +- hammer/projectile scripts in a combat or projectiles folder +- managers in a managers folder +- environment/world scripts in an environment or world folder + +Do not move files blindly. +If there is risk to Unity references, provide a move plan instead of applying changes immediately. + +### Deliverables +- either actual safe file moves +- or a documented migration plan for folder cleanup + +### Definition of Done +- the structure becomes clearer or a safe future move plan is documented + +--- + +## 8. Recommended Execution Order + +The coding model should process the tasks in the following order: + +1. Task 1 — Normalize UI manager naming +2. Task 2 — Separate hammer throw logic and projectile logic +3. Task 3 — Add `GameManager` +4. Task 4 — Add `LevelManager` +5. Task 8 — Integrate `KeyChest` with game state +6. Task 9 — Improve door flow +7. Task 5 — Add `NoiseSystem` +8. Task 6 — Add enemy states to `EnemyAI` +9. Task 7 — Finalize hammer cooldown and tactical rules +10. Task 10 — Optional folder cleanup + +This order is intentionally incremental and low risk. + +--- + +## 9. Prompt Template for the Coding Model + +Use the following prompt template when sending a single task to a coding model: + +```text +You are working on an existing Unity 2D project called Gnome’s Bounty. + +Important constraints: +- Do not rewrite the entire architecture. +- Make only focused, safe, incremental changes. +- Keep existing gameplay working if possible. +- Return full code for every changed file. +- Return full code for every new file. +- Clearly list renamed files and any Unity Inspector setup steps. +- Prefer simple MonoBehaviour-based design over overengineering. + +Current project context: +- The player uses a throwing hammer. +- The hammer can stun enemies and break certain walls. +- The level loop is chest -> key -> door -> exit. +- Enemies should later react to noise. +- Existing files include PlayerController, Hammer, HammerThrower, EnemyAI, BreakableWall, Chest, KeyChest, Door, DoorInteract, InputManager, UiManager, CharacterSpawner. + +Task: +[INSERT ONE TASK FROM THIS DOCUMENT] + +Expected output: +1. Summary of changes +2. List of files changed +3. Full code for each new file +4. Full code for each updated file +5. Unity setup instructions +6. Notes about any risks or assumptions +``` + +--- + +## 10. Recommended AI Session Breakdown + +To reduce risk, do **not** ask the coding model to execute the whole migration in one response. + +Preferred breakdown: + +### Session 1 +- Task 1 +- Task 2 + +### Session 2 +- Task 3 +- Task 4 +- Task 8 +- Task 9 + +### Session 3 +- Task 5 +- Task 6 +- Task 7 + +### Session 4 +- Task 10 + +This keeps refactoring controlled and easier to review. + +--- + +## 11. Final Guidance for the Coding Model + +When performing these tasks, always prefer: + +- compatibility over elegance +- safe migration over aggressive refactor +- explicit inspector setup over hidden assumptions +- readable MonoBehaviour code over advanced patterns + +The project already has a working prototype base. +The purpose of this plan is to evolve it into a cleaner architecture that matches the game concept more closely. + +Do not replace the existing project with a theoretical “perfect architecture”. +Improve the real project incrementally. + +--- + +## 12. Desired End State + +After completing the migration, the project should have: + +- clean hammer throw + projectile separation +- a central `GameManager` +- a central `LevelManager` +- a simple but functional `NoiseSystem` +- enemies that can react to noise and become stunned +- a stable chest → key → door → exit flow +- clearer responsibilities between gameplay systems +- a cleaner and more maintainable Unity architecture + +This is the target state for the current project.