gogobee/gogobee_expedition_system.md

GogoBee — Expedition System

Companion to: gogobee_dnd_design_doc.md, gogobee_dungeon_zones.md Version: 1.0 Status: Draft

---

⚠️ Protected Files — DO NOT MODIFY

All existing *_flavor.go / *_flavor.txt files are off-limits. New expedition flavor text goes in twinbee_expedition_flavor.go — a new file, never edits to existing ones.

---

1. Design Philosophy

Single-session dungeon runs are replaced by Expeditions — persistent, multi-day (sometimes multi-week) explorations tied to real calendar time. An Expedition is not a sprint. It is a campaign.

What changes

• Zones are no longer completed in one sitting. They unfold over real days.
• The player logs in each day to take actions, advance, rest, manage supplies.
• TwinBee delivers a Morning Briefing and an Evening Recap every real-world day the expedition is active.
• Resources deplete over time. Poor planning ends expeditions early.
• The dungeon has a Threat Clock — the longer you stay, the more aware the zone becomes.
• Some events only happen on specific days, specific times, or after specific triggers.

What doesn't change

• All combat mechanics from the main design doc apply unchanged.
• Loot, XP, and progression work identically.
• Players can still retreat, rest, and use all existing commands.
• Zones are still the same zones with the same bosses.

---

2. Expedition Duration by Zone Tier

Tier	Zone	Minimum Days	Maximum Days	Notes
1	Goblin Warrens	2	4	Shortest possible expedition
1	Crypt of Valdris	2	5	Boss requires full rest before attempt
2	Forest of Shadows	4	8	Zone scales spatially
2	Sunken Temple	4	9	Tidal event on Day 6 (see Section 7)
3	Haunted Manor	6	12	Manor fully resets every 3 in-game nights
3	The Underforge	5	10	Heat accumulation mechanic
4	The Underdark	10	21	Multi-region; truly exhausting
4	Feywild Crossing	8	14	Time distortion (see Section 7)
5	Dragon's Lair	14	30	Multi-wing structure
5	The Abyss Portal	21	∞	Portal destabilizes over time; hard exit pressure

Minimum days = the absolute floor if a player advances aggressively, rests optimally, and encounters no complications.
Maximum days = soft cap. After this, the Threat Clock maxes out and the expedition enters Siege Mode (see Section 8).

---

3. The Expedition Day Cycle

Each real-world day an expedition is active follows this structure:

06:00 — MORNING BRIEFING (TwinBee)
         Status summary: HP, supplies, current location,
         Threat Clock level, any overnight events.

06:00–21:00 — ACTIVE WINDOW
         Player takes actions: advance, search, fight,
         trade, camp, rest, interact with NPCs.
         No hard limit on actions per day — limited by
         resources, HP, and supply consumption.

21:00 — EVENING RECAP (TwinBee)
         Summary of the day: rooms cleared, loot found,
         XP gained, supplies consumed.
         TwinBee delivers a narrative coda.
         Threat Clock advances if player is in a
         dangerous position.

21:00–06:00 — NIGHT PHASE
         Camp triggers if the player has camped.
         Wandering monster check (see Section 6).
         Environmental events possible (Section 7).
         Supply consumption continues passively.

---

4. Supply System

Expeditions consume Supplies — an abstracted resource representing food, water, torches, rope, ammunition, and minor consumables. Supplies are purchased before departure and cannot be restocked mid-expedition unless a Supply Cache is found or a resupply route is established.

4.1 Supply Units

One Supply Unit (SU) represents one day's worth of basic provisions for one character.

Zone Tier	Base SU Cost Per Day	Harsh Conditions Multiplier
1	1 SU/day	×1
2	1.5 SU/day	×1.5
3	2 SU/day	×2
4	3 SU/day	×2.5
5	4 SU/day	×3

Harsh conditions are triggered by: Threat Clock above 60, heat accumulation events, tidal flooding, Feywild time distortion.

4.2 Supply Procurement

Source	SU Yield	Cost	Notes
Thom Krooke standard pack	10 SU	50 coins	Max 3 packs per expedition
Thom Krooke deluxe pack	20 SU	90 coins	Max 1 per expedition
Foraged (Ranger, WIS DC 12)	1d4 SU	Free	Once per day; fails in indoor zones
Supply Cache (dungeon loot)	2d6 SU	—	Random find; not guaranteed
NPC Trader (certain zones)	Variable	Variable	Zone-specific

4.3 Supply Depletion Effects

