agent-skills

Hidden Hubs – Project Overview

Date: February 26, 2026

This document acts as the long‑term memory for the Hidden Hubs codebase. Whenever new systems are added, refactored or architectures change the README should be updated so future engineers (or we, two weeks later) can understand how things fit together.

🎯 Current Architecture

The project uses a lightweight, event‑driven architecture with the following core responsibilities split across systems:

• NPCManager – singleton quest state / fragment counter. Broadcasts FragmentCollected and QuestComplete events.
• SaveLoadSystem – serialises NPCManager state and the player position to JSON in Application.persistentDataPath.
• Dialogue subsystem – new architecture introduced Feb 26 2026:
  • DialogueData (ScriptableObject) – conversation content.
  • DialogueManager – central state machine for playing dialogues.
  • DialogueUI – visual component (typewriter, fade, wrapping).
  • Interactable base class – reusable range‑and‑input logic.
  • QuestNPC – derives from Interactable, chooses dialogue asset based on quest progress and hooks into NPCManager events. It also toggles conversations (via DialogueManager.StartDialogue/.StopDialogue) and refreshes active lines when fragment counts change.

QuestNPC responsibilities

• Determine which dialogue asset to play (greeting/progress/complete).

• Start/stop conversations and ensure only one runs at a time.

• Refresh a live line when quest progress updates.

• Show an optional "press F" hint when player is in range.

• Close dialogue if player exits the trigger during a conversation.

• Pickup / Fragment – visual bob + rotation; notifies NPCManager on collection.

• UI scripts – e.g. UpdateCollectibleCount listens to quest events and updates the fragment counter.

Folder structure

Assets/
├── Hidden Hubs/
│   ├── SourceFiles/
│   │   ├── InputSystem/
│   │   │   └── StarterAssetsInputs.cs
│   │   ├── Interaction/
│   │   │   └── Interactable.cs            # base class for world interactions
│   │   ├── Dialogue/
│   │   │   ├── DialogueData.cs            # SO container for lines
│   │   │   ├── DialogueUI.cs              # handles typewriter + fade
│   │   │   └── DialogueManager.cs         # state machine
│   │   ├── Scripts/
│   │   │   ├── NPCManager.cs              # quest state and events
│   │   │   ├── Pickup.cs                  # collectible behaviour
│   │   │   ├── QuestNPC.cs                # NPC-specific behaviour
│   │   │   ├── UpdateCollectibleCount.cs  # HUD counter
│   │   │   ├── SaveLoadSystem.cs
│   │   │   └── ... (other unrelated scripts)
│   └── ...
├── (other packages, pro builder examples, etc.)
└── HB.slnx / csproj files

Important top‑level files (scripts copied to root during past updates) are kept for historical reasons (QuestNPC.cs used to live at project root; now it is not—ignore that legacy copy if present).

🔊 Dialogue System Details

The new conversation framework satisfies the goals outlined on Feb 26:

1. Typewriter effect + skip – DialogueUI runs a coroutine that reveals characters over time; pressing the interact key while typing calls SkipTyping() and the line finishes instantly.
2. Line progression – once a line finishes, the manager enters WaitingForInput state and listens for the next key press (E/Space or the Input System "Interact" action). Pressing the key advances to the next line or ends the dialogue.
3. Non‑overflowing text – the TMP component on the panel should have Word Wrapping enabled and a suitable RectTransform size with a ContentSizeFitter / Vertical Layout Group + Mask if scrolling is desired. See Editor setup below.
4. Reusable across NPCs – dialogues are authored as DialogueData assets that can be swapped in the inspector.
5. Data/logic separation – asset holds text only; manager and UI handle presentation and input.
6. Future‑proofing – the SO class is trivial; you can subclass it later for branching choices or add speaker tags. DialogueManager exposes events and a RefreshCurrentLine method for dynamic tokens.
7. State machine – manager tracks Idle, Typing, WaitingForInput, Finished states, preventing overlapping triggers and making the flow explicit.

Example usage

// QuestNPC or any other actor:
DialogueManager.Instance.StartDialogue(myDialogueAsset, currentFragments);

Dialogue flow (text‑diagram)