🌫 Aether — Body Stats & Life-Sim Expansion

Living design document. The canonical reference for the Aether (formerly Life Sim) feature. Aether v1.0.10 is SHIPPED — skeleton (1.0.0), real-time decay + body panel UI (1.0.1), 5 activities (drink/eat/sleep/work/travel) with AI judge (1.0.2), console-error cleanup (1.0.3), stat → XP multiplier (1.0.4), character mood gate (1.0.5), age-gated intimate stats (1.0.6, since simplified in 1.0.10), Workshop Publish toggle (1.0.7), system prompt injection (1.0.8), registry-aware age gate (1.0.9), and simplified age gate (1.0.10: just `age >= 18`, removed the persona pattern-matcher — too many false positives like "demon girl", German "Mädel"/"Fräulein"). The species registry is still loaded for body function defaults and breed dropdowns, but the gate doesn't consult it. Phase 3 polish (cinema/beach/disco activities) is the next planned step. Pack ships as an opt-in expansion; main app version is 4.0.0 (Aether v1.0.10 has independent semver and uses the 1.0.x patch line).

§1. Vision & Design Principles

The Life Sim is a maintenance-and-modifier layer that lives underneath the existing chat. The chat stays the primary experience — the Life Sim adds depth, urgency, and a sense of physical presence for the user, and (optionally) a body for the character.

Three design pillars:

1. Stat decay. Body needs degrade in real time. A user who logs in once a day plays differently than one who logs in every hour — but neither is punished; the system is forgiving (0.2× floor on the multiplier).
2. Persona-aware actions. Eating, drinking, traveling, etc. are scored by the AI against the character's persona. Peony (succubus) and a vampire character would react very differently to the same food choice. Score: 1-20.
3. Modifier synergy. The body stats, the existing Reputation (0-100), and the existing relationship XP (0-2150) all compose multiplicatively. No stat governs alone; everything stacks.

Compatibility promise: the Life Sim is purely additive. Existing rooms, users, and chats work unchanged. Default values for new rows match today's behavior (stats start neutral, no action happens unless the user opts in).

§2. Phased Rollout

Version	Scope	Status
4.0.0	Player body (3 stats: stamina, food, drink), home-only activities (sleep, eat, drink), persona-aware scoring 1-20, character mood (derived, hidden until CLOSE FRIEND), stat → XP/Reputation multiplier, system prompt injection, server tick decay, lazy reconciliation, 18+ community poll	DOCUMENTED
4.1.0	Fainting mechanic (stamina + food + drink all 0 → user faints, OC narrates the skip), more stats (hygiene, bladder, fun, social, stress, health), activity_log table for dailies	PLANNED
4.2.0	Locations (work, restaurant, cinema, disco, beach, park, gym, mall), travel action with time cost, money column, work activity earns income, full activities grid per location	PLANNED
4.3.0	Full character body (separate hunger, energy, health, mood rows), character activities, character-side prompt injection expands	PLANNED
4.4.0	Intimate stats (arousal, sensuality, intimacy, desire) — gated behind CLOSE FRIEND/INTIMATE tiers, pending community poll results. Multi-character rooms, NPC schedules, item inventory, season/weather, dynamic macro resolver. See the 18+ community input section below.	FUTURE

§3. Data Model

users ──┬── user_stats (per user, per room) ── room
        ├── messages ── room
        └── relationships ── room ── character_mood
                              └── character_food_prefs

user_stats — player body, one row per (user, room)

Column	Type	Default	Notes
user_id	INTEGER	—	FK → users.id, part of PK
room_id	INTEGER	—	FK → rooms.id, part of PK
stamina	INTEGER	90	0 = exhausted, 100 = fresh
food	INTEGER	80	0 = starving, 100 = full
drink	INTEGER	80	0 = dehydrated, 100 = quenched
mood	INTEGER	70	derived; stored for stable-mood freeze
last_action_comment	TEXT	NULL	Comment from the last eat/drink, injected into the next system prompt then cleared
last_action_at	TEXT	NULL	ISO timestamp; used to track comment age
last_updated	TEXT	—	ISO timestamp; tick & lazy decay use this

