updated readme

README.md

@@ -70,7 +70,7 @@ Move → observe NPC density and types → make a coverage/exposure decision →
 - **Win (campaign):** Survive 90 days. Endings are gated by progression path level and total followers (TBD specific thresholds).
 - **Endless mode:** Unlocked after first campaign completion. Disables rent-based eviction. All other systems (session loss, embarrassment, lust, recognition, etc.) remain active. Lets players keep playing their character indefinitely. Implementation cost is minimal — a single flag on the run.
 - **Lose (run):** Cannot pay rent → evicted → game over. Disabled in endless mode.
-- **Lose (session):** Energy → 0, OR embarrassment → max, OR caught by police. Session loss has consequences (see §6.5) but does not end the run.
+- **Lose (session):** Energy → 0, OR embarrassment → max, OR caught by police. Session loss has consequences (see §4.4 and the summary table in §6.6) but does not end the run.
 
 ---
 
@@ -88,16 +88,20 @@ Triggered by leaving the apartment. Snapshots current equipment, attributes, and
 - The player can freely re-enter the apartment to safely end the session at any time.
 
 ### 4.3 Session end (safe)
-Player returns home. All carried items persist. Rewards from completed commissions are finalized. Embarrassment resets toward baseline.
+Player returns home. All carried items persist. Rewards from completed commissions are finalized. Embarrassment resets toward baseline. If a Snitch reported the player to police during the session (§10.2), the player keeps the `wanted` tag even after a safe return — see §7.7.
 
 ### 4.4 Session end (loss)
-Triggered by any of the four loss conditions. On loss:
-- The player is teleported home (or to a fail-state location — TBD).
-- **All currently equipped clothing is forcibly dropped** at the loss location.
-- **A bag currently placed in the world** (not carried) is lost along with its contents.
-- **Unequipped clothing already lying on the ground anywhere** can be lost with some amount of probability, if session ended due to low energy player goes to sleep and all clothing is lost. If player goes to sleep after some clothing is left outside it is also lost. Sleep = lost clothing that was left outside.
-- If reported to police but managed to end session safely gets `wanted` tag. Players need to rip **wanted posters** in the city to get rid of the `wanted` tag. `Wanted` tag spawns police every day from the start of the session.
-- If caught by police during pursuit get money penalty. If not enough money skips some days depending on lost money.
+Triggered by any session-loss condition (§3.3). On loss:
+- **The player returns to the apartment.** The route home depends on the cause:
+    - **Energy = 0** — a cutscene plays of the player trudging home, exhausted, and going to bed. The player never sleeps outside; the apartment bed is the only sleep location. Time advances by one sleep cycle.
+    - **Embarrassment = max** — fade to apartment (or a dedicated fail-state location — TBD).
+    - **Police capture** — the player is processed (money penalty below) and returned home.
+- **Equipped clothing is never forcibly removed by loss.** Whatever the player was wearing at the moment of failure stays equipped on arrival home.
+- **A bag placed in the world** (not carried) is lost along with its contents — the player did not retrieve it before the failure.
+- **Unequipped clothing left on the ground** can be lost two ways:
+    1. **In-session theft** — a chance-based roll while the player is away from the item. See §6.3.4 for the model.
+    2. **Sleep** — any clothing left outside the apartment when the player sleeps is **guaranteed** lost. This fires both for the energy-zero cutscene (forced sleep) and for voluntary sleep at home with items still outside.
+- **Police capture** during pursuit applies a money penalty. If the player can't cover it, they skip days until the debt clears; the number of skipped days scales with the unpaid amount. Capture also clears the `wanted` tag (§7.7).
 
 > **Implementation note:** session loss must be a clearly defined transactional state. All "what gets lost" logic should live in a single SessionLossResolver to keep this deterministic and debuggable.
 
@@ -142,7 +146,7 @@ Each path has a level (e.g., 1–10). Level gates clothing, missions, and attrib
 - **Clothing** (§6.3)
 - **Bags** (§6.4)
 - **Phone** (one — special, §9)
