# Gameplay Enrichment Plan

> Generated: 2026-02-07 | Status: Proposal

## Current State Assessment

The game has **excellent mechanical depth** — 30 careers, 100+ activities, 13 health conditions, 48 shop items, 44 achievements, sophisticated death/aging mechanics. The framework is solid.

What's missing is **narrative depth**: the moment-to-moment experience feels repetitive because daily schedules are rigid, events repeat without variation, and many life moments that players would expect (school drama, workplace politics, holidays, friend hangouts) simply don't exist yet.

**The character lives a mechanically correct life, but not an interesting one.**

---

## Dual-Mode Design: The Core Framework

The game has two fundamentally different play modes, and **every event must be designed with both in mind**.

### Realtime Mode — "Living With Your Character"

- **Speed**: `5000ms` or `1000ms` per game-minute (slowest two speeds)
- **Purpose**: The character's day unfolds alongside the player's real day. Small moments trickle in as push notifications to bring the player back into the app.
- **Feel**: Checking in on a friend. "What's my character up to?" Ambient, low-friction engagement.
- **Event cadence**: A few events per real-world hour. Not overwhelming.
- **Examples**: "Alex texted asking if you want to hang out tonight", "Your mom called to check in", "You're craving coffee — stop by a cafe?", "It's starting to rain outside"
- **Key mechanic**: Push notifications for interesting moments. Player taps notification → opens app → sees what's happening → makes a quick choice → closes app.

### Fast Mode — "Progressing Through Life"

- **Speed**: `500ms` or faster (speeds 3-6)
- **Purpose**: The player is actively in-app, speeding through time to hit milestones, advance careers, age up, experience life events. This is where "the game" lives.
- **Feel**: Watching a life unfold. Decisions matter. Progress is visible.
- **Event cadence**: Only meaningful events — milestones, decisions, consequences. No ambient noise.
- **Examples**: "You graduated high school!", "Promotion offer at work", "Your girlfriend proposed", "You've been diagnosed with diabetes"
- **Key mechanic**: Events that pause the game (questionEvents) are fine here because the player is watching. Ambient chatter would be unbearable at 50x speed.

### The Filter Rule

Every event gets tagged with a mode:

| Tag | Fires in Realtime | Fires in Fast | Description |
|-----|:---:|:---:|-------------|
| `realtime` | Yes | **No** | Ambient flavor, check-ins, small moments. Would clutter fast mode. |
| `fast` | Yes (rare, time moves slowly) | Yes | Milestones, decisions, consequences. Always worth showing. |
| `both` | Yes | Yes | Works at any speed. Most existing events are this. |

**Implementation**: `player.gameSpeed` is already tracked. The event dispatcher checks speed before firing:
```
const isRealtimeSpeed = player.gameSpeed >= 1000;  // slowest two speeds
if (event.mode === 'realtime' && !isRealtimeSpeed) return; // skip in fast mode
```

### Push Notification Architecture (Realtime Mode)

The iOS app already sends `deviceToken` to the server and stores it on the player. What's missing:

1. **Server-side push sender** — APNS integration to send notifications when the app is backgrounded
2. **Notification triggers** — Realtime events that fire when the player isn't actively looking at the app
3. **Smart throttling** — Max 3-5 notifications per real-world hour. Don't annoy the player.
4. **Deep links** — Notification tap opens the app to the relevant screen (event modal, chat, etc.)

This is a **Sprint 2 prerequisite** — without push notifications, realtime mode has no way to bring players back.

---

## Enrichment Items — Ranked by Impact

### Tier 1: High Impact / Moderate Effort

These target the longest gameplay segments (school = 12 years, work = 40+ years) and the most frequent player touchpoints (daily schedule, social interactions).

---

#### 1. School Life Events
**Why**: Ages 5-17 span 12+ in-game years — currently the most content-starved period.

**Realtime events** (ambient, notification-worthy):
- "You got a B+ on your history quiz" (small notification)
- "Your teacher complimented your essay today"
- "There's a rumor going around school about you..."
- "Lunch break — you sat with a new group today"
- "Practice ran late. Coach says the team is looking strong."

**Fast mode events** (milestones, decisions):
- Report card day (quarterly) — GPA reveal with consequences
- Honor roll / academic probation notifications
- School dance invitation → accept/decline (question event)
- Prom (senior year) → ask someone / go alone / skip
- Graduation ceremony → valedictorian speech choice
- Detention/suspension triggers (low focus + bad behavior)
- Science fair / debate tournament → compete or skip
- College acceptance/rejection letters

**Backend scope**: New event files in `server/src/events/education/`, age-gated triggers
**iOS scope**: Existing EventModalView — no new UI needed