character_mood — derived mood, one row per room

Column	Type	Default	Notes
room_id	INTEGER	—	PK, FK → rooms.id
mood	INTEGER	70	derived from persona context; updated lazily
last_updated	TEXT	—	ISO timestamp

character_food_prefs — per-character eating preferences (optional, defaults to persona-only)

Column	Type	Default	Notes
room_id	INTEGER	—	FK → rooms.id, part of PK
kind	TEXT	—	'food' or 'drink', part of PK
item	TEXT	—	e.g. "rare steak", "water", part of PK
weight	INTEGER	1	Higher = stronger preference

activity_log — every action the user takes (deferred to 4.1.0)

Column	Type	Default	Notes
id	INTEGER	autoinc	PK
user_id	INTEGER	—	FK → users.id
room_id	INTEGER	—	FK → rooms.id
activity	TEXT	—	'sleep' | 'eat' | 'drink' | (later: 'work' | 'cinema' | …)
location	TEXT	'home'	For 4.0.0 always 'home'
money_delta	INTEGER	0	For 4.2.0+
created_at	TEXT	—	ISO timestamp

Indexes (4.0.0): the two primary keys already cover the hot paths. If read latency becomes a concern, add CREATE INDEX idx_user_stats_updated ON user_stats(last_updated) for the tick sweep.

§4. Decay & Time Model

Decay rates (per real hour)

Stat	Rate	Direction	Notes
stamina	−1 / hour	↓ drains	Slowest. Decays faster if the user is very active (deferred to 4.1.0).
food	−2 / hour	↓ drains	Average. Eating at a restaurant resets this for a few hours.
drink	−3 / hour	↓ drains	Fastest. The body needs water more often than food.

Tick architecture

• Server tick every 60s. A single setInterval iterates all user_stats and character_mood rows, applies decay proportional to elapsed time since the last tick, and updates last_updated.
• Lazy reconciliation on read. In case the server restarts mid-tick or is offline for hours, the GET /api/rooms/:id/stats endpoint applies any missed decay on demand before returning the row. This is the same pattern the Reputation system already uses.
• No background job / cron. The tick lives in the same Node process as the chat server. PM2 restarts cleanly. If user count grows 100×, swap the in-process tick for a job queue (TODO comment in code).
• Performance. At today's scale (3 users, 7 rooms) the tick touches ~10 rows. Worst case: 1 SQLite UPDATE per row, all in one transaction, well under 1ms.

Stabilization rule (mood freeze)

Worked example: 4 hours of inactivity

Initial state (t = 0):
  stamina = 90, food = 80, drink = 80, mood = 70

After 4 hours of no activity:
  stamina: 90 − (1 × 4) = 86
  food:    80 − (2 × 4) = 72
  drink:   80 − (3 × 4) = 68

Mood check: drink (68) is now below 75 → stability broken.
  mood = clamp(50 + (86−50)/5 + (72−50)/5 + (68−50)/5, 0, 100)
       = clamp(50 + 7.2 + 4.4 + 3.6, 0, 100)
       = clamp(65.2, 0, 100)
       = 65

State at t = 4h:
  stamina = 86, food = 72, drink = 68, mood = 65

§5. Activities Matrix

Phase 1 / 2 / 3 / 4 scope (all at home)

Activity	Time (real min)	Money	Stat effects
sleep	480	0	stamina +60, food +20, drink +20
eat	60	0	food += AI score (1-20, soft cap at 5 if unbelievable)
drink	5	0	drink += AI score (1-20, soft cap at 5 if unbelievable)

Deferred to 4.2.0 (locations, travel, economy)