-- **Consumables** (food, §6.6)
+- **Consumables** (food, §6.7)
 - **Gadgets** (TBD beyond phone)
 
 ### 6.3 Clothing
@@ -176,9 +180,12 @@ For each body part `b`:
 - Clothing on the ground can be picked up when the player is in range.
 
 #### 6.3.4 Theft
-- Clothing left unattended (no player nearby, not in a bag) for X(1) minutes (TBD) is at risk of being stolen by an NPC. Risk is capped at X%.
-- Clothing inside a bag (even if the bag is on the ground) can't be stolen for X(3) amount of minutes
-- After X amount of minutes passed probability for stealing increases over time. Probability starts increasing only after player is away. When player enters safe zone probability and safe timer resets.
+Theft applies to loose clothing on the ground and to bags placed in the world (see §6.4). The model has two layers — a chance-based in-session roll and a deterministic sleep-loss handled in §4.4. Tuning placeholders below are resolved in §21.
+
+- **Grace period.** Loose clothing on the ground is safe for `T_grace` minutes (TBD) after the player leaves it unattended. Bagged contents (bag set down in the world) get a longer grace period `T_grace_bag` (TBD, longer than `T_grace`); the bag protects its contents until then.
+- **Chance roll.** Once an item is past its grace period, each check tick is an independent roll at a flat probability `P_theft` (TBD %). The probability does **not** ramp with time — leaving an item out for 20 minutes is not strictly riskier per minute than leaving it out for 5 minutes; the only thing time does is give more independent rolls.
+- **Resets.** The grace timer resets when the player re-enters proximity of the item or when the player is inside a safe zone (apartment).
+- **Sleep is not handled here.** Sleeping (voluntary at home or via the energy-zero cutscene) is the deterministic side of the model — any clothing left outside the apartment at sleep time is guaranteed lost, regardless of where it sits in the grace / roll cycle. See §4.4.
 
 #### 6.3.5 Rip & tear
 - Moving through bushes, against walls, or other rough collisions decrements `condition`.
@@ -201,23 +208,24 @@ For each body part `b`:
 - Bag is an equippable item with its own inventory.
 - Player can equip **one** bag at a time.
 - Bag can be placed in the world (set down) — persists as an AActor.
-- Bag lost as described in **6.3.4**
+- Bags follow the same theft rules as clothing (§6.3.4) and the same session-loss rules as other items (§4.4 / §6.6).
 
 ### 6.5 Inventory & Equipment
-- Bag slot for 1 bag
-- 1 Hand slot
-- Each clothing has container slots for storing allowed items inside
-- Each bag has also container slots
+- **Clothing slots** — one per equipment slot type (see §6.3 `type` field for the slot vocabulary; final list is TBD per §21 Q1).
+- **Bag slot** — 1 (see §6.4).
+- **Hand slot** — 1. Holds one carriable item at a time (phone, food, key, etc.). Restrictive clothing (§6.3.7) disables all hand-dependent actions while equipped.
+- **Container slots** — additional storage exposed by equipped clothing (e.g., pants pocket) and by the equipped bag. Each container slot has a size class (S / M / L, §6.3.1) that constrains what fits.
+- There is no abstract "backpack" inventory. Total carry capacity = sum of container slots provided by currently equipped items.
 
 ### 6.6 Item loss summary table