SU Remaining	Effect
> 25%	Normal operation
10–25%	Rationing: -1 to all rolls from fatigue
1–9%	Severe rationing: -2 to all rolls; no long rests
0	Starvation: -1d4 CON per day; forced extraction if CON reaches 0

4.4 Go Data Model — Supplies

type ExpeditionSupplies struct {
    Current     float32 `json:"current"`      // current SU
    Max         float32 `json:"max"`          // purchased at outset
    DailyBurn   float32 `json:"daily_burn"`   // base rate for this zone tier
    HarshMod    float32 `json:"harsh_mod"`    // multiplier if harsh conditions active
    Foraging    bool    `json:"foraging"`     // Ranger forage attempt used today
}

---

5. Camp System

Camping is the primary mechanism for long rests during an expedition. It is not free — it costs time, supplies, and exposes the player to overnight risk.

5.1 Camp Types

Camp Type	Setup Requirement	Rest Quality	Supply Cost	Night Risk
Rough Camp	Any location	Partial (50% HP, no slots)	+0.5 SU	High
Standard Camp	Safe room (cleared)	Full long rest	+1 SU	Medium
Fortified Camp	Boss-cleared room or cache site	Full long rest + bonus	+2 SU	Low
Base Camp	Expedition Day 3+ in Tier 4–5 zones	Full long rest + extended	+3 SU	Very Low

Fortified Camp bonus: +1d6 HP on wake; TwinBee narrates a peaceful night (rare flavor event).
Base Camp: Establishes a persistent waypoint. Player can fast-travel back to Base Camp in 1 action. Required for Tier 5 zones.

5.2 Camp Placement Rules

