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

Update architecture documentation for Gnome's Bounty

Browse Source 
Revise architecture documentation to align with gameplay concept and improve clarity.
This commit is contained in:
voffka81
2026-06-07 15:13:31 +03:00
committed by GitHub
parent 95ae008290
commit 851cf3376d
1 changed files with 744 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Assets/Docs/Architecture.md
+744 -33
View File
@@ -1,8 +1,55 @@
# Gnome’s Bounty - Architecture Documentation
# Gnome’s Bounty — Architecture Review and Alignment Report
## Project Structure
## 1. Purpose
```
This document reviews the current Unity project architecture for **Gnome’s Bounty** and evaluates how well it matches the core game concept.
The goal is to determine whether the current structure supports the intended gameplay:
- tactical movement instead of combat
- puzzle-focused level design
- a **magical throwing hammer** as the main tool
- trolls as slow, persistent pressure enemies
- treasure, chests, keys, and exit-based progression
- rising tension through timed troll spawns
- environmental interaction and noise-driven enemy reactions
---
## 2. Executive Summary
**Verdict:** The current architecture is a **good starting point**, but it is **not yet 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.
### Overall Alignment Score
**7/10**
### Main Reasons
#### 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
## Current Structure
```text
Assets/
├── Scripts/
│ ├── Controllers/
@@ -61,40 +108,704 @@ Assets/
└── README.md
```
## Key Components and Systems
---
### Player Controller
- **Responsibilities**: Handles player movement (left/right, climbing, jumping).
- **Interactions**: Interacts with the magical throwing axe.
## 4. What Matches the Core Game Idea
### Troll Controller
- **Responsibilities**: Manages troll behavior (patrol, chase, stun recovery).
- **Spawning**: Spawns trolls from the troll cave.
### 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/
│ │ ├── TrollController.cs
│ │ ├── TrollStateMachine.cs
│ │ └── TrollSensors.cs
│ │
│ ├── Systems/
│ │ ├── TrollSpawner.cs
│ │ ├── NoiseSystem.cs
│ │ ├── ChestSystem.cs
│ │ └── ScoreSystem.cs
│ │
│ ├── World/
│ │ ├── BreakableBlock.cs
│ │ ├── Treasure.cs
│ │ ├── Chest.cs
│ │ ├── ExitDoor.cs
│ │ ├── KeyItem.cs
│ │ └── TrollCave.cs
│ │
│ ├── Projectiles/
│ │ └── HammerProjectile.cs
│ │
│ ├── Managers/
│ │ ├── InputManager.cs
│ │ ├── AudioManager.cs
│ │ └── UIManager.cs
│ │
│ ├── UI/
│ │ ├── HUD.cs
│ │ ├── KeyUI.cs
│ │ ├── ExitDoorUI.cs
│ │ └── TreasureUI.cs
│ │
│ └── Editor/
│ ├── PlayerControllerEditor.cs
│ └── TrollControllerEditor.cs
│
├── Prefabs/
│ ├── Player.prefab
│ ├── Troll.prefab
│ ├── Hammer.prefab
│ ├── HammerProjectile.prefab
│ ├── BreakableBlock.prefab
│ ├── Treasure.prefab
│ ├── Chest.prefab
│ ├── ExitDoor.prefab
│ └── TrollCave.prefab
│
├── Scenes/
│ ├── MainScene.unity
│ └── Level1.unity
│
├── Resources/
│ ├── Sprites/
│ │ ├── Player.png
│ │ ├── Troll.png
│ │ ├── Hammer.png
│ │ ├── BreakableBlock.png
│ │ ├── Treasure.png
│ │ ├── Chest.png
│ │ └── ExitDoor.png
│ └── Audio/
│ ├── Footsteps.mp3
│ ├── StunSound.wav
│ ├── BlockBreak.mp3
│ ├── KeyCollect.mp3
│ ├── HammerThrow.wav
│ ├── HammerImpact.wav
│ └── LevelComplete.mp3
│
├── Documentation/
│ ├── Architecture.md
│ ├── GameConcept.md
│ └── SystemsOverview.md
│
└── README.md
```
---
## 7. Recommended Responsibilities by System
## 7.1 Core
### GameManager
- **Responsibilities**: Manages game state (level progression, score, lives).
Responsible for global game state:
### InputManager
- **Responsibilities**: Handles player input for movement and axe throwing.
### AudioManager
- **Responsibilities**: Plays sound effects and background music.
### UIManager
- **Responsibilities**: Manages the heads-up display (HUD) and UI elements like keys and exit doors.
### AxeThrower
- **Responsibilities**: Handles the mechanics of throwing the magical axe.
- **Stunning**: Stuns trolls and breaks blocks.
### BreakableBlock
- **Responsibilities**: Manages breakable blocks, including their destruction and sound effects.
### TreasureCollector
- **Responsibilities**: Tracks treasure collected by the player.
### TrollSpawner
- **Responsibilities**: Spawns trolls at timed intervals from the troll cave.
- current level
- score
- pause state
- restart flow
- progression to the next level
- game over / level complete state
### LevelManager
- **Responsibilities**: Manages level transitions and loading.
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
### PlayerController
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
### TrollController
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
### TrollSpawner
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.