Gnome-s-Bounty/Assets/Docs/ArchitectureMigration.md

# 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.