-| Situation | Outcome                                         |
-|---|-------------------------------------------------|
-| Session ends safely | All carried/equipped/placed items persist.      |
-| Session lost, item equipped | Item persists.                                  |
-| Session lost, item in equipped bag | Item persists (bag is on you).                  |
-| Session lost, bag placed in world | Bag and contents can be lost due to theft risk. |
-| Session lost, clothing on ground (unattended) | Can be lost due to theft risk.                  |
-| Clothing unattended too long, no loss | At risk of NPC theft.                           |
+| Situation | Outcome |
+|---|---|
+| Session ends safely | All carried / equipped / placed items persist. |
+| Session lost, item equipped | Item persists, fully equipped. Loss never forcibly removes worn clothing (§4.4). |
+| Session lost, item in equipped bag | Item persists (bag is on the player). |
+| Session lost, bag placed in world | Bag and contents are subject to the same theft chance as clothing (§6.3.4) and to sleep-loss if the player sleeps before retrieving them. |
+| In-session, clothing past the grace period | Each check is a flat chance of theft (§6.3.4). Picking the item back up resets the grace timer. |
+| Sleep with clothing left outside the apartment (voluntary or forced energy-zero cutscene) | **Guaranteed** loss of every clothing item left outside, regardless of grace / chance state. |
 
 ### 6.7 Consumables — Food
 - Restores energy.
@@ -256,7 +264,7 @@ All attributes update in real time. Indoor and outdoor behavior is identical —
     - Blurred peripheral vision.
     - Player cannot tell whether NPCs are calling police or taking photos.
     - No indicator of which NPCs noticed them.
-- Reset by **masturbating** (consumes more energy than usual, modified by `energyDrainMasturbateModifier`).
+- Reset by **masturbating** (consumes more energy than usual, modified by `energyDrainMasturbateModifier`). Masturbation is a Slut-path unlock (§5.1) — players who haven't taken that path cannot reset lust within a session and must accept the max-lust handicaps above until they sleep.
 
 ### 7.3 Energy
 - Drained by all activity. Base rate plus modifiers:
@@ -268,39 +276,53 @@ All attributes update in real time. Indoor and outdoor behavior is identical —
 - Recovered during sleep at `energyRecoveryRate`.
 - Hard floor at 0 → session lost.
 - Max raised by gym training.
-- Lowers max stamina (0% energy - 50% max stamina, 80-100% energy - 100% max stamina) after calculating food buffs.
+- Low energy reduces effective max stamina (see §7.4).
 
 ### 7.4 Stamina
-- Used for sprinting and other burst physical actions.
-- Recovers at `staminaRecoveryRate` when not sprinting.
-- Max raised by Slave-path leveling.
-- Distinct from energy: stamina is short-term, energy is daily budget.
-- Max stamina with buffs can be decreased by lower amounts of energy.
-- Max stamina with food buffs but without energy debuffs can be increased by food buffs.
+- Used for running and other burst physical actions.
+- Recovers at `staminaRecoveryRate` when not running.
+- Base max raised by Slave-path leveling.
+- Distinct from energy: stamina is short-term, energy is the daily budget.
+- **Effective max stamina** is derived from base max in two passes (applied in order):
+    1. **Food buffs** — additive; can raise effective max above base.
+    2. **Energy multiplier** — scales the result by `staminaEnergyFactor`, where 0% energy → 50%, 80–100% energy → 100% (linear in between).
+- Net effect: a well-fed but exhausted player has lower effective max stamina than a well-fed, rested player; food buffs cannot fully compensate for low energy.
 
-### 7.5 Recognition
+### 7.5 Pulse
+- Simulated heart-rate / arousal-rate attribute. Tracked alongside the other attributes in §7.
+- Rises with:
+    - Physical exertion (running, masturbation, sex acts).
+    - Exposure events (a body part becoming uncovered, an `expose` action triggering).
+    - Being observed while exposed.
+- Decays toward a personal baseline when at rest.
+- **Modifies** embarrassment gain (§7.1) and lust gain (§7.2) — both scale with pulse.
+- Exhibitionist-path attribute pool: leveling can raise / lower baseline pulse and adjust pulse-response curves (tuning TBD).
+
+### 7.6 Recognition
 - Each photo taken by a Blogger NPC and published increases recognition.
 - Higher recognition → faster embarrassment gain (NPCs recognize the player).
 - Reducible by reporting articles on the city news site (PC, §11.1).
 - Can be **bypassed** by hiding the face (mask, hat-and-glasses combo — TBD specifics).
 
