added inventory and stamina system
This commit is contained in:
353
DEV_NOTES.md
Normal file
353
DEV_NOTES.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# OGG — Dev Notes & Systems Guide
|
||||
|
||||
> Boomer shooter. Cruelty Squad vibes. Jank is a feature.
|
||||
> This doc covers all current systems.
|
||||
|
||||
---
|
||||
|
||||
## Scene Hierarchy
|
||||
|
||||
```
|
||||
Player [CharacterController, FirstPersonController, SimpleCrosshair]
|
||||
│ [Player, PlayerHUD, Inventory, WeaponManager, BootsEffect]
|
||||
└── Camera [Camera, AudioListener, CameraShake, WeaponBob]
|
||||
```
|
||||
|
||||
Pickups are standalone GameObjects placed anywhere in the scene — **not** children of the player.
|
||||
|
||||
---
|
||||
|
||||
## Scripts Overview
|
||||
|
||||
| Script | Lives On | What it does |
|
||||
|---|---|---|
|
||||
| `FirstPersonController` | Player | WASD move, mouse look, jump, sprint, cursor lock |
|
||||
| `Player` | Player | Health + stamina stats, drain/regen logic, sprint gating |
|
||||
| `PlayerHUD` | Player | Health bar, stamina bar, speedometer (IMGUI) |
|
||||
| `SimpleGun` | Weapon prefabs | Shooting, ammo, recoil, muzzle flash, bullet decals |
|
||||
| `CameraShake` | Camera | Singleton shake impulses, called by SimpleGun on fire |
|
||||
| `WeaponBob` | Camera | Procedural weapon sway while moving |
|
||||
| `WeaponViewmodel` | Weapon prefabs | Per-weapon position/rotation/scale in the player's hands |
|
||||
| `SimpleCrosshair` | Player | Draws the crosshair via OnGUI |
|
||||
| `EnemyHealth` | Enemy objects | Takes damage from SimpleGun raycasts, flashes red, dies |
|
||||
| `EnemySpawner` | Any object | Spawns enemies at runtime |
|
||||
| `HumanoidEnemy` | Enemy objects | Enemy AI / behaviour |
|
||||
| `ItemDefinition` | ScriptableObject asset | Data definition for any item: name, icon, type, weapon prefab, equippable flag |
|
||||
| `PickupItem` | Pickup GameObjects | Spin/bob animation, proximity prompt, E-to-collect |
|
||||
| `Inventory` | Player | Item list, [I] HUD, right-click context menu, equip logic |
|
||||
| `WeaponManager` | Player | Instantiates weapon prefabs, handles slot switching |
|
||||
| `BootsEffect` | Player | Watches inventory for Bunny Hop Boots equipped state, applies stamina boost |
|
||||
| `StaminaBoostPickup` | Pickup GameObjects | Legacy — superseded by BootsEffect. Left in for reference. |
|
||||
|
||||
---
|
||||
|
||||
## 1. Player Stats — `Player` + `PlayerHUD`
|
||||
|
||||
`Player.cs` is the data container for all player stats. `PlayerHUD.cs` reads from it and draws the HUD.
|
||||
|
||||
**Health fields:**
|
||||
- `maxHealth` / `health` — enemies subtract from `health` directly, no auto-regen
|
||||
|
||||
**Stamina fields:**
|
||||
- `maxStamina` / `stamina` — depletes while sprinting
|
||||
- `staminaDrain` — units lost per second while sprinting (default 22)
|
||||
- `staminaRegen` — units gained per second when resting (default 12)
|
||||
- `regenDelay` — seconds of non-sprinting before regen starts (default 1.2)
|
||||
- When stamina hits 0 the player is **exhausted** — sprint locked out until stamina fully refills
|
||||
|
||||
**HUD Layout:**
|
||||
```
|
||||
[bottom-left corner]
|
||||
SPEED
|
||||
42.3
|
||||
units / sec
|
||||
|
||||
HEALTH 85 / 100
|
||||
[████████████░░░]
|
||||
STAMINA 62 / 100
|
||||
[██████░░░░░░░░░]
|
||||
```
|
||||
|
||||
**Speedometer:**
|
||||
- Sits above the health/stamina bars, bottom-left
|
||||
- Speed calculated from actual position delta per frame (horizontal only)
|
||||
- Colour shifts: green → yellow → red as speed increases
|
||||
- Thresholds configurable in Inspector (`speedoFastThreshold`, `speedoCritThreshold`)
|
||||
- Can be toggled off via `showSpeedometer` bool
|
||||
|
||||
---
|
||||
|
||||
## 2. Movement — `FirstPersonController`
|
||||
|
||||
Standard FPS controller.
|
||||
|
||||
**Inspector fields:**
|
||||
- `walkSpeed` / `runSpeed` — intentionally high (50/80) due to CharacterController collision tuning
|
||||
- `mouseSensitivity` — linear, no acceleration
|
||||
- `playerCamera` — auto-found if empty, best to assign explicitly
|
||||
|
||||
**Controls:**
|
||||
| Key | Action |
|
||||
|---|---|
|
||||
| W A S D / Arrows | Move |
|
||||
| Left Shift | Sprint (drains stamina) |
|
||||
| Space | Jump |
|
||||
| Mouse | Look |
|
||||
| Escape | Unlock cursor |
|
||||
| Left Click (unlocked) | Re-lock cursor |
|
||||
|
||||
---
|
||||
|
||||
## 3. Shooting — `SimpleGun`
|
||||
|
||||
Raycast-based hitscan. No projectiles.
|
||||
|
||||
**Key fields:**
|
||||
- `damage` — per shot
|
||||
- `range` — raycast distance in units
|
||||
- `fireRate` — shots per second
|
||||
- `isAutomatic` — hold vs click
|
||||
- `recoilKickback` / `recoilKickUp` — feel tuning
|
||||
- `fpsCam` — auto-found if null
|
||||
|
||||
**Internals:**
|
||||
- Muzzle flash: child Quad + Point Light, shown ~50ms per shot
|
||||
- Bullet decals: pooled (30 max), oldest reused when full
|
||||
- Spark particles: spawned and self-destroyed on impact
|
||||
- Calls `CameraShake.Instance.Shake()` on every shot
|
||||
- Shooting blocked when inventory is open
|
||||
- Position driven by `WeaponManager.weaponPositionOffset` each frame so recoil applies on top correctly
|
||||
|
||||
**Ammo:** `currentAmmo` / `maxAmmo`. Press **R** to reload (instant).
|
||||
|
||||
---
|
||||
|
||||
## 4. Item Definitions — `ItemDefinition` (ScriptableObject)
|
||||
|
||||
**Create:** Right-click in Project → **Create → OGG → Item Definition**
|
||||
|
||||
| Field | Notes |
|
||||
|---|---|
|
||||
| `itemName` | Display name everywhere — must be unique |
|
||||
| `icon` | Sprite shown in inventory slots |
|
||||
| `type` | `Misc`, `Consumable`, or `Weapon` |
|
||||
| `isEquippable` | Tick for non-weapon items that can be equipped (e.g. boots) — shows equip button in inventory |
|
||||
| `weaponPrefab` | Weapon type only — prefab spawned in weapon holder when equipped |
|
||||
| `description` | Shown in inventory detail panel |
|
||||
|
||||
---
|
||||
|
||||
## 5. Pickups — `PickupItem`
|
||||
|
||||
Attach to any GameObject to make it a spinning, bobbing pickup.
|
||||
|
||||
**Setup:**
|
||||
1. Place a GameObject in the scene with any mesh
|
||||
2. Add `PickupItem` component
|
||||
3. Drag an `ItemDefinition` into the `Definition` slot
|
||||
|
||||
**Inspector fields:**
|
||||
| Field | Notes |
|
||||
|---|---|
|
||||
| `definition` | The ItemDefinition asset |
|
||||
| `spinSpeed` | Degrees/sec Y rotation (default 120) |
|
||||
| `bobHeight` | Vertical travel in units (default 0.18) |
|
||||
| `bobSpeed` | Bob cycles per second (default 2.2) |
|
||||
| `pickupRadius` | Proximity trigger distance |
|
||||
| `pickupKey` | Default E |
|
||||
| `pickupParticlesPrefab` | Optional — spawned on collect |
|
||||
| `pickupSound` | Optional — played on collect |
|
||||
|
||||
**On pickup:** Calls `Inventory.AddItem(definition, autoEquip: true)` — picking up a weapon automatically equips it.
|
||||
|
||||
---
|
||||
|
||||
## 6. Inventory — `Inventory`
|
||||
|
||||
Lives on the Player. Press **I** to open/close. Cursor unlocks when open.
|
||||
|
||||
**HUD Layout:**
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ [ INVENTORY ] │ ← header, shows active weapon top-right
|
||||
├──────────────────────────────┤
|
||||
│ [ ] [ ] [ ] [ ] │
|
||||
│ [ ] [ ] [ ] [ ] │ ← item grid (4×5 by default)
|
||||
├──────────────────────────────┤
|
||||
│ SELECTED: Item Name │ ← detail panel
|
||||
│ Description │
|
||||
│ ▶ EQUIPPED [ F ] UNEQUIP│ ← shown for weapons AND equippable items
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
**Right-click context menu** on any slot:
|
||||
- **Equip** / **Unequip** — shown for weapons and items with `isEquippable = true`
|
||||
- **Inspect** — selects the item in the detail panel
|
||||
- **Drop** — removes from inventory
|
||||
|
||||
**Controls:**
|
||||
| Input | Action |
|
||||
|---|---|
|
||||
| I | Toggle inventory open/close |
|
||||
| Click slot | Select item |
|
||||
| Double-click weapon slot | Equip it |
|
||||
| Right-click slot | Open context menu |
|
||||
| F | Equip selected item |
|
||||
| Scroll Wheel (closed) | Cycle weapons |
|
||||
| 1–9 (closed) | Equip weapon by slot number |
|
||||
|
||||
**Slot colours:**
|
||||
- Dark grey = empty
|
||||
- Dark green = has item
|
||||
- Bright green = selected
|
||||
- Orange = equipped
|
||||
|
||||
**Useful methods:**
|
||||
```csharp
|
||||
inventory.HasItem("Medkit") // bool
|
||||
inventory.CountOf("Grenade") // int
|
||||
inventory.RemoveItem("Medkit", 1) // bool
|
||||
inventory.AddItem(definition) // add by ItemDefinition
|
||||
inventory.AddItem("Raw Name", sprite) // add by name
|
||||
inventory.IsOpen // bool — checked by gun + WeaponManager
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Weapon Manager — `WeaponManager`
|
||||
|
||||
Lives on the Player. Manages weapon instances and which is active.
|
||||
|
||||
**Setup:**
|
||||
- Add `WeaponManager` to Player
|
||||
- Set `Weapon Holder` to the Camera transform
|
||||
- Any `SimpleGun` child of the holder is auto-registered but starts **inactive** — player must pick up and equip from inventory
|
||||
|
||||
**Weapon Position fields:**
|
||||
- `weaponPositionOffset` / `weaponRotationOffset` / `weaponScale` — global fallback if the weapon has no `WeaponViewmodel` component
|
||||
- Per-weapon positioning is preferred — add `WeaponViewmodel` to the weapon prefab instead
|
||||
|
||||
**Live positioning workflow (in Editor):**
|
||||
1. Hit Play, equip the gun
|
||||
2. On WeaponManager Inspector → click **"Select Active Weapon in Scene"**
|
||||
3. Use gizmos in Scene view to position it
|
||||
4. Click **"Sync Transform → Offset Fields"** — saves to the `WeaponViewmodel` on the prefab automatically
|
||||
5. Stop Play — values persist
|
||||
|
||||
**Useful methods:**
|
||||
```csharp
|
||||
weaponManager.EquipByIndex(0)
|
||||
weaponManager.EquipByName("Gun Splat")
|
||||
weaponManager.CycleWeapon(1) // next
|
||||
weaponManager.CycleWeapon(-1) // previous
|
||||
weaponManager.ActiveWeaponName // string
|
||||
weaponManager.Unequip() // holster all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. WeaponViewmodel — `WeaponViewmodel`
|
||||
|
||||
Add to a **weapon prefab** to define how it sits in the player's hands. WeaponManager reads from it on equip instead of using the global offset.
|
||||
|
||||
**Fields:**
|
||||
- `positionOffset` — local position relative to weapon holder
|
||||
- `rotationOffset` — euler angles
|
||||
- `scale` — local scale
|
||||
|
||||
Each weapon prefab gets its own values, so Gun Splat can sit differently from any future weapon.
|
||||
|
||||
---
|
||||
|
||||
## 9. Equippable Items — `BootsEffect`
|
||||
|
||||
**Add `BootsEffect` to the Player** for the Bunny Hop Boots to work.
|
||||
|
||||
Lives on the Player. Watches `Inventory.items` each frame for the boots' `isEquipped` state and adjusts `Player.maxStamina` accordingly.
|
||||
|
||||
| State | Effect |
|
||||
|---|---|
|
||||
| Boots equipped | `maxStamina` → 200, stamina topped up |
|
||||
| Boots unequipped | `maxStamina` → 100, stamina clamped back down |
|
||||
|
||||
The stamina bar stretches/shrinks live to reflect the new max.
|
||||
|
||||
**Inspector fields:**
|
||||
- `bootsItemName` — must match the ItemDefinition `itemName` exactly (default `"Bunny Hop Boots"`)
|
||||
- `boostedMaxStamina` — default 200
|
||||
|
||||
---
|
||||
|
||||
## Setup Scripts (Editor Menu: OGG → Setup)
|
||||
|
||||
### Create Gun Splat Weapon
|
||||
Creates:
|
||||
- `Assets/Prefabs/Weapons/GunSplat.prefab` — held weapon with `SimpleGun`
|
||||
- `Assets/Prefabs/Pickups/GunSplat_Pickup.prefab` — world pickup with spin/bob
|
||||
- `Assets/Items/GunSplat_Item.asset` — `ItemDefinition` (type = Weapon)
|
||||
|
||||
### Create Bunny Hop Boots
|
||||
Creates:
|
||||
- `Assets/Items/BhopBoots_Item.asset` — `ItemDefinition` (type = Misc, isEquippable = true)
|
||||
- `Assets/Prefabs/Pickups/BhopBoots_Pickup.prefab` — world pickup
|
||||
|
||||
**After running either script:** drag the pickup prefab into your scene.
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Weapon — Step by Step
|
||||
|
||||
1. Create an `ItemDefinition` asset — set `type = Weapon`, assign your gun prefab to `weaponPrefab`
|
||||
2. Add `SimpleGun` to the gun prefab root
|
||||
3. Add `WeaponViewmodel` to the gun prefab — set position/rotation/scale or dial it in with the live Editor workflow
|
||||
4. Create a pickup: any mesh + `PickupItem` component + drag in the ItemDefinition
|
||||
5. Place the pickup in the scene
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Equippable Item
|
||||
|
||||
1. Create an `ItemDefinition` — set `type = Misc`, tick `isEquippable = true`
|
||||
2. Write a component that lives on the Player, watches `inventory.items` for `entry.isEquipped`, and applies/removes the effect
|
||||
3. Place a pickup in the scene referencing the definition
|
||||
|
||||
---
|
||||
|
||||
## Adding a Consumable
|
||||
|
||||
```csharp
|
||||
Inventory inv = GetComponent<Inventory>();
|
||||
if (inv.HasItem("Medkit")) {
|
||||
health += 50f;
|
||||
inv.RemoveItem("Medkit");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known Rough Edges
|
||||
|
||||
- **No weapon switch animation** — instant swap. Hook into `WeaponManager.EquipByIndex()` when ready.
|
||||
- **No save system** — inventory is runtime only, nothing persists between sessions.
|
||||
- **Starting gun** — any `SimpleGun` that's a child of the Camera at Start gets auto-registered but starts inactive. Player needs to find it as a pickup in the scene.
|
||||
- **Inventory is IMGUI** — not Canvas. Performance fine at this scale. All data logic is decoupled from drawing so a Canvas swap later would be straightforward.
|
||||
- **`SimpleGun` assumes it's always active** — non-SimpleGun weapons will slot-switch fine but need their own input handling to shoot.
|
||||
|
||||
---
|
||||
|
||||
## Controls Reference
|
||||
|
||||
| Key | Action |
|
||||
|---|---|
|
||||
| W A S D | Move |
|
||||
| Left Shift | Sprint |
|
||||
| Space | Jump |
|
||||
| Left Click | Shoot |
|
||||
| Right Click | Context menu (inventory open) |
|
||||
| R | Reload |
|
||||
| E | Pick up nearby item |
|
||||
| I | Open / close inventory |
|
||||
| F | Equip selected item |
|
||||
| Scroll Wheel | Cycle weapons |
|
||||
| 1 – 9 | Equip weapon by slot |
|
||||
| Escape | Unlock cursor |
|
||||
Reference in New Issue
Block a user