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:

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.