diff --git a/docs/superpowers/specs/2026-03-11-daytime-nap-design.md b/docs/superpowers/specs/2026-03-11-daytime-nap-design.md new file mode 100644 index 0000000..8ce7644 --- /dev/null +++ b/docs/superpowers/specs/2026-03-11-daytime-nap-design.md @@ -0,0 +1,58 @@ +# Daytime Nap System + +## Problem + +NPCs that emergency-sleep during the day (energy < 20) currently sleep all the way to energy 85-100, shifting their circadian rhythm. They wake fully rested mid-day and won't be tired again until well into the next day, drifting out of sync with the day/night cycle. + +## Solution + +When sleeping during daytime, treat it as a **nap**: calculate just enough energy to reach nightfall with a small buffer, then wake immediately. This keeps NPCs synchronized — they'll arrive at nightfall with low-but-manageable energy and naturally trigger voluntary night sleep. + +## Nap Target Calculation + +``` +remainingDayTicks = (SLEEP_NIGHT_START - gameTime) * cycleTicks +energyNeeded = remainingDayTicks * ENERGY_DECAY_PER_TICK * constitutionMultiplier +napTarget = ENERGY_THRESHOLD + energyNeeded + NAP_BUFFER +``` + +- `NAP_BUFFER`: ~15 energy. NPCs arrive at nightfall around 35 energy — above the 20 emergency threshold, below the 60 voluntary night sleep threshold. +- `constitutionMultiplier`: `1 - (con - 10) * 0.03` (same formula used in needsDecaySystem). + +## Wake Logic + +In the sleep wake check (npcBrainSystem.ts): + +1. Determine if this is a **daytime sleep** (gameTime < SLEEP_NIGHT_START). +2. Calculate nap target. +3. **Guard**: if napTarget >= SLEEP_VOLUNTARY_ENERGY_THRESHOLD (60), treat as normal full sleep (too close to nightfall for a nap to matter — avoid wake-then-immediately-re-sleep). +4. **Daytime nap**: wake immediately when energy >= napTarget (clean cutoff, no probabilistic ramp). +5. **Night or guarded**: use existing probabilistic wake (85-100 range). + +## Edge Cases + +- **Night arrives while napping**: switch to normal night sleep wake logic (85-100 probabilistic). The NPC was exhausted enough to sleep into night — that's fine. +- **Close to nightfall**: napTarget would be low (~25-30), which is below 60, so the guard triggers normal full sleep. No silly wake-then-re-sleep. +- **Constitution variation**: high-CON NPCs decay slower, so shorter naps. Low-CON NPCs need more banked energy, so longer naps. Natural. + +## Recovery Rate + +Same as normal sleep (0.048/tick). No change. A nap is just a shorter sleep. + +## Constants + +- New: `NAP_BUFFER = 15` in shared/src/constants.ts. +- All other sleep constants unchanged. + +## Files Changed + +- `shared/src/constants.ts` — add NAP_BUFFER +- `server/src/systems/npcBrainSystem.ts` — modify sleep wake logic + +## What Stays the Same + +- Sleep entry conditions (emergency < 20, voluntary night < 60) +- Recovery rate (0.048/tick) +- Hunger/thirst decay reduction during sleep +- Social interaction protection +- Thought system sleep handling