Activity	Location	Time (min)	Money	Stat effects
work	work	240	+120	energy −25, stress +15, hunger +15, mood −5
eat (restaurant)	restaurant	60	−40	food += AI score, mood +5
cinema	cinema	120	−25	fun +30, mood +10, energy −5
disco	disco	180	−35	fun +40, social +25, energy −15, stress −20
beach	beach	120	0	fun +20, mood +15, energy −5, hygiene −10
travel	any → any	15-20	0	energy −2/3, location changes immediately

§6. Body Stats and Chat XP

Status as of Aether 1.0.11 (2026-06-29): the stat → XP coupling was removed. The v1.0.4 geometric-mean dampener that scaled the chat XP delta by the user's body stats is gone. Body stats are now RP cues only — they feed the OC's prompt-injection (§5) and the room's character_mood derivation, but the chat XP math no longer reads them.

Current XP formula (1.0.11+)

sentimentVal  = -5..+5            (from the AI judge, unchanged)
baseline      = 1                 (v3.2.0, sacred)
repMultiplier = 1..6              (v3.8.0, unchanged)
delta         = round((baseline + sentimentVal) × repMultiplier)
newScore      = clamp(score + delta, 0, 2150)

The v3.2.0 baseline +1 and the v3.8.0 reputation multiplier are the only inputs. A tired / hungry / thirsty / sad character earns and loses XP exactly as a fully-rested one would. The v4.0.3 safety net (force a non-zero direction when the formula rounds to 0) is preserved.

Why the coupling was removed

User feedback (report id 10, Garlramor, 2026-06-27): the stat dampener made "not much sense to link the amount of lost XP bound to the multiplier of the Rep to the Stats as such. The Reputation and XP should only be used as a measure for the Relationship status dynamics based on the User behaviour, whereas the OC Persona of course determines how the behaviour is perceived and how the reputation and XP points will be influened." The intended use for stats is as RP cues — the OC notices posture (low stamina), hunger (low food), thirst (low drink), tone (low mood) — which is what the §5 prompt-injection already does. The XP coupling was a duplicate, punitive path: it was already covered (better) by the OC's awareness of the user's body in the prompt, AND it was punishing the user for the very thing the rest of the system was encouraging them to roleplay around.

The 4.3.2 AETHER_XP_MULTIPLIER_ENABLED env-var flip was the A/B test that confirmed the decoupling felt right. 1.0.11 makes that test the permanent default. The env var is gone; the lib/aether/multiplier.js function is kept dormant on disk for any future re-introduction.

What did NOT change in 1.0.11

• The body panel UI, decay, activities, prompt-injection, character_mood, age gate, and Publish toggle are all unchanged.
• The user_stats table is unchanged (still owned by Aether; read by Mirror for the profile presence snapshot).
• The v3.8.0 reputation → XP multiplier is preserved — that's the user-facing RP signal the user did NOT complain about, and it's independent of the body stats.
• No schema, no API, no UI change visible to the user. The multiplier was never displayed anywhere; the chat sidebar is identical at every stat level.

§7. Persona-Aware Scoring

When the user performs an eat or drink action, the server calls the AI to score the action against the character's persona. This is a short, single-turn call — cheap and fast.

Request shape (server → AI)

{
  "system": "You are scoring a {kind} action for {character_name}, a {persona_summary}.",
  "user": "{user_action}"
}

Response shape (AI → server, required JSON)

{
  "score":       1-20,
  "believable":  true | false,
  "comment":     "<=120 chars describing character reaction"
}

Scoring rubric

Score band	Meaning
1 – 5	Off-putting or breaks character (e.g., a vampire eating garlic bread). believable is likely false.
6 – 10	Neutral — the action is fine but unremarkable.
11 – 15	Good match for the character's tastes.
16 – 20	Deeply in-character, memorable, on-theme.

Believability gate

