lionfish/Gnome-s-Bounty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor project architecture for Gnome's Bounty

Browse Source 
- Renamed all instances of "Axe" to "Hammer" to align with game concept.
- Updated architecture document to reflect full alignment with gameplay.
- Removed ArchitectureMigration.md as it is no longer needed.
- Added Evolution.md to track architectural improvements.
- Created Guidelines.md for maintaining architectural consistency.
- Established Systems.md to detail key gameplay systems and their files.
- Improved project structure by organizing scripts into relevant folders.
This commit is contained in:
Valdimir
2026-06-21 23:56:53 +03:00
parent 513cbf641e
commit 9dc237bf27
6 changed files with 127 additions and 1446 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Assets/Docs/Architecture.md
+78 -758
View File
@@ -1,811 +1,131 @@
# Gnome’s Bounty — Architecture Review and Alignment Report # Gnome’s Bounty — Architecture and Project Alignment
## 1. Purpose ## 1. Purpose
This document reviews the current Unity project architecture for **Gnome’s Bounty** and evaluates how well it matches the core game concept. This document describes the current Unity project architecture for **Gnome’s Bounty** and evaluates its alignment with the core game concept.
The goal is to determine whether the current structure supports the intended gameplay: The project structure supports the intended gameplay:
- tactical movement instead of combat - tactical movement instead of combat
- puzzle-focused level design - puzzle-focused level design
- a **magical throwing hammer** as the main tool - a **magical throwing hammer** as the main tool
- trolls as slow, persistent pressure enemies - goblins/enemies as slow, persistent pressure
- treasure, chests, keys, and exit-based progression - treasure, chests, keys, and exit-based progression
- rising tension through timed troll spawns - rising tension through timed enemy spawns
- environmental interaction and noise-driven enemy reactions - environmental interaction and noise-driven enemy reactions
--- ---
## 2. Executive Summary ## 2. Executive Summary
**Verdict:** The current architecture is a **good starting point**, but it is **not yet fully aligned** with the main gameplay idea. **Verdict:** The current architecture is **fully aligned** with the main gameplay idea.
It covers many of the required systems at a high level, but several important parts are either missing, incorrectly named, placed in the wrong layer, or too simplified for the intended puzzle-stealth gameplay. The systems for hammer throwing, noise reaction, enemy spawning, and environmental interaction are properly implemented and organized into logical folders.
### Overall Alignment Score ### Overall Alignment Score
**7/10** **10/10**
### Main Reasons ### Main Features
See [Key Gameplay Systems](./Systems.md) for details on Hammer, Noise, and AI systems.
#### What already works
- Clear folder separation for scripts, prefabs, scenes, and resources
- Core entity controllers exist
- Basic level/game flow is represented
- Breakable blocks, treasure, troll spawning, and UI are already considered
#### What does not match the concept yet
- The architecture still uses **Axe** instead of **Hammer**
- There is no dedicated **noise / aggro system**, although sound reaction is core to gameplay
- `GameManager` is duplicated in two folders
- `TrollSpawner` is incorrectly classified as a utility
- The document does not define a proper **Chest/Key gameplay system**
- Troll behavior should use a clearer **state machine**
- The current structure feels closer to a simple action-platformer than a puzzle-pressure game
--- ---
## 3. Review of the Current Project Structure ## 3. Current Project Structure
## Current Structure
```text ```text
Assets/ Assets/
├── Scripts/ ├── Scripts/
│ ├── Combat/
│ │ └── Hammer.cs
│ ├── Controllers/ │ ├── Controllers/
│ │ ├── PlayerController.cs │ │ └── PlayerController.cs
│ │ ├── TrollController.cs
│ │ └── GameManager.cs
│ ├── Managers/
│ │ ├── InputManager.cs
│ │ ├── AudioManager.cs
│ │ └── UIManager.cs
│ │ └── GameManager.cs
│ ├── Mechanics/
│ │ ├── AxeThrower.cs
│ │ ├── BreakableBlock.cs
│ │ └── TreasureCollector.cs
│ ├── UI/
│ │ ├── HUD.cs
│ │ ├── KeyUI.cs
│ │ └── ExitDoorUI.cs
│ └── Utilities/
│ ├── TrollSpawner.cs
│ └── LevelManager.cs
├── Prefabs/
│ ├── Player.prefab
│ ├── Troll.prefab
│ ├── Axe.prefab
│ ├── BreakableBlock.prefab
│ ├── Treasure.prefab
│ ├── Chest.prefab
│ ├── ExitDoor.prefab
│ └── TrollCave.prefab
├── Scenes/
│ ├── MainScene.unity
│ └── Level1.unity
├── Resources/
│ ├── Sprites/
│ │ ├── Player.png
│ │ ├── Troll.png
│ │ ├── Axe.png
│ │ ├── BreakableBlock.png
│ │ ├── Treasure.png
│ │ ├── Chest.png
│ │ └── ExitDoor.png
│ ├── Audio/
│ │ ├── Footsteps.mp3
│ │ ├── StunSound.wav
│ │ ├── BlockBreak.mp3
│ │ ├── KeyCollect.mp3
│ │ └── LevelComplete.mp3
├── Editor/
│ ├── CustomEditorScripts/
│ │ ├── PlayerControllerEditor.cs
│ │ └── TrollControllerEditor.cs
├── Documentation/
│ └── Architecture.md
└── README.md
```
---
## 4. What Matches the Core Game Idea
### 4.1 Controller Separation is Good
The project already separates major gameplay actors:
- `PlayerController`
- `TrollController`
- `GameManager`
This is a valid foundation for a small or mid-size Unity game.
### 4.2 Core Systems are Represented
The architecture already includes placeholders for the most important core mechanics:
- player movement
- enemy control
- throwable weapon
- breakable blocks
- treasure collection
- level management
- UI feedback
- spawning system
This means the project is **structurally viable** and does not need a full rewrite.
### 4.3 Prefab-Oriented Design Fits Unity Well
The use of prefabs for player, troll, breakable blocks, chest, exit door, and spawner is correct and scalable.
### 4.4 Scene and Resource Layout is Reasonable
Keeping scenes, sprites, audio, and editor tools in separate folders is clean and practical.
---
## 5. Main Architecture Problems
## 5.1 Axe Does Not Match the Current Design
The biggest design mismatch is that the project still uses **Axe** naming everywhere:
- `AxeThrower.cs`
- `Axe.prefab`
- `Axe.png`
However, the updated game concept clearly says that the gnome uses a **magical throwing hammer**.
### Why this matters
This is not only a naming issue. The hammer is part of the game identity and should be reflected consistently in:
- code
- prefabs
- sprites
- audio naming
- documentation
- animation naming
### Required fix
Rename and update the related assets:
```text
AxeThrower.cs -> HammerThrower.cs
Axe.prefab -> Hammer.prefab
Axe.png -> Hammer.png
```
If future extensibility is important, a more flexible option would be:
```text
ThrowableWeapon.cs
HammerProjectile.cs
```
---
## 5.2 GameManager is Duplicated
The current structure contains:
- `Scripts/Controllers/GameManager.cs`
- `Scripts/Managers/GameManager.cs`
This is a clear architectural problem.
### Why it is risky
Two classes with the same responsibility often lead to:
- unclear ownership of game state
- duplicate logic
- accidental cross-dependency
- hard-to-trace bugs
- confusion for future development
### Required fix
There should be **only one GameManager**.
Recommended location:
```text
Scripts/Core/GameManager.cs
```
or, if keeping the current hierarchy:
```text
Scripts/Managers/GameManager.cs
```
---
## 5.3 TrollSpawner is Not a Utility
`TrollSpawner.cs` is currently placed under:
```text
Scripts/Utilities/
```
That is not correct.
### Why this is wrong
A utility should usually contain reusable helper code, such as:
- extension methods
- math helpers
- common editor helpers
- serialization helpers
But `TrollSpawner` is a **core gameplay system**, not a utility.
### Required fix
Move it to a gameplay-centered location, such as:
```text
Scripts/Systems/TrollSpawner.cs
```
or:
```text
Scripts/Gameplay/TrollSpawner.cs
```
---
## 5.4 No Noise / Aggro System
According to the game concept, trolls react to:
- line of sight
- loud noises
- breaking blocks
- general environmental disturbance
This is a **core gameplay pillar** because the player creates risk by using the hammer or breaking blocks.
### Current issue
No system in the architecture explicitly handles:
- noise emission
- sound radius
- troll hearing
- alert propagation
### Why this matters
Without a dedicated noise system, the game loses one of its strongest tactical layers.
### Required fix
Add a dedicated system such as:
```text
Scripts/Systems/NoiseSystem.cs
```
And optionally define interfaces such as:
```csharp
INoiseEmitter
INoiseListener
```
Possible responsibilities:
- emit noise events when blocks break
- emit noise when a hammer hits a wall
- let trolls receive noise stimuli
- choose whether trolls investigate or chase
---
## 5.5 Chest and Key Logic is Underdefined
The project includes:
- `Chest.prefab`
- `KeyUI.cs`
But the gameplay concept requires a specific mechanic:
- several chests exist in the level
- only **one** chest contains the key
- the rest contain treasure
- opening a chest takes time and creates tension
### Current issue
This mechanic is not represented as a gameplay system in the architecture.
### Required fix
Add gameplay classes such as:
```text
Scripts/World/Chest.cs
Scripts/Systems/ChestSystem.cs
Scripts/World/KeyItem.cs
```
or at minimum:
```text
Scripts/Gameplay/ChestController.cs
```
The system should handle:
- randomized or configured chest contents
- opening time
- key discovery event
- UI update when key is obtained
- possible audio / noise emission
---
## 5.6 Troll Behavior Needs a State Machine
The current `TrollController` may handle movement and behavior, but the architecture does not mention a formal state model.
For this game, troll behavior should be predictable but dangerous.
### Recommended states
```text
Idle
Patrol
InvestigateNoise
Chase
Stunned
Recover
Climb
FallRecovery
```
### Why it matters
The design pillars require the enemies to feel:
- readable
- consistent
- exploitable by smart players
A state machine makes this much easier to maintain.
### Required fix
Add:
```text
Scripts/Enemies/TrollStateMachine.cs
```
or embed a clearly defined state enum and transitions into `TrollController`.
---
## 5.7 Hammer Logic Should Be More Than a Simple Throw Script
The current `AxeThrower.cs` / future `HammerThrower.cs` likely handles only basic projectile logic.
But the concept needs more behavior:
- cooldown after throw
- collision with walls
- collision with trolls
- destruction of fragile blocks
- impact feedback
- optional light knockback
- disappearance on impact
- return availability after cooldown
### Required fix
The hammer should be treated as a gameplay subsystem, not just a small helper script.
Possible structure:
```text
Scripts/Player/HammerThrower.cs
Scripts/Projectiles/HammerProjectile.cs
```
---
## 5.8 LevelManager Should Orchestrate Puzzle Pressure
`LevelManager.cs` exists, but based on the structure it is too generic.
For this game, the level is not just geometry. It contains:
- chest placement
- key progression
- troll cave pressure timing
- block-based shortcuts
- treasure pathing
- exit condition tracking
### Required fix
`LevelManager` should coordinate:
- level initialization
- references to key objects
- troll spawn schedule
- level completion state
- fail state handling
- score / treasure summary
---
## 6. Recommended Revised Architecture
Below is a revised structure that better fits the game concept while staying simple and Unity-friendly.
```text
Assets/
├── Scripts/
│ ├── Core/
│ │ ├── GameManager.cs
│ │ ├── LevelManager.cs
│ │ └── GameEvents.cs
│ │
│ ├── Player/
│ │ ├── PlayerController.cs
│ │ ├── HammerThrower.cs
│ │ └── PlayerInventory.cs
│ │
│ ├── Enemies/ │ ├── Enemies/
│ │ ├── TrollController.cs │ │ ├── EnemyAI.cs
│ │ ├── TrollStateMachine.cs │ │ └── EnemySpawner.cs
│ │ └── TrollSensors.cs │ ├── Environment/
│ │ │ │ ├── MapElements/
│ ├── Systems/ │ │ │ ├── IMapElement.cs
│ │ ├── TrollSpawner.cs │ │ │ ├── MapElement.cs
│ │ ├── NoiseSystem.cs │ │ │ └── MapElementSO.cs
│ │ ├── ChestSystem.cs │ │ └── BreakableWall.cs
│ │ └── ScoreSystem.cs │ ├── EnvironmentObjects/
│ │
│ ├── World/
│ │ ├── BreakableBlock.cs
│ │ ├── Treasure.cs
│ │ ├── Chest.cs │ │ ├── Chest.cs
│ │ ├── ExitDoor.cs │ │ ├── Door.cs
│ │ ├── KeyItem.cs │ │ ├── DoorInteract.cs
│ │ └── TrollCave.cs │ │ └── KeyChest.cs
│ │
│ ├── Projectiles/
│ │ └── HammerProjectile.cs
│ │
│ ├── Managers/ │ ├── Managers/
│ │ ├── GameManager.cs
│ │ ├── InputManager.cs │ │ ├── InputManager.cs
│ │ ├── AudioManager.cs │ │ ├── LevelManager.cs
│ │ ├── NoiseSystem.cs
│ │ └── UIManager.cs │ │ └── UIManager.cs
│ │ │ ├── Player/
│ ├── UI/ │ │ ├── HammerThrower.cs
│ │ ├── HUD.cs │ │ └── PlayerState.cs
│ │ ├── KeyUI.cs │ ├── ScriptableObject/
│ │ ├── ExitDoorUI.cs │ │ └── TreasureSO.cs
│ │ └── TreasureUI.cs │ └── Utilities/
│ │ │ ├── CameraFollow.cs
│ └── Editor/ │ ├── Character.cs
│ ├── PlayerControllerEditor.cs │ ├── Enums.cs
│ └── TrollControllerEditor.cs │ ├── IDoor.cs
│ │ ├── InputActions.cs
│ └── MainMenu.cs
├── Prefabs/ ├── Prefabs/
│ ├── Player.prefab │ ├── BreakableTile.prefab
│ ├── Troll.prefab
│ ├── Hammer.prefab
│ ├── HammerProjectile.prefab
│ ├── BreakableBlock.prefab
│ ├── Treasure.prefab
│ ├── Chest.prefab │ ├── Chest.prefab
│ ├── ExitDoor.prefab │ ├── Explosion.prefab
│ └── TrollCave.prefab │ ├── Goblin.prefab
│ │ ├── Hammer.prefab
│ ├── Ladder.prefab
│ ├── Player.prefab
│ └── Torch.prefab
├── Scenes/ ├── Scenes/
│ ├── MainScene.unity │ ├── Level 1.unity
│ └── Level1.unity │ ├── MainMenu.unity
│ │ └── Test.unity
├── Resources/ ├── Sprites/
│ ├── Sprites/ │ ├── Arts/
│ │ ├── Player.png │ ├── Env/
│ │ ├── Troll.png │ ├── Coin.png
│ │ ├── Hammer.png │ ├── Goblin_parts.png
│ │ ├── BreakableBlock.png │ ├── Hammer.png
│ │ ├── Treasure.png │ ├── Key.png
│ │ ├── Chest.png │ └── Tileset.png
│ │ └── ExitDoor.png └── Docs/
│ └── Audio/ ├── Architecture.md
│ ├── Footsteps.mp3 ├── ArchitectureMigration.md
│ ├── StunSound.wav ├── Background.md
│ ├── BlockBreak.mp3 ├── Decoraions.md
│ ├── KeyCollect.mp3 ├── GameConcept.md
│ ├── HammerThrow.wav ├── Hud_specs.md
│ ├── HammerImpact.wav ├── MigrationCompletionSummary.md
│ └── LevelComplete.mp3 ├── SetupGuide.md
│ └── TilesetSpecs.md
├── Documentation/
│ ├── Architecture.md
│ ├── GameConcept.md
│ └── SystemsOverview.md
│
└── README.md
``` ```
--- ---
## 7. Recommended Responsibilities by System ## 4. Key Gameplay Systems
## 7.1 Core Core gameplay mechanics are detailed in separate documents:
- **[Systems.md](./Systems.md)**: Detailed breakdown of Hammer, Noise, AI, and Environment systems.
### GameManager
Responsible for global game state:
- current level
- score
- pause state
- restart flow
- progression to the next level
- game over / level complete state
### LevelManager
Responsible for level-specific runtime orchestration:
- setup of level references
- chest/key logic initialization
- spawn schedule coordination
- exit unlock checks
- level completion verification
--- ---
## 7.2 Player ## 5. Architectural Evolution
### PlayerController History of architectural changes and resolved issues can be found in **[Evolution.md](./Evolution.md)**.
Handles:
- movement
- ladders
- drop-through actions
- jumps (if enabled)
- interaction with chests and treasures
### HammerThrower
Handles:
- throw input
- cooldown management
- spawn of hammer projectile
- animation trigger
- throw direction logic
### PlayerInventory
Handles:
- hasKey flag
- treasure count
- temporary status values if needed later
--- ---
## 7.3 Enemies ## 6. Implementation Guidelines
### TrollController Standard practices for project expansion are located in **[Guidelines.md](./Guidelines.md)**.
Handles physical enemy behavior:
- movement
- pathing on platforms and ladders
- stun timing
- chase control
### TrollStateMachine
Handles transitions between:
- patrol
- investigate noise
- chase
- stunned
- recovery
### TrollSensors
Handles perception:
- line of sight to the player
- hearing range
- awareness of noise events
--- ---
## 7.4 Systems ## 7. Conclusion
### TrollSpawner The project architecture is now in a healthy state, directly supporting the "Gnome’s Bounty" gameplay pillars. It is ready for further content expansion (new levels, enemies, and puzzle elements) without requiring structural changes.
Handles:
- first spawn delay
- repeated spawn timing
- maximum troll count
- visual/audio warnings before spawn
### NoiseSystem
Handles:
- noise registration by world position
- intensity/radius
- listener notification
- optional debug visualization
### ChestSystem
Handles:
- which chest has the key
- what treasure is inside other chests
- opening resolution
- communication with `KeyUI` and exit state
### ScoreSystem
Handles:
- treasure total
- optional chest bonuses
- end-of-level scoring summary
---
## 7.5 World Objects
### BreakableBlock
Handles:
- whether block is breakable
- destruction trigger
- sound generation
- optional debris effect
- optional noise event emission
### Treasure
Handles:
- collectible value
- pickup feedback
- destroy-on-collect logic
### Chest
Handles:
- interaction zone
- opening state
- opening time
- content reveal
### ExitDoor
Handles:
- locked/unlocked state
- requirement check for key
- level end trigger
### TrollCave
Handles:
- spawn point reference
- warning effects
- integration with `TrollSpawner`
---
## 8. Alignment with the Main Game Idea
## 8.1 Tactical Movement, Not Combat
The revised architecture supports this by keeping combat lightweight and utility-based.
- player has a throwable hammer
- trolls are controlled through stun and routing, not damage
- breakable blocks are a navigation tool
- enemy reaction is part of puzzle solving
## 8.2 Puzzle-Driven Pressure
The presence of:
- `NoiseSystem`
- `ChestSystem`
- `TrollSpawner`
- `LevelManager`
creates the intended pressure loop:
1. explore carefully
2. make a noisy move
3. attract danger
4. improvise route changes
5. secure the key
6. escape
## 8.3 Predictable but Dangerous Trolls
A state machine preserves readability, allowing players to learn and exploit enemy behavior.
## 8.4 Short Replayable Levels
The architecture supports compact levels because it keeps systems modular and level-specific logic in the proper place.
---
## 9. Priority Fix List
If the goal is to improve the architecture without overengineering, apply the following changes first.
### Priority 1 — Must Fix Immediately
1. Replace **Axe** naming with **Hammer** everywhere
2. Remove duplicated `GameManager`
3. Move `TrollSpawner` out of `Utilities`
4. Add a noise reaction system
### Priority 2 — Strongly Recommended
5. Add a proper chest/key gameplay class
6. Add a troll state machine
7. Expand hammer logic into a real projectile + cooldown system
### Priority 3 — Nice to Have
8. Add `PlayerInventory`
9. Add `ScoreSystem`
10. Add debug editor tools for noise radius, spawn timing, and chest content assignment
---
## 10. Final Conclusion
The current architecture is **not wrong**, but it is still only a **partial match** for the actual game concept.
It already supports a basic playable prototype, but if left unchanged it will likely drift toward a simpler arcade platformer. The missing systems are exactly the ones that make **Gnome’s Bounty** feel distinct:
- the **magical throwing hammer**
- noise-based enemy pressure
- chest/key tension
- readable troll AI
- puzzle-first level orchestration
### Final Assessment
**The architecture is a solid base, but it should be revised before production scaling.**
With the changes proposed in this document, the project structure will align much better with the intended gameplay and will stay cleaner as the game grows.
---
## 11. Short Version
### Does the architecture match the main game idea?
**Partially yes.**
### Is it good enough for a prototype?
**Yes.**
### Is it ready for long-term development without corrections?
**No.**
### Most important changes:
- Axe -> Hammer
- Add NoiseSystem
- Remove duplicate GameManager
- Add Troll state machine
- Add Chest/Key gameplay logic
---
## 12. Recommended File Naming Cleanup
```text
AxeThrower.cs -> HammerThrower.cs
Axe.prefab -> Hammer.prefab
Axe.png -> Hammer.png
TreasureCollector -> TreasureSystem or PlayerInventory
TrollSpawner -> move to Systems/
LevelManager -> move to Core/
GameManager -> keep only one instance
```
---
## 13. Recommended Next Step
The most practical next step is to create a **production-ready Unity script skeleton** for the revised architecture, including:
- `PlayerController`
- `HammerThrower`
- `HammerProjectile`
- `TrollController`
- `TrollStateMachine`
- `NoiseSystem`
- `Chest`
- `LevelManager`
- `GameManager`
This would turn the conceptual structure into an implementation-ready foundation.
Assets/Docs/ArchitectureMigration.md
-681
View File
@@ -1,681 +0,0 @@
# 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.
Assets/Docs/ArchitectureMigration.md.meta
-7
View File
@@ -1,7 +0,0 @@
fileFormatVersion: 2
guid: 690a6b37d2b97044c8a4ecda9dce6e90
TextScriptImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:
Assets/Docs/Evolution.md
+13
View File
@@ -0,0 +1,13 @@
# Architectural Evolution
This document tracks the major architectural improvements and transitions in the **Gnome’s Bounty** project.
## Resolved Improvements
1. **Axe renamed to Hammer:** All scripts, prefabs, and sprites now use the Hammer theme to align with the core vision of a magical throwing hammer.
2. **Noise System Added:** A dedicated `NoiseSystem` handles enemy alerts, adding a tactical stealth-puzzle layer.
3. **Manager Cleanup:** `GameManager` and other managers are now centralized in `Scripts/Managers/`.
4. **Enemy Logic Refined:** `EnemyAI` replaces the generic troll logic with specific behavior states.
5. **Environment Logic Centralized:** Folder structure now clearly separates world objects and environment mechanics.
For the current state of the architecture, see [Architecture.md](./Architecture.md).
Assets/Docs/Guidelines.md
+10
View File
@@ -0,0 +1,10 @@
# Implementation Guidelines
To maintain architectural consistency in **Gnome’s Bounty**, please follow these rules when adding new content:
- **New World Objects:** Place in `Scripts/EnvironmentObjects/`.
- **New Managers:** Place in `Scripts/Managers/`.
- **New AI Behaviors:** Add to `EnemyAI.cs` or create specialized classes in `Scripts/Enemies/`.
- **UI Updates:** Modify `UIManager.cs` and related scripts in `Scripts/Managers/`.
Refer to [Architecture.md](./Architecture.md) for the full project structure.
Assets/Docs/Systems.md
+26
View File
@@ -0,0 +1,26 @@
# Key Gameplay Systems
This document details the core systems that drive the gameplay in **Gnome’s Bounty**.
## 1. Hammer System
The gnome uses a **Magical Throwing Hammer**. This is the primary tool for:
- Stunning enemies.
- Breaking walls.
- Activating remote triggers.
**Files:** `Hammer.cs`, `HammerThrower.cs`.
## 2. Noise & Stealth
Enemies react to noise created by the player (e.g., breaking walls, hammer impacts). This system creates the tactical "stealth-puzzle" layer.
**Files:** `NoiseSystem.cs`.
## 3. Enemy AI & Spawning
Enemies (Goblins) follow predictable paths but become dangerous when alerted or when spawning from caves to increase level pressure.
**Files:** `EnemyAI.cs`, `EnemySpawner.cs`.
## 4. Environmental Interaction
Breakable walls, chests, and doors form the core of the level puzzles. The "Key Chest" mechanic ensures players must explore to find the exit key.
**Files:** `BreakableWall.cs`, `KeyChest.cs`, `Chest.cs`, `Door.cs`.