docs: daytime nap system design spec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 02:55:12 +00:00
parent 49016073ad
commit f0b8fea4f1
1 changed files with 58 additions and 0 deletions
@@ -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