-### 7.6 Wanted
-- Boolean. Set when reported to police.
-- Affects police patrol spawn.
-- Cleared by tearing down wanted posters in the city (§10.3) or by being caught.
+### 7.7 Wanted
+- Boolean. Set when a Snitch (§10.2) successfully reports the player to police during a session. The tag persists even if the session ends safely afterward (§4.3).
+- While set, police patrols spawn during **both day and night** until the tag is cleared (§10.3). The day/night cycle does not gate patrols once the player is `wanted`.
+- Cleared by either:
+    - Tearing down every wanted poster in the city (§10.3), or
+    - Being caught by police (§4.4) — capture also clears the tag along with applying the money penalty.
 
-### 7.7 Reputation
+### 7.8 Reputation
 - Earned by completing commissions; lost by failing or skipping them.
 - Degrades passively over time, faster at higher values.
 - Affects follower gain: positive/neutral → followers grow; negative → followers shrink.
 
-### 7.8 Followers & Money
+### 7.9 Followers & Money
 - **Followers** — running total of forum followers. Used in subscriber-style follower-gain math when posting photos.
 - Followers generate money each week.
 - More followers means more money for completing commissions.
 - **Money (Yen)** — earned from commissions, livestream donations, selling worn underwear. Spent on rent, clothing, food, gym, beauty salon.
 
-### 7.9 Attribute leveling
+### 7.10 Attribute leveling
 Path XP unlocks the *ability* to upgrade attributes within that path's pool. Money or a separate currency may be required per level-up (TBD — recommend keeping it tied to XP only for clarity, but flag for playtest).
 
 ---
@@ -319,7 +341,7 @@ Movement should be implemented as a state machine on the character with clear tr
 
 ## 9. Phone
 
-The phone is the player's diegetic UI hub. It can be used if it is in: hand, pocket (pants with phone slot), or equipped bag.
+The phone is the player's diegetic UI hub. It can be used if it is in: hand, pocket (pants with phone-sized container slot), or equipped bag. **Exception:** the livestream app (§9.1.1) continues to operate while the phone is placed in the world, so the player can keep streaming after setting the phone down for a back-camera shot.
 
 ### 9.1 Camera
 - **Front camera** — held in hand, framed selfie shot.
@@ -359,8 +381,10 @@ The phone is the primary access point for the forum. See §13.
 ### 10.1 Day / Night
 | Phase | In-game time | Real time | Effects                                                                                           |
 |---|---|---|---------------------------------------------------------------------------------------------------|
-| Day | 08:00 → 20:00 | ~45 min | High NPC density. Faster embarrassment gain. Most shops open.                                     |
-| Night | 20:00 → 08:00 | ~45 min | Low NPC density. Slower embarrassment gain. Police patrols spawn when `wanted`. Most shops closed. |
+| Day | 08:00 → 20:00 | ~45 min | High NPC density. Faster embarrassment gain. Most shops open. |
+| Night | 20:00 → 08:00 | ~45 min | Low NPC density. Slower embarrassment gain. Most shops closed. |
+
+Police patrols ignore the day/night cycle: when the player has the `wanted` tag (§7.7), patrols spawn in both phases (§10.3).
 
 Sleeping at home fast-forwards 8 hours.
 
@@ -375,12 +399,12 @@ Sleeping at home fast-forwards 8 hours.
 | **Police**        | See §10.3. |
 
 ### 10.3 Police
-- Spawn each night when `wanted`, patrol routes.
+- Spawn during both day and night while the player has the `wanted` tag (§7.7). Patrol fixed routes.
 - Detect player if face not hidden, or if revealing/no clothing.
 - On detection: chase begins.
 - If player breaks line of sight: police patrol last known position for a timer, then disengage.
 - `wanted` persists across sessions until cleared.
-- **Wanted poster mechanic:** wanted posters spawn in the city. Tearing them all down stops police spawning until further triggers.
+- **Wanted poster mechanic:** wanted posters spawn in the city. Tearing them all down clears the `wanted` tag and stops police spawning until a new Snitch report retriggers it.
 
 ### 10.4 Locations
 - **Apartment** — safe zone. Wardrobe, bed, PC, kitchen.