If the AI returns believable: false, the server clamps the score to 5 before applying it. The food/drink stat still changes, but only by a small amount. The character's reaction in comment still gets surfaced — so the user sees a clear "Peony is confused" or similar note in their next chat.

Comment feed-forward

The returned comment is:

1. Stored in user_stats.last_action_comment with a last_action_at timestamp.
2. Injected into the next chat message's system prompt as a single line: [Last action: {comment}].
3. Cleared from the row after one chat exchange so it doesn't pile up.

Worked examples for Peony (succubus persona)

User input	Score	Believable	Comment
"I slowly savor a rare steak, the juices running down my chin."	18	true	"Peony's eyes follow the sensual motion with quiet interest."
"a glass of water"	7	true	"Peony watches the glass with polite disinterest."
"garlic bread"	3	false	"Peony arches an eyebrow at the absurdity of a succubus ordering garlic bread."
"a thimble of blood"	20	true	"Peony takes the thimble with an approving smile."

§8. API Surface

All endpoints are room-scoped. Authentication is the same as the rest of the chat system (cookie-based session token).

Method	Path	Purpose
GET	/api/rooms/:id/stats	Lazy-decayed player stats + character mood (gated by relationship tier). Returns the full user_stats row plus derived character_mood if tier ≥ CLOSE FRIEND.
POST	/api/rooms/:id/stats/activity	{activity, item?, narration?} → applies effects, returns the new row + AI comment.
POST	/api/rooms/:id/stats/travel	{to} → changes location, deducts travel time. (4.2.0+)
SSE	stats-updated event	Broadcast on every activity, travel, or tick. Carries the full new user_stats row + the character mood (if visible).

Request / response shapes

POST /api/rooms/:id/stats/activity
Request:
{
  "activity":   "eat",
  "item":       "rare steak",         // required for eat/drink
  "narration":  "I slowly savor it"   // optional, sent to AI
}

Response 200:
{
  "ok":        true,
  "stats": {
    "stamina":     90,
    "food":        98,                // was 80, +18 from AI
    "drink":       80,
    "mood":        70,
    "comment":     "Peony's eyes follow the sensual motion with quiet interest."
  },
  "character_mood": 80                // included only if tier ≥ CLOSE FRIEND
}

Error codes

Status	Code	When
400	not at location	User tried to work while at home (4.2.0+)
400	invalid activity	Activity name not in the allowed list
400	missing item	eat/drink without an item string
403	locked	User is in the kicked state (XP = 0) and cannot act
422	AI scoring failed	The persona-scoring call timed out or returned malformed JSON. Server falls back to a neutral score of 10 with a generic comment.
429	rate limited	One eat/drink per 5 minutes per user. Prevents spam.

§9. UI/UX Wireframes

Body sidebar panel (chat.html, under Reputation)

┌─────────────────────────────────────────┐
│  ⚡ 90   🍔 80   💧 80   😊 70          │
│  ─────────────────────────────          │
│  💰 $200       📍 Home                  │
│  [ 🎯 Activities ]                      │
└─────────────────────────────────────────┘

Activities modal (at home, 4.0.0)

┌─────────────────────────────────────────┐
│  🎯 Activities                          │
│  ─────────────────────────────          │
│  📍 Home        💰 $200                 │
│                                         │
│  [ 🛏 Sleep — 8h, free ]                │
│  [ 🍽 Eat   — 1h, free ]                │
│  [ 💧 Drink — 5m, free ]                │
└─────────────────────────────────────────┘

Eat modal (with item + optional narration)

┌─────────────────────────────────────────┐
│  🍽 Eat                                 │
│  ─────────────────────────────          │
│  What are you eating?                    │
│  [ rare steak                       ]    │
│                                         │
│  How are you eating it? (optional)       │
│  [ I slowly savor it, the juices   ]    │
│  [ running down my chin.           ]    │
│                                         │
│  0 / 2000              [   Eat   ]      │
└─────────────────────────────────────────┘

Character mood gate (locked vs visible)