• Cannot camp in a room with active enemies.
• Cannot camp in a trap room (even if the trap is disarmed).
• Cannot camp in a Boss room (the room knows it's a boss room).
• Camping in a non-cleared room = Rough Camp regardless of intent.

5.3 Go Data Model — Camp

type CampState struct {
    Active       bool      `json:"active"`
    Type         string    `json:"camp_type"`   // rough, standard, fortified, base
    RoomID       string    `json:"room_id"`
    EstablishedAt time.Time `json:"established_at"`
    NightEvents  []string  `json:"night_events"` // log of overnight occurrences
}

---

6. Wandering Monster System

During the Night Phase, if the player has camped, a wandering monster check fires. The result depends on camp type and Threat Clock level.

6.1 Wandering Monster Table

Roll 1d20 + Threat Clock modifier:

Roll	Outcome
1–5	Peaceful night. TwinBee narrates quiet.
6–10	Signs of passage. No encounter; Threat Clock +2.
11–14	Minor encounter: 1–2 low-CR enemies from zone roster. Player wakes to combat.
15–17	Standard encounter: standard zone enemy group.
18–19	Elite encounter: Elite-tier enemy from zone.
20+	Ambush: enemy has surprise round. Elite-tier. TwinBee delivers a terse, sleep-interrupted narration.

Threat Clock modifier: +1 per 10 points of Threat Clock above 30.

6.2 Rough Camp Night Risk Modifier

Rough Camp adds +3 to all wandering monster rolls.

6.3 Avoiding Night Encounters

• Ranger passive: -2 to all wandering monster rolls while in a wilderness zone.
• Rogue passive: On a roll of 11–14, may attempt a Stealth check (DC 14) to avoid the encounter entirely.
• Fortified Camp: -4 to all wandering monster rolls.

---

7. Zone-Specific Temporal Events

These events fire on specific expedition days, times, or conditions. They are not random — they are scheduled by the zone and announced by TwinBee in advance (vaguely).

7.1 Sunken Temple — Tidal Event (Day 6)

On Expedition Day 6, the tidal cycle peaks. All flooded rooms gain:

• +1d6 cold damage per turn while wading
• Kuo-toa enemies gain +2 AC and +1d4 to attack rolls
• Supply burn doubles for 24 hours (water infiltration)

TwinBee warns on Day 4: "The water is rising. Something about the rhythm of it has changed."
TwinBee warns on Day 5: "Tomorrow the temple will be fully claimed by the tide. Plan accordingly."

If the player has reached the Boss room before Day 6: no event fires.

7.2 Haunted Manor — Nightly Reset (Every 3 In-Game Nights)

Every third night in the Manor, non-boss rooms respawn one enemy (not a full reset — one enemy per room, chosen from zone roster). This represents the house reasserting itself.

TwinBee notes on Night 2: "The house has been quiet. That will not last."
On Night 3 morning: "Overnight, something moved back in. Several somethings, actually."

7.3 The Underforge — Heat Accumulation

Each day spent in the Underforge adds 1 Heat Stack (max 10). Effects:

Heat Stacks	Effect
1–3	Flavor only ("the air shimmers")
4–6	+1d4 fire damage at start of each combat round
7–9	Disadvantage on CON saves; Supply burn +50%
10	Exhaustion: -2 to all rolls; forced 24hr rest or extraction

Heat stacks reduce by 2 per long rest in a Fortified Camp. Full extraction resets all stacks.

7.4 The Feywild Crossing — Time Distortion

Time in the Feywild is unreliable. Each day the player enters an Exploration Room, roll 1d6:

Roll	Time Effect
1–2	Normal day passes
3–4	Half-day: only 0.5 SU consumed; next room generates instantly
5	Double-day: 2 SU consumed; an extra wandering monster check fires
6	Time Loop: player re-enters the same room (new enemies; loot already taken)

TwinBee tracks time distortion and reports it in the Morning Briefing with increasing bewilderment.

7.5 Dragon's Lair — Awareness Pulses

Infernax sleeps lightly. Every 3 days, an Awareness Pulse fires:

• Kobold patrols increase by 1 enemy per active room
• Threat Clock +10
• TwinBee delivers an Awareness Pulse narration (see twinbee_expedition_flavor.go)

On Day 14: Infernax wakes. If the player has not reached the Boss room by Day 14, Infernax begins active hunting — wandering monster checks occur every 6 hours and may produce a Dragon encounter (CR 15 young dragon proxy) until the player reaches the final chamber.

7.6 The Abyss Portal — Destabilization

The portal grows unstable over time. Each day, Portal Instability increases by 5 (starts at 0, max 100).

Instability	Effect
0–20	Normal operations
21–40	Psychic pressure: -1 to WIS rolls
41–60	Reality warps: rooms occasionally shift order
61–80	Demon surges: wandering monster check every 12 hours
81–99	Unraveling: -2 to all rolls; Supply burn doubles
100	Collapse: player is forcibly extracted; expedition fails; portal requires a new event to reopen

Instability is reduced by 10 for each major story objective completed in the zone.

---

8. The Threat Clock

The Threat Clock (0–100) represents how aware the zone's faction has become of the player's presence. It is the dungeon's version of stealth — the longer you're here, the more organized the opposition becomes.

8.1 Threat Clock Modifiers

Event	Threat Change
Combat in a new room	+5
Enemy killed before raising alarm	+0
Enemy escapes combat	+10
Player uses loud ability (Fireball, Thunderwave)	+8
Rogue uses Stealth to move between rooms	-3
Long rest in Fortified Camp	-5
Boss defeated	-20
Day passes in zone	+3
TwinBee Mood: Wrathful	+5/day additional
TwinBee Mood: Elated	-3/day

8.2 Threat Clock Thresholds

Level	Threshold	Effect
Quiet	0–20	No modifications. TwinBee describes an unaware zone.
Stirring	21–40	Enemies in uncleared rooms gain +1 to Perception; wandering monster +1
Alert	41–60	Enemies gain +2 AC; wandering monster +2; reinforcements possible
Hostile	61–80	All enemies have initiative advantage; room traps re-arm
Siege	81–100	Siege Mode (see Section 8.3)

8.3 Siege Mode

When Threat Clock hits 100, the zone enters Siege Mode:

• All rooms with cleared enemies respawn one enemy (once)
• Boss gains +20 HP and Legendary Resistance +1
• Supply burn doubles
• No short rests possible (too dangerous)
• TwinBee delivers a Siege Mode narration and does not sugarcoat it
• Siege Mode cannot be reduced — it is the dungeon's final form

TwinBee begins warning at Threat Clock 70:
"They know you're here. Not a suspicion anymore. A certainty. The question now is whether you finish before they organize."

8.4 Go Data Model — Threat Clock

type ThreatClock struct {
    Level       int       `json:"level"`        // 0–100
    SiegeMode   bool      `json:"siege_mode"`
    LastUpdated time.Time `json:"last_updated"`
    Events      []ThreatEvent `json:"events"`
}

type ThreatEvent struct {
    Timestamp time.Time `json:"timestamp"`
    Delta     int       `json:"delta"`
    Reason    string    `json:"reason"`
}

---

9. Expedition State Model

type Expedition struct {
    ID              string            `json:"id"`
    PlayerID        string            `json:"player_id"`
    ZoneID          string            `json:"zone_id"`
    StartDate       time.Time         `json:"start_date"`
    CurrentDay      int               `json:"current_day"`
    Status          string            `json:"status"`    // active, extracting, complete, failed
    CurrentRegion   string            `json:"current_region"`
    CurrentRoomID   string            `json:"current_room_id"`
    RoomsCleared    []string          `json:"rooms_cleared"`
    BossDefeated    bool              `json:"boss_defeated"`
    Supplies        ExpeditionSupplies `json:"supplies"`
    Camp            *CampState        `json:"camp"`
    ThreatClock     ThreatClock       `json:"threat_clock"`
    TemporalStack   int               `json:"temporal_stack"`  // zone-specific (heat, instability, etc.)
    Log             []ExpeditionEntry `json:"log"`
    LootCollected   []string          `json:"loot_collected"`
    XPEarned        int               `json:"xp_earned"`
    GMMood          int               `json:"gm_mood"`
    LastActivity    time.Time         `json:"last_activity"`
}

type ExpeditionEntry struct {
    Day       int       `json:"day"`
    Timestamp time.Time `json:"timestamp"`
    Type      string    `json:"type"`    // action, combat, rest, event, narrative
    Summary   string    `json:"summary"`
    Flavor    string    `json:"flavor"`  // TwinBee line for this entry
}

---

10. Extraction

Extraction is leaving the zone before completion — intentionally or by force.

10.1 Voluntary Extraction

Command: !extract

• Player may extract at any time from any cleared room.
• Extraction costs 1 in-game day (finding the way out).
• Player keeps all loot and XP earned to that point.
• Expedition marked as Incomplete — can be resumed (see Section 10.3).
• TwinBee delivers an extraction narration.

10.2 Forced Extraction

Triggered by: HP reaching 0, supplies reaching 0, Abyss Portal collapse.

• Player loses 20% of coins earned during expedition (chaos tax).
• All loot carried out is kept.
• Expedition marked as Abandoned.
• Cannot be resumed — must restart.
• Threat Clock resets to 20 on re-entry (zone remembers you, but time has passed).
• TwinBee delivers a forced extraction narration (respectful; never mocking).

10.3 Expedition Resume

Voluntarily extracted expeditions can be resumed within 7 real days:

• Resumes from the last cleared room.
• Supplies must be repurchased (what was carried is gone — you extracted).
• Threat Clock resumes at extraction value.
• Zone-specific temporal stacks (Heat, Instability) resume at extraction value.
• TwinBee delivers a return narration: "Back again. TwinBee noted the door. TwinBee notes it opening."

After 7 days, the expedition expires and must restart.

---

11. Multi-Region Zones (Tier 4–5)

The Underdark, Dragon's Lair, and Abyss Portal are too large for a single dungeon map. They are divided into Regions, each functioning as a sub-dungeon.

11.1 Region Structure

Each Region contains:

• Its own room sequence (Entry → Exploration → Trap → Exploration → Elite → Boss)
• A Region Boss (not the Zone Boss — a mid-tier milestone)
• A potential Base Camp site (unlocked after clearing Region Boss)
• Region-specific enemies (subset of zone roster)
• Region-specific loot table

11.2 Region Progression

Zone	Regions	Region Boss
The Underdark	Surface Tunnels → Drow Outpost → Illithid Warren → The Deep Throne	Drow Elite Captain → Mind Flayer Elder → Ilvaras Xunyl (Zone Boss)
Dragon's Lair	Kobold Warrens → Drake Pens → The Vault → Infernax's Chamber	Kobold Warchief → Elder Drake → Infernax (Zone Boss)
The Abyss Portal	Outer Rift → Demon Assembly → The Warden's Post → The Tear	Vrock Commander → Nalfeshnee → Belaxath (Zone Boss)

11.3 Region Transitions

Moving between regions costs 1 full in-game day of travel. TwinBee narrates the transition with specific regional flavor. Supply burn applies during travel. Wandering monster check fires once during transit.

11.4 Go Data Model — Region

type ExpeditionRegion struct {
    ID            string    `json:"id"`
    ZoneID        string    `json:"zone_id"`
    Name          string    `json:"name"`
    Order         int       `json:"order"`
    Cleared       bool      `json:"cleared"`
    BossDefeated  bool      `json:"boss_defeated"`
    BaseCampSite  bool      `json:"base_camp_site"`
    EnemySubset   []string  `json:"enemy_subset"`
    LootTable     []LootEntry `json:"loot_table"`
    FlavorRef     string    `json:"flavor_ref"`
}

---

12. TwinBee Daily Briefing & Recap Format

12.1 Morning Briefing (06:00)

🎭 TwinBee — Morning Briefing, Day [N]

📍 Location:    [Zone Name] — [Region if applicable] — [Room description]
❤️  HP:          [current] / [max]
🎒 Supplies:    [SU remaining] / [SU max] ([days remaining estimate])
⏰ Threat:      [Threat Clock level] — [Threshold name]
🌡️  [Zone stack]: [Heat/Instability/Time value if applicable]

[Overnight events, if any — TwinBee narrates what happened while you slept]

[TwinBee morning flavor line — see twinbee_expedition_flavor.go]

Available actions: [!advance] [!search] [!camp] [!rest] [!extract] [!status]

12.2 Evening Recap (21:00)

🎭 TwinBee — Evening Recap, Day [N]

Today's progress:
  Rooms cleared:  [N]
  Enemies defeated: [N]
  Loot found:     [item list or "nothing notable"]
  XP earned:      [N]
  Supplies used:  [N SU]

[TwinBee evening narrative — see twinbee_expedition_flavor.go]

[Camp prompt if player hasn't camped: "You should rest. The dungeon does not."]

---

13. Expedition Milestones & Bonus Rewards

Milestones reward players who engage with the expedition's full arc rather than rushing.

Milestone	Trigger	Reward
First Night	Survive Night 1	+50 XP; TwinBee delivers a "you're still here" line
Cartographer	Search every room before advancing	Bonus loot roll in next Elite room
Patient Zero	Complete expedition without Threat Clock above 50	+10% XP bonus on zone complete
Survivalist	Complete Tier 3+ expedition with no forced extraction	Unique title + cosmetic item
Week One	Expedition Day 7 survived	+200 XP; Thom Krooke discount next visit
Two Weeks	Expedition Day 14 survived	+500 XP; permanent +1 to primary class stat
The Long Game	Complete a Tier 5 zone	Legendary item guaranteed; TwinBee delivers a personal note

---

14. Expedition Commands Reference

Command	Description
!expedition start <zone>	Begin a new expedition (opens supply purchase flow)
!expedition status	Full expedition status summary
!expedition log	Last 5 expedition log entries with TwinBee narration
!advance	Move to next room (costs time; triggers encounters)
!retreat	Return to previous cleared room
!search	Search current room (Perception/Investigation check)
!camp <type>	Establish camp (rough / standard / fortified / base)
!rest short	Short rest at current location
!rest long	Long rest (requires Standard camp or better)
!supplies	Check supply status and daily burn rate
!threat	Check Threat Clock level and current threshold
!extract	Begin voluntary extraction
!resume	Resume a previously extracted expedition
!map	Display expedition progress as ASCII region/room map

---

15. Implementation Phases — Expedition System

Phase E1 — Core Infrastructure

• Expedition struct and DB schema
• Real-time day cycle engine (06:00/21:00 triggers)
• Morning Briefing and Evening Recap generation
• !expedition start, !expedition status commands
• Supply system (procurement, depletion, effects)
• Basic camp system (rough and standard)

Phase E2 — Threat Clock & Night Phase

• Threat Clock state machine
• Wandering monster system
• Night phase event resolution
• Siege Mode implementation
• Fortified Camp and Base Camp

Phase E3 — Zone Temporal Events

• Tidal Event (Sunken Temple)
• Nightly Reset (Haunted Manor)
• Heat Accumulation (Underforge)
• Time Distortion (Feywild)
• Awareness Pulses (Dragon's Lair)
• Portal Destabilization (Abyss Portal)

Phase E4 — Multi-Region Zones

• Region system and region boss structure
• Region transition (travel day, supply burn, encounter)
• Base Camp as persistent waypoint
• Underdark, Dragon's Lair, Abyss Portal region maps

Phase E5 — Extraction & Resume

• Voluntary extraction flow
• Forced extraction flow
• Expedition resume (7-day window)
• Expedition log persistence

Phase E6 — Milestones & Polish

• Milestone tracking and reward delivery
• twinbee_expedition_flavor.go full population (briefings, recaps, event narrations)
• ASCII map renderer (multi-region aware)
• Pete bot expedition update posts (daily highlights for Matrix room)

---

End of Expedition System Document. Reference alongside all companion docs in Claude Code sessions.