From 9dc237bf27ea01097ef714faa239ecebcba35133 Mon Sep 17 00:00:00 2001 From: Valdimir Date: Sun, 21 Jun 2026 23:56:53 +0300 Subject: [PATCH] Refactor project architecture for Gnome's Bounty - 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. --- Assets/Docs/Architecture.md | 836 ++-------------------- Assets/Docs/ArchitectureMigration.md | 681 ------------------ Assets/Docs/ArchitectureMigration.md.meta | 7 - Assets/Docs/Evolution.md | 13 + Assets/Docs/Guidelines.md | 10 + Assets/Docs/Systems.md | 26 + 6 files changed, 127 insertions(+), 1446 deletions(-) delete mode 100644 Assets/Docs/ArchitectureMigration.md delete mode 100644 Assets/Docs/ArchitectureMigration.md.meta create mode 100644 Assets/Docs/Evolution.md create mode 100644 Assets/Docs/Guidelines.md create mode 100644 Assets/Docs/Systems.md diff --git a/Assets/Docs/Architecture.md b/Assets/Docs/Architecture.md index 685f992..8c46c5d 100644 --- a/Assets/Docs/Architecture.md +++ b/Assets/Docs/Architecture.md @@ -1,811 +1,131 @@ -# Gnome’s Bounty — Architecture Review and Alignment Report +# Gnome’s Bounty — Architecture and Project Alignment ## 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 - puzzle-focused level design - 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 -- rising tension through timed troll spawns +- rising tension through timed enemy 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. +**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 -**7/10** +**10/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 +### Main Features +See [Key Gameplay Systems](./Systems.md) for details on Hammer, Noise, and AI systems. --- -## 3. Review of the Current Project Structure - -## Current Structure +## 3. Current Project Structure ```text Assets/ ├── Scripts/ +│ ├── Combat/ +│ │ └── Hammer.cs │ ├── 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: - -```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 -│ │ +│ │ └── PlayerController.cs │ ├── Enemies/ -│ │ ├── TrollController.cs -│ │ ├── TrollStateMachine.cs -│ │ └── TrollSensors.cs -│ │ -│ ├── Systems/ -│ │ ├── TrollSpawner.cs -│ │ ├── NoiseSystem.cs -│ │ ├── ChestSystem.cs -│ │ └── ScoreSystem.cs -│ │ -│ ├── World/ -│ │ ├── BreakableBlock.cs -│ │ ├── Treasure.cs +│ │ ├── EnemyAI.cs +│ │ └── EnemySpawner.cs +│ ├── Environment/ +│ │ ├── MapElements/ +│ │ │ ├── IMapElement.cs +│ │ │ ├── MapElement.cs +│ │ │ └── MapElementSO.cs +│ │ └── BreakableWall.cs +│ ├── EnvironmentObjects/ │ │ ├── Chest.cs -│ │ ├── ExitDoor.cs -│ │ ├── KeyItem.cs -│ │ └── TrollCave.cs -│ │ -│ ├── Projectiles/ -│ │ └── HammerProjectile.cs -│ │ +│ │ ├── Door.cs +│ │ ├── DoorInteract.cs +│ │ └── KeyChest.cs │ ├── Managers/ +│ │ ├── GameManager.cs │ │ ├── InputManager.cs -│ │ ├── AudioManager.cs +│ │ ├── LevelManager.cs +│ │ ├── NoiseSystem.cs │ │ └── UIManager.cs -│ │ -│ ├── UI/ -│ │ ├── HUD.cs -│ │ ├── KeyUI.cs -│ │ ├── ExitDoorUI.cs -│ │ └── TreasureUI.cs -│ │ -│ └── Editor/ -│ ├── PlayerControllerEditor.cs -│ └── TrollControllerEditor.cs -│ +│ ├── Player/ +│ │ ├── HammerThrower.cs +│ │ └── PlayerState.cs +│ ├── ScriptableObject/ +│ │ └── TreasureSO.cs +│ └── Utilities/ +│ ├── CameraFollow.cs +│ ├── Character.cs +│ ├── Enums.cs +│ ├── IDoor.cs +│ ├── InputActions.cs +│ └── MainMenu.cs ├── Prefabs/ -│ ├── Player.prefab -│ ├── Troll.prefab -│ ├── Hammer.prefab -│ ├── HammerProjectile.prefab -│ ├── BreakableBlock.prefab -│ ├── Treasure.prefab +│ ├── BreakableTile.prefab │ ├── Chest.prefab -│ ├── ExitDoor.prefab -│ └── TrollCave.prefab -│ +│ ├── Explosion.prefab +│ ├── Goblin.prefab +│ ├── Hammer.prefab +│ ├── Ladder.prefab +│ ├── Player.prefab +│ └── Torch.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 +│ ├── Level 1.unity +│ ├── MainMenu.unity +│ └── Test.unity +├── Sprites/ +│ ├── Arts/ +│ ├── Env/ +│ ├── Coin.png +│ ├── Goblin_parts.png +│ ├── Hammer.png +│ ├── Key.png +│ └── Tileset.png +└── Docs/ + ├── Architecture.md + ├── ArchitectureMigration.md + ├── Background.md + ├── Decoraions.md + ├── GameConcept.md + ├── Hud_specs.md + ├── MigrationCompletionSummary.md + ├── SetupGuide.md + └── TilesetSpecs.md ``` --- -## 7. Recommended Responsibilities by System +## 4. Key Gameplay Systems -## 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 +Core gameplay mechanics are detailed in separate documents: +- **[Systems.md](./Systems.md)**: Detailed breakdown of Hammer, Noise, AI, and Environment systems. --- -## 7.2 Player +## 5. Architectural Evolution -### 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 +History of architectural changes and resolved issues can be found in **[Evolution.md](./Evolution.md)**. --- -## 7.3 Enemies +## 6. Implementation Guidelines -### 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 +Standard practices for project expansion are located in **[Guidelines.md](./Guidelines.md)**. --- -## 7.4 Systems +## 7. Conclusion -### 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. +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. diff --git a/Assets/Docs/ArchitectureMigration.md b/Assets/Docs/ArchitectureMigration.md deleted file mode 100644 index 370e82f..0000000 --- a/Assets/Docs/ArchitectureMigration.md +++ /dev/null @@ -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. diff --git a/Assets/Docs/ArchitectureMigration.md.meta b/Assets/Docs/ArchitectureMigration.md.meta deleted file mode 100644 index 25ed20f..0000000 --- a/Assets/Docs/ArchitectureMigration.md.meta +++ /dev/null @@ -1,7 +0,0 @@ -fileFormatVersion: 2 -guid: 690a6b37d2b97044c8a4ecda9dce6e90 -TextScriptImporter: - externalObjects: {} - userData: - assetBundleName: - assetBundleVariant: diff --git a/Assets/Docs/Evolution.md b/Assets/Docs/Evolution.md new file mode 100644 index 0000000..0cfcbdc --- /dev/null +++ b/Assets/Docs/Evolution.md @@ -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). \ No newline at end of file diff --git a/Assets/Docs/Guidelines.md b/Assets/Docs/Guidelines.md new file mode 100644 index 0000000..93d6910 --- /dev/null +++ b/Assets/Docs/Guidelines.md @@ -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. \ No newline at end of file diff --git a/Assets/Docs/Systems.md b/Assets/Docs/Systems.md new file mode 100644 index 0000000..73cd552 --- /dev/null +++ b/Assets/Docs/Systems.md @@ -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`. \ No newline at end of file