Tier < CLOSE FRIEND (default):
┌─────────────────────────────────────────┐
│  Peony                                  │
│  ...avatar, bio, XP bar...              │
│  🔒 Mood locked — build trust to see   │
└─────────────────────────────────────────┘

Tier ≥ CLOSE FRIEND:
┌─────────────────────────────────────────┐
│  Peony                                  │
│  ...avatar, bio, XP bar...              │
│  😊 Mood 80/100 — content                │
└─────────────────────────────────────────┘

Color tokens

Range	Color	Meaning
0 – 29	#e94560 red	Critical
30 – 49	#e8c547 amber	Low
50	#a0a0b0 grey	Neutral
51 – 80	#53d769 green	Good
81 – 100	#bc13fe neon	Excellent

§10. Edge Cases, Testing, & Future Hooks

Edge cases

1. No user_stats row yet. The first call to GET /api/rooms/:id/stats lazily creates the row with default values. No migration needed; the row materializes on first access.
2. AI scoring call fails. Server returns a neutral fallback: {score: 10, believable: true, comment: "Peony accepts the offering without comment."}. The user always gets some stat gain; the action never errors out.
3. Server restart during a tick. Lazy reconciliation on the next read catches up the missed decay. The 60s tick is best-effort; correctness is guaranteed by the read path.
4. User offline during a tick. Same as above — decay accumulates as time passes, applied lazily on next read.
5. Both bodies flagged unbelievable. Soft cap applies independently. If the user's persona AND the character's persona both find the action absurd, both stats still change (small) and both comments are surfaced (one in user, one in character). 4.3.0+.
6. Rapid-fire eat/drink spam. Rate limit: 1 eat or drink per 5 minutes per user. Returns 429. Sleep is exempt (it's an 8-hour action).

Testing strategy

• Unit tests for the multiplier. 12 corner-case stat combinations, asserting exact modifier values and the 0.20 floor. Run as part of the existing test_features.js suite.
• Integration test for activity end-to-end. Register a test user, enter a room, POST eat, verify the new user_stats row, verify the SSE stats-updated event, verify the next chat's system prompt contains the comment line.
• Manual smoke test for the tick. Set a test user's stamina to 100, wait 2 hours, verify the next read returns stamina=98 (2 × 1pt/hr × 2h = 2 less).
• Manual smoke test for the mood gate. Confirm character mood is hidden in the API response for a user with XP=350 (FRIEND tier). Bump to 950+ (CLOSE FRIEND), confirm it appears.

Future hooks — how to extend the system

This section is the upgradeable-system contract. Every extension below is a non-breaking additive change.

How to add a new stat (e.g. hygiene)

1. Add column to user_stats via idempotent ALTER TABLE ... ADD COLUMN ... DEFAULT 90 in the migration block.
2. Add a decay rate to DECAY_PER_HOUR at the top of server.js.
3. Add a chip in the Body sidebar panel in public/chat.html.
4. Add a modifier row to the multiplier table in §6 of this doc and in the statMultiplier() function in server.js.
5. Add a test case in test_features.js.
6. Done. No other code paths need to know.

How to add a new activity (e.g. shower)

1. Add the activity name to the activities map in server.js with its effects: {stat, delta, time_min, location: "home"}.
2. Add a button in the Activities modal in public/chat.html.
3. Add a row to §5 of this doc.
4. Add an icon and label. Done.

How to add a new location (e.g. park)

1. Extend the LOCATION_LIST constant in server.js with "park".
2. Add a "Travel to: Park" button in the Activities modal (4.2.0+).
3. Add the per-location activity grid to §5 of this doc.
4. Add a travel cost (time + money) to the travel action handler.
5. Done.

How to add a new character with a different persona

1. Create the character via the existing /soulforge.html flow (replaces the legacy /workshop.html editor as of 4.3.0).
2. The persona is automatically pulled from the persona field of the characters table and used as persona_summary in the AI scoring prompt.
3. Optional: seed character_food_prefs rows if the character has strong known likes.
4. Done.

How to add a new relationship tier (e.g. SOULMATE)

1. Extend the RELATION_LEVELS array in server.js with a new entry.
2. Update the character mood gate threshold in /api/rooms/:id/stats if the new tier changes the visibility rule.
3. Update the existing getXPInfo() function in public/chat.html to render the new label.
4. Add a row to §6 of this doc.

Appendix A — Glossary

Term	Definition
Stat mult floor	The minimum value of the body-stat multiplier, currently 0.20. A fully-depleted player always gets at least 20% of the raw XP delta.
Stable mood	The state where stamina, food, and drink are all ≥ 75. Player mood is frozen at its current value and does not decay further until one of the three drops below 75.
Believability gate	The soft cap applied when the AI scores an action as believable: false. The score is clamped to 5 before being applied to the stat. The comment is still surfaced.
Persona	The character-specific system prompt that defines a character's identity, voice, preferences, and taboos. Lives in the characters.persona DB column.
OC	Original Character — the AI-driven character bound to a room.
Comment feed-forward	The mechanism that stores the AI's reaction comment from an eat/drink and injects it into the next chat's system prompt, then clears it.
Reputation	Existing per-room 0-100 axis that multiplies the XP delta (1×–6×). Decays 1pt/hr toward 50. See changelog.json v3.8.0.
XP	Existing per-room 0-2150 axis that drives the relationship tier (STRANGER → INTIMATE).
Tick	The 60-second server-side job that applies real-time stat decay to all rows.
Lazy reconciliation	The on-read application of any missed decay, used as a safety net if the server was offline for a while.

Appendix B — Open Questions

1. Tick interval. Currently 60s. Should it be shorter (10s for smoother feel) or longer (5min for less DB churn) as the user base grows?
2. Multiplier floor. Is 0.20 too generous? Too punishing? A/B candidates: 0.10, 0.30.
3. Comment feed-forward length. Currently capped at 120 chars. Should it be 200 for richer flavor? Tradeoff: prompt token cost.
4. Character mood visibility. CLOSE FRIEND threshold feels right, but is it too late? FRIEND (350 XP) would reveal the mood earlier in the relationship arc.
5. Eating at home vs. restaurant. 4.0.0 has eating at home only. Should home eating give a smaller bonus than restaurant eating (4.2.0), or are they equivalent?
6. Decay while sleeping. Should stamina decay pause while the user is sleeping? (Trivially: yes, since the sleep action sets stamina to a high value. But what about a user who logs in, sleeps, logs out, comes back later — does stamina decay happen between the sleep end and the next login?)
7. 18+ intimate stats. Pending community poll results. See the 18+ section below.

Appendix C — References

• Reputation Bar design (3.8.0) — changelog.json v3.8.0 entry. The reputation system is the closest existing analog and shares the multiplicative-stacking pattern.
• Red Update Banner fix (3.7.1) — changelog.json v3.7.1 entry. The first-tick-on-load pattern is the same one the Life Sim's checkVersion() uses.
• Community poll (18+) — /api/life-sim/poll + /api/life-sim/poll/answer. The data file is data/life-sim-poll.json. The UI is the "🔞 Life Sim 18+ Community Input" section below.
• AGENTS.md — versioning rules, process management (thw), deployment notes.
• 🔥 Soulforge Design — the companion design document for the new (beta) Character Creator page, also planned for 4.0.0. The (beta) creator feeds the body baselines and age fields that the Life Sim consumes.

---

🔞 Life Sim 18+ Community Input

An open-ended question for the community about a future consideration in the Life Sim design. Your answers here will help inform whether (and how) intimate stats get added in a later phase. This is a separate system from the bug-report / feedback flow — your input goes into a dedicated poll log, not the support queue.

---

← Back to the main roadmap