---

#### 2. Holiday & Birthday System
**Why**: Every player expects their character's birthday to matter. Holidays break up identical weeks.

**Realtime events**:
- "Happy Birthday! Your mom left a present on the kitchen table"
- "It's snowing outside — first snow of the year!"
- "Your coworker brought Halloween candy to the office"
- "New Year's Eve — any resolutions?"

**Fast mode events**:
- Birthday milestone choices (16th: car or party? 21st: bar or dinner? 50th: midlife reflection)
- Holiday family gatherings with drama/affinity changes (Thanksgiving dinner, Christmas morning)
- Valentine's Day romance event (partnered) or loneliness event (single)
- New Year's resolution → choose temporary stat boost for 30 days

**Backend scope**: Birthday logic in `processDayTick` (check `ageDays % 365`), holiday events gated on `dayOfYear`
**iOS scope**: Optional special event modal styling for holidays

---

#### 3. Friend Hangouts & Social Depth
**Why**: Relationships beyond romance feel hollow. Friends exist but never initiate anything.

**Realtime events** (the #1 opportunity for pull-back notifications):
- "Alex: hey, wanna grab coffee after work?" → accept/decline
- "Your friend group chat is blowing up about weekend plans"
- "Sarah shared a meme with you" (affinity +1, no action needed)
- "Jordan is going through a tough time and wants to talk"
- "You haven't talked to Marcus in a while. Check in?"

**Fast mode events**:
- "Became best friends with Alex" milestone
- Friend betrayal / trust broken → forgive or cut off
- Friend introduces you to someone (new relationship spark)
- Group trip event (costs money, boosts multiple affinities)
- Being excluded from a group activity (social consequences)

**Backend scope**: New `server/src/events/social/friendships.ts`, friend-event scheduler in hourly tick
**iOS scope**: Existing messaging and event UIs

---

#### 4. Daily Schedule Variety & Random Disruptions
**Why**: Every weekday is identical. Real life has variety.

**Realtime events** (make each day feel different):
- "It's raining — brought an umbrella?"
- "Your car won't start this morning"
- "Surprise — your friend stopped by with lunch"
- "You found $20 on the sidewalk"
- "A stray cat followed you home"

**Fast mode events**:
- Doctor appointment reveals health condition
- Snow day cancels school (kids celebrate)
- Power outage → whole day disrupted
- Weekend trip proposal from friend/partner (costs money, boosts happiness)

**Both modes**:
- Weekend activities: park, family visit, movie marathon, house cleaning (not just "relax at home")
- Evening variety: cook dinner, go for a walk, call a friend, read a book
- Sleep quality events: nightmares (if stressed), great sleep (if exercised)

**Backend scope**: Modify `intradayActivity.ts` to inject random events, add weather state
**iOS scope**: Enhanced messages show automatically via existing location/activity display

---

### Tier 2: Strong Impact / Moderate Effort

---

#### 5. Workplace Events & Career Flavor
**Why**: Work occupies 8+ hours/day for 40+ years. Currently it's just a performance number.

**Realtime events**:
- "Coffee machine chat with Sarah from accounting"
- "Your boss seems stressed today — stay out of the way?"
- "Lunch invitation from a coworker you don't know well"
- "Deadline approaching — put in extra hours tonight?"

**Fast mode events**:
- Performance review (quarterly) with raise/warning
- Promotion ceremony / getting passed over
- Layoff notice with severance
- Counter-offer from competitor
- Starting your own business (high risk/reward question chain)

---

#### 6. Health Events & Medical System
**Why**: Health conditions exist mechanically but have no narrative weight.

**Realtime events**:
- "You're feeling unusually tired today"
- "Time for your annual checkup — schedule it?"
- "Great workout! You ran your fastest mile yet"
- "You've been stressed lately. Maybe take a mental health day?"

**Fast mode events**:
- Diagnosis reveal (diabetes, heart disease, etc.) with treatment choice
- Medical emergency → hospital trip (costs money + time off work)
- Therapy arc: costs money, gradually improves happiness over weeks
- Pregnancy trimester events, baby shower, delivery

---

#### 7. Family Dynamics
**Why**: Family members are generated but rarely do anything.

**Realtime events**:
- "Mom called to check in on you"
- "Your sibling shared a funny memory from childhood"
- "Dad needs help moving furniture this weekend"
- "Your kid brought home a drawing from school"

**Fast mode events**:
- Parent gets sick / passes away → inheritance, grief
- Sibling's wedding → attend, be in party, or skip
- Child's first words / first steps / first day of school
- Teenager rebellion → strict or lenient parenting choice
- Family secret revealed → confrontation or acceptance

---

#### 8. Event Text Variations
**Why**: Even great events feel stale when you see identical text 5 times.

**Both modes**:
- 3-5 text variants per event (same mechanical outcome, different flavor)
- Context-aware text referencing location, time of day, weather
- Personality-influenced descriptions (extrovert vs introvert)
- Example: Hunger → "Your stomach growls loudly" / "You start thinking about what's in the fridge" / "A coworker's lunch smells amazing"

**Backend scope**: Text variant arrays with random selection, template `{variable}` substitution
**iOS scope**: No changes needed

---

### Tier 3: Nice-to-Have / Higher Effort

---

#### 9. Financial Depth
- Recurring expenses (rent, utilities, subscriptions)
- Investment system (stocks with random returns, savings interest)
- Debt system (student loans, mortgage, credit card debt)
- Economic events (recession → layoff risk, boom → salary increase)

#### 10. Multi-Step Quest Chains
- Story arcs spanning multiple days/weeks
- "Plan your wedding" → venue → caterer → invites → ceremony
- "College application season" → SAT prep → essays → campus visits → results

#### 11. Cross-System Synergies
- Photography hobby → journalism career unlock
- Debate club → lawyer career bonus
- Exercise habit → health condition prevention

#### 12. Aging & Late-Life Content
- Mid-life crisis event chain (ages 40-50)
- Retirement planning (age 55+)
- Grandparent events
- End-of-life: will, final gathering, life reflection summary

---

## Implementation Priority Matrix

| Item | Player Impact | Dev Effort | Mode Focus | Sprint |
|------|:---:|:---:|:---:|:---:|
| **Push notification infra** | ★★★★★ | ★★☆ | Realtime prerequisite | Sprint 2 |
| **Event mode tagging system** | ★★★★★ | ★☆☆ | Both | Sprint 2 |
| 1. School Life Events | ★★★★★ | ★★☆ | Both | Sprint 2 |
| 2. Holidays & Birthdays | ★★★★★ | ★★☆ | Both | Sprint 2 |
| 3. Friend Hangouts | ★★★★☆ | ★★☆ | Realtime-heavy | Sprint 2 |
| 4. Schedule Variety | ★★★★☆ | ★★★ | Both | Sprint 2 |
| 5. Workplace Events | ★★★★☆ | ★★☆ | Both | Sprint 3 |
| 6. Health Events | ★★★☆☆ | ★★★ | Both | Sprint 3 |
| 7. Family Dynamics | ★★★☆☆ | ★★☆ | Realtime-heavy | Sprint 3 |
| 8. Event Text Variations | ★★★★☆ | ★★☆ | Both | Sprint 2-3 |
| 9. Financial Depth | ★★☆☆☆ | ★★★ | Fast | Sprint 4 |
| 10. Quest Chains | ★★★☆☆ | ★★★★ | Fast | Sprint 4 |
| 11. Cross-System Synergies | ★★☆☆☆ | ★★★ | Fast | Sprint 4 |
| 12. Late-Life Content | ★★☆☆☆ | ★★☆ | Fast | Sprint 4 |

---

## Recommended Sprint 2 Scope

### Foundation Work (must happen first)
1. **Event mode tagging system** — Add `mode: 'realtime' | 'fast' | 'both'` to event definitions, add speed check to event dispatcher
2. **Push notification infra** — APNS integration on server, notification triggers when app is backgrounded, smart throttling (max 4/hour), deep links back into app

### Content (builds on foundation)
3. **School Life Events** — 15-20 new events (mix of realtime ambient + fast milestones)
4. **Holidays & Birthdays** — 8-10 holiday events + birthday system
5. **Friend Hangouts** — 10-12 friend-initiated events (mostly realtime — these are the #1 pull-back opportunity)
6. **Schedule Variety** — Random disruptions, weekend activities, evening variety

### What This Gets Us
- **Realtime mode becomes compelling**: Your character's friends text you, weather changes, small moments happen. Push notifications bring you back 3-4 times a day.
- **Fast mode stays clean**: Only milestones, decisions, and consequences. No "your friend sent a meme" cluttering a 50x-speed playthrough.
- **Days feel different**: Random disruptions, weather, friend invites, and schedule variety break the repetition loop.
- **School years have content**: The 12-year content desert gets filled with classroom events, dances, competitions, and social drama.

**Estimated scope**: Event mode system + push infra + ~50-60 new event scenarios across 8-10 new files.

All content events work within the existing event system and iOS event modal — **no new UI screens required** (push notifications need iOS notification handling, which AppDelegate already scaffolds).