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

Gnome’s Bounty — Architecture Review and Alignment Report

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

Assets/
├── Scripts/
│   ├── Controllers/
│   │   ├── 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:

AxeThrower.cs   -> HammerThrower.cs
Axe.prefab      -> Hammer.prefab
Axe.png         -> Hammer.png

If future extensibility is important, a more flexible option would be:

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:

Scripts/Core/GameManager.cs

or, if keeping the current hierarchy:

Scripts/Managers/GameManager.cs

---

5.3 TrollSpawner is Not a Utility

TrollSpawner.cs is currently placed under:

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:

Scripts/Systems/TrollSpawner.cs

or:

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:

Scripts/Systems/NoiseSystem.cs

And optionally define interfaces such as:

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:

Scripts/World/Chest.cs
Scripts/Systems/ChestSystem.cs
Scripts/World/KeyItem.cs

or at minimum:

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

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:

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:

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.

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

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

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

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.