@@ -394,8 +418,10 @@ Sleeping at home fast-forwards 8 hours.
 - **(TBD)** beach, train station, school exterior, hot springs, etc. — design pass needed for variety.
 
 #### 10.4.1 Cuff / restraint removal
-One paths for removing restrictive clothing:
-1. **Key** - Player needs to have key and perform unlock action that takes some time, during unlock action moving or other actions are disabled.
+Restrictive clothing (§6.3.7) is removed by **Key + timed unlock action**:
+- The player must possess the matching key for the restraint instance.
+- Performing the unlock takes time; movement and all other actions are disabled for the duration.
+- There is no Helper NPC, no adult-shop unlock service, and no break-out option. If the player loses the key, the restraint stays on until a key is acquired again.
 
 ---
 
@@ -463,6 +489,7 @@ CommissionTemplate {
 ```
 Typed objective steps (initial set):
 - `ExposeBodyPart(part, durationSeconds)`
+- `BeFullyNaked(durationSeconds)` — fully unclothed for the duration; no NPC requirement.
 - `BeFullyNakedNearNPCs(count, durationSeconds)`
 - `WalkNakedDistance(meters)`
 - `MoveDistanceFromClothing(meters)`
@@ -471,11 +498,13 @@ Typed objective steps (initial set):
 - `TakePhotoAtLocation(locationTag)`
 - `DeliverItemTo(npcOrLocation)`
 
+Steps compose: a single commission step list may chain primitives that must all be satisfied (concurrently or sequentially as specified by the template).
+
 Example commissions from the brief that should be representable:
 - "Get naked in front of 1 person" → `BeFullyNakedNearNPCs(1, ~3s)`.
 - "Walk with breasts exposed for 10 seconds" → `ExposeBodyPart(boobs, 10)`.
-- "Walk naked for 30 seconds" → `BeFullyNaked(30)` (composite step).
-- "Move 50m away from your clothing while naked" → `BeFullyNaked` + `MoveDistanceFromClothing(50)`.
+- "Walk naked for 30 seconds" → `BeFullyNaked(30)`.
+- "Move 50m away from your clothing while naked" → `BeFullyNaked(durationSeconds)` + `MoveDistanceFromClothing(50)` (both must hold).
 
 ### 13.5 Subscriber math (rough)
 ```
@@ -493,7 +522,7 @@ Radial or hotbar accessible mid-session. Actions:
 - Expose body part (per garment with `canExpose`).
 - Open phone.
 - Drop bag / pick up bag.
-- Masturbate.
+- Masturbate (Slut-path unlock, §5.1 — entry hidden until unlocked).
 - Crouch / stand.
 
 ### 14.2 HUD (in-session)
@@ -522,8 +551,7 @@ Forum, bank, gallery, shops are all in-fiction screens (phone/PC). Avoid out-of-
 - **Selling worn underwear** — two delivery methods:
     - **Feetex shipping** — drop the item in a Feetex shipping box at the post office or convenience store. Payment arrives 1 in-game day later (mirrors Feetex's existing 1-day delivery delay).
     - **Drop-off** — travel to a specified location (varies per order) and leave the underwear there. Immediate payment, but the location may be in a high-risk area depending on the order. Tactical trade-off: convenience vs. drop-off-style commission tension.
-- Photo posts (indirect — followers → ongoing income? TBD).
-- Passive followers income
+- Photo posts (indirect) and accumulated followers — drive the weekly **passive follower income** (§7.9). Higher follower count → larger weekly payout and larger commission payouts.
 
 ### 15.2 Costs
 - Weekly rent — **flat across the campaign**. No escalation, no event-driven spikes. The pressure comes from the 90-day timer and other expenses, not from a moving rent target.
@@ -614,7 +642,7 @@ Clothing, commissions, food, NPC templates all live as `DataAssets` (or DataTabl
 - 15–20 clothing items spread across paths (5 Slut, 5 Exhibitionist, 5 Slave, 5 neutral).
 - 3 bag variants.
 - 8 food items (4 cooking ingredients, 4 pre-made).
-- 5 NPC types (Walker, Stalker, Paparazzi, Snitch, Harasser) + Police + Helper.
+- 5 NPC types (Walker, Stalker, Blogger, Snitch, Harasser) + Police.
 - 1 functional city district with all shop types.
 - 20 commission templates yielding ~5x procedural variation.
 - Apartment + PC + phone fully functional.
@@ -654,7 +682,7 @@ Decisions previously open, now fixed:
 6. **Selling worn underwear:** Feetex shipping (1-day, convenient) or specified drop-off location (immediate, risk-based). See §15.1.
 7. **Rent:** Flat. No escalation.
 8. **Run length:** 90-day campaign. Endless mode unlocked after first completion (rent-eviction disabled, all other systems intact). See §3.3.
-9. **Cuff/restraint removal:** Adult shop (paid, reliable) + Helper NPC (rare random spawn, free). See §10.4.1.
+9. **Cuff/restraint removal:** Key + timed unlock action only. No Helper NPC, no paid adult-shop service. See §10.4.1.
 10. **Voice commands:** Not used. Hotkey-driven only.
 
 ## 21. Open Design Questions
@@ -662,15 +690,15 @@ Decisions previously open, now fixed:
 These remain genuinely unresolved and should be addressed during implementation:
 
 1. Final slot list for clothing equipment (top, bottom, underwear-top, underwear-bottom, outerwear, footwear, accessory, restraint — confirm and lock).
-2. NPC theft timer for unattended clothing (X minutes, see §6.3.3).
-3. Concrete tuning numbers for embarrassment / lust / energy / stamina rates.
+2. NPC theft tuning: grace periods (`T_grace`, `T_grace_bag`), per-tick chance (`P_theft`), and check-tick interval — see §6.3.4.
+3. Concrete tuning numbers for embarrassment / lust / energy / stamina / pulse rates.
 4. Specific ending conditions for the 90-day campaign (path level + follower thresholds).
 5. Manual save in apartment: enabled or auto-save only?
 6. Photo system implementation: render-to-texture vs. screenshot-with-overlay (§17.6).
 7. Crowd density: full pawns vs. instanced extras with awareness-radius promotion (§17.6).
 8. Modular character system specifics — base mesh, layering scheme, attachment sockets.
-9. Helper NPC spawn rate and conditions (city-wide chance per session? specific zones?).
-10. Photo-post follower decay curve and per-photo cap.
+9. Photo-post follower decay curve and per-photo cap.
+10. Stamina ↔ energy multiplier curve specifics (linear vs. eased between 0% and 80% energy, §7.4).
 
 ---
 
@@ -681,10 +709,10 @@ These remain genuinely unresolved and should be addressed during implementation:
 - **Mission** — weekly task, generated at week start.
 - **Session** — the active outdoor play state between leaving and returning to the apartment.
 - **Path** — Slut / Exhibitionist / Slave progression track.
+- **Pulse** — heart-rate / arousal-rate attribute. Higher pulse multiplies embarrassment and lust gain. Exhibitionist-path attribute pool. See §7.5.
 - **Recognition** — how known the player is in the city. Multiplies embarrassment gain.
-- **Wanted** — binary police-target flag.
-- **Helper** — rare friendly NPC who can remove restrictive clothing for free.
-- **Feetex** — in-fiction package tracking and shipping service.
+- **Wanted** — binary police-target flag. Set by Snitch reports; cleared by tearing down posters or by capture. See §7.7.
+- **Feetex** — in-fiction package tracking and shipping service. Handles both incoming deliveries (1-day delay) and outgoing worn-underwear shipping.
 - **Endless mode** — post-campaign unlock; rent eviction disabled, all other systems active.
 
 ---