From 851cf3376d94abea32905f5ae8411624d8ee3fdf Mon Sep 17 00:00:00 2001 From: voffka81 <84612470+voffka81@users.noreply.github.com> Date: Sun, 7 Jun 2026 15:13:31 +0300 Subject: [PATCH] Update architecture documentation for Gnome's Bounty Revise architecture documentation to align with gameplay concept and improve clarity. --- Assets/Docs/Architecture.md | 777 ++++++++++++++++++++++++++++++++++-- 1 file changed, 744 insertions(+), 33 deletions(-) diff --git a/Assets/Docs/Architecture.md b/Assets/Docs/Architecture.md index 51b0454..685f992 100644 --- a/Assets/Docs/Architecture.md +++ b/Assets/Docs/Architecture.md @@ -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. \ No newline at end of file +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.