Add v2 mechanics: sanity dread meter and rituals/wards

Bundle two survival-horror mechanics onto the spectersim detector plugin,
bumping it to 0.2.0.

Sanity: SanityComponent(current, maximum) on characters, driven by a per-tick
SanityConsequence that drains near SpectralMarker entities and in dark rooms,
recovers in safe or bright spirit-free rooms (clamped 0..maximum), and emits
SanityChangedEvent on band crossings. sanity_fragments inject escalating
first-person distortion lines (shaking, whispering, a hallucinated presence at
critical) into the afflicted character's own prompt only.

Rituals & wards: WardComponent protects a room or placed ward entity;
RitualKitComponent is a held banishing tool. WardConsequence passively weakens
then banishes (strips SpectralMarkerComponent from) presences in warded rooms.
Verbs draw-ward and perform-ritual follow the validate-order convention and emit
WardDrawnEvent / PresenceWeakenedEvent / PresenceBanishedEvent. ritual_fragments
surface ward protection and the held-kit line. New spawn_ritual_kit / spawn_ward
factories.

All new surfaces registered in plugin.py; v1 behavior and tests untouched.
Adds test_sanity.py and test_rituals.py; 90 tests pass, ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: thalismind

README.md

@@ -8,6 +8,16 @@ particular marker component share its room**. Two variants ship out of the box:
 - **Ghost detector** — reacts to `SpectralMarkerComponent` (monsters, spirits, the undead).
 - **Radio** — reacts to `RadioSourceMarkerComponent` (transmitters, beacons, broadcasters).
 
+**v2** bundles two survival-horror mechanics on top of the detectors:
+
+- **Sanity** — a dread meter (`SanityComponent`) that drains near spectral presences and in
+  the dark, recovers in safe or bright spirit-free rooms, and injects escalating first-person
+  distortion lines ("Your hands won't stop shaking.", whispering, a hallucinated presence)
+  into the afflicted character's own prompt.
+- **Rituals & wards** — `draw-ward` protects a room and `perform-ritual` channels a held
+  ritual kit to weaken and finally banish a spectral presence; a warded room also erodes any
+  trapped presence passively.
+
 This repo intentionally keeps all detector work outside the main `bunnyland-server` repo.
 
 ## Layout
@@ -30,6 +40,17 @@ The plugin exposes `bunnyland_spectersim.bunnyland_plugins()` and contributes:
 - `power-detector` and `set-detector-volume` - verbs for the holder (human or AI).
 - `spawn_ghost_detector`, `spawn_radio` - spawn factories.
 
+v2 additionally contributes:
+
+- `SanityComponent` and `SanityConsequence` - the per-tick dread meter, with band-crossing
+  `SanityChangedEvent`s and first-person `sanity_fragments`.
+- `WardComponent`, `RitualKitComponent`, and `WardConsequence` - room protection plus the
+  passive weaken/banish pass, with `WardDrawnEvent`, `PresenceWeakenedEvent`, and
+  `PresenceBanishedEvent`.
+- `draw-ward` and `perform-ritual` - verbs for placing wards and banishing presences.
+- `ritual_fragments` - renders ward protection and the held-kit line into prompts.
+- `spawn_ritual_kit`, `spawn_ward` - spawn factories.
+
 ## Running
 
 This package builds no containers. It is loaded into the stock server via `--module`:

server/README.md

@@ -41,3 +41,20 @@ bunnyland serve --module bunnyland_spectersim
 - **Two verbs** — `power-detector` and `set-detector-volume` — usable by the holder
   (human or AI).
 - **Spawn factories** — `spawn_ghost_detector`, `spawn_radio`.
+
+### v2 — sanity and rituals
+
+- **Sanity** — `SanityComponent(current, maximum)` on characters and a per-tick
+  `SanityConsequence` that drains sanity near `SpectralMarkerComponent` entities and in dark
+  rooms, recovers it in safe or bright spirit-free rooms (clamped `0..maximum`), and emits a
+  `SanityChangedEvent` on band crossings. `sanity_fragments` inject escalating first-person
+  distortion lines at low sanity (shaking, whispering, and a hallucinated presence at
+  critical), visible only to the afflicted character.
+- **Rituals & wards** — `WardComponent` marks a room (or a placed ward entity) as protected;
+  `RitualKitComponent` is a held banishing tool. `WardConsequence` passively weakens then
+  banishes (strips the `SpectralMarkerComponent` from) any presence caught in a warded room.
+  Verbs `draw-ward` (place a ward, optionally consuming a held reagent) and `perform-ritual`
+  (channel a held kit to weaken/banish a presence in the room) emit `WardDrawnEvent`,
+  `PresenceWeakenedEvent`, and `PresenceBanishedEvent`. `ritual_fragments` render ward
+  protection and the held-kit line.
+- **Spawn factories** — `spawn_ritual_kit`, `spawn_ward`.

server/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "bunnyland-spectersim"
-version = "0.1.0"
-description = "Out-of-tree Bunnyland plugin: Silent Hill / Ghost Hunters-style monster-detecting devices (ghost detector + radio)."
+version = "0.2.0"
+description = "Out-of-tree Bunnyland plugin: Silent Hill / Ghost Hunters-style monster-detecting devices, plus a sanity meter and banishing rituals/wards."
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [

server/src/bunnyland_spectersim/__init__.py

@@ -1,4 +1,8 @@
-"""Out-of-tree Bunnyland plugin: monster-detecting devices (ghost detector + radio)."""
+"""Out-of-tree Bunnyland plugin: monster-detecting devices (ghost detector + radio).
+
+v2 adds two bundled mechanics: a **sanity** dread meter and **rituals/wards** for banishing
+spectral presences.
+"""
 
 from .commands import PowerDetectorHandler, SetDetectorVolumeHandler
 from .components import (
@@ -14,9 +18,27 @@
 from .enrichment import SpecterWorldgenHook
 from .events import DetectorPoweredEvent, DetectorVolumeSetEvent
 from .fragments import spectersim_fragments
-from .install import install_spectersim
+from .install import install_spectersim, install_spectersim_v2
 from .plugin import PLUGIN_ID, bunnyland_plugins, plugin
-from .prefabs import spawn_ghost_detector, spawn_radio
+from .prefabs import spawn_ghost_detector, spawn_radio, spawn_ritual_kit, spawn_ward
+from .rituals import (
+    DrawWardHandler,
+    PerformRitualHandler,
+    PresenceBanishedEvent,
+    PresenceWeakenedEvent,
+    RitualKitComponent,
+    WardComponent,
+    WardConsequence,
+    WardDrawnEvent,
+    ritual_fragments,
+)
+from .sanity import (
+    SanityChangedEvent,
+    SanityComponent,
+    SanityConsequence,
+    sanity_band,
+    sanity_fragments,
+)
 from .spatial import holder_of, room_of
 
 __all__ = [
@@ -26,20 +48,37 @@
     "DetectionConsequence",
     "DetectorPoweredEvent",
     "DetectorVolumeSetEvent",
+    "DrawWardHandler",
     "GhostDetectorComponent",
+    "PerformRitualHandler",
     "PowerDetectorHandler",
+    "PresenceBanishedEvent",
+    "PresenceWeakenedEvent",
     "RadioDetectorComponent",
     "RadioSourceMarkerComponent",
+    "RitualKitComponent",
+    "SanityChangedEvent",
+    "SanityComponent",
+    "SanityConsequence",
     "SetDetectorVolumeHandler",
     "SpecterWorldgenHook",
     "SpectralMarkerComponent",
+    "WardComponent",
+    "WardConsequence",
+    "WardDrawnEvent",
     "bunnyland_plugins",
     "detector_component_of",
     "holder_of",
     "install_spectersim",
+    "install_spectersim_v2",
     "plugin",
+    "ritual_fragments",
     "room_of",
+    "sanity_band",
+    "sanity_fragments",
     "spawn_ghost_detector",
     "spawn_radio",
+    "spawn_ritual_kit",
+    "spawn_ward",
     "spectersim_fragments",
 ]

server/src/bunnyland_spectersim/install.py

@@ -1,15 +1,23 @@
-"""Runtime wiring: register the detection consequence on a world actor."""
+"""Runtime wiring: register the per-tick consequences on a world actor."""
 
 from __future__ import annotations
 
 from bunnyland.core.world_actor import WorldActor
 
 from .detection import DetectionConsequence
+from .rituals import WardConsequence
+from .sanity import SanityConsequence
 
 
 def install_spectersim(actor: WorldActor) -> None:
-    """Register the per-tick detection consequence (a ``service_factories`` entry)."""
+    """Register the v1 detection consequence (a ``service_factories`` entry)."""
     actor.register_consequence(DetectionConsequence())
 
 
-__all__ = ["install_spectersim"]
+def install_spectersim_v2(actor: WorldActor) -> None:
+    """Register the v2 sanity and ward consequences (a ``service_factories`` entry)."""
+    actor.register_consequence(SanityConsequence())
+    actor.register_consequence(WardConsequence())
+
+
+__all__ = ["install_spectersim", "install_spectersim_v2"]

server/src/bunnyland_spectersim/plugin.py

@@ -20,7 +20,18 @@
 from .enrichment import SpecterWorldgenHook
 from .events import DetectorPoweredEvent, DetectorVolumeSetEvent
 from .fragments import spectersim_fragments
-from .install import install_spectersim
+from .install import install_spectersim, install_spectersim_v2
+from .rituals import (
+    RITUAL_ACTION_DEFINITIONS,
+    RITUAL_ACTION_HANDLERS,
+    PresenceBanishedEvent,
+    PresenceWeakenedEvent,
+    RitualKitComponent,
+    WardComponent,
+    WardDrawnEvent,
+    ritual_fragments,
+)
+from .sanity import SanityChangedEvent, SanityComponent, sanity_fragments
 
 PLUGIN_ID = "bunnyland_spectersim"
 
@@ -29,24 +40,36 @@ def plugin() -> Plugin:
     return Plugin(
         id=PLUGIN_ID,
         name="Bunnyland Spectersim",
-        version="0.1.0",
+        version="0.2.0",
         default_enabled=True,
         ecs=EcsContribution(
             components=(
                 SpectralMarkerComponent,
                 RadioSourceMarkerComponent,
                 GhostDetectorComponent,
                 RadioDetectorComponent,
+                SanityComponent,
+                WardComponent,
+                RitualKitComponent,
             ),
         ),
         commands=CommandContribution(
-            action_handlers=DETECTOR_ACTION_HANDLERS,
-            action_definitions=DETECTOR_ACTION_DEFINITIONS,
-            typed_events=(DetectorPoweredEvent, DetectorVolumeSetEvent),
+            action_handlers=DETECTOR_ACTION_HANDLERS + RITUAL_ACTION_HANDLERS,
+            action_definitions=DETECTOR_ACTION_DEFINITIONS + RITUAL_ACTION_DEFINITIONS,
+            typed_events=(
+                DetectorPoweredEvent,
+                DetectorVolumeSetEvent,
+                SanityChangedEvent,
+                WardDrawnEvent,
+                PresenceWeakenedEvent,
+                PresenceBanishedEvent,
+            ),
+        ),
+        runtime=RuntimeContribution(
+            service_factories=(install_spectersim, install_spectersim_v2),
         ),
-        runtime=RuntimeContribution(service_factories=(install_spectersim,)),
         content=ContentContribution(
-            prompt_fragments=(spectersim_fragments,),
+            prompt_fragments=(spectersim_fragments, sanity_fragments, ritual_fragments),
             worldgen_hooks=(SpecterWorldgenHook,),
         ),
     )

server/src/bunnyland_spectersim/prefabs.py

@@ -19,6 +19,7 @@
 from relics import Entity, World
 
 from .components import GhostDetectorComponent, RadioDetectorComponent
+from .rituals import RitualKitComponent, WardComponent
 
 
 def _link_into_room(world: World, item: Entity, room_id) -> None:
@@ -57,4 +58,32 @@ def spawn_radio(world: World, *, room_id=None, sound: str = "hiss") -> Entity:
     return item
 
 
-__all__ = ["spawn_ghost_detector", "spawn_radio"]
+def spawn_ritual_kit(world: World, *, room_id=None, potency: float = 0.5) -> Entity:
+    """Spawn a holdable ritual kit item, optionally placed in ``room_id``."""
+    item = spawn_entity(
+        world,
+        [
+            IdentityComponent(name="ritual kit", kind="item", tags=("spectersim",)),
+            PortableComponent(),
+            HoldableComponent(slot="hand"),
+            RitualKitComponent(potency=potency),
+        ],
+    )
+    _link_into_room(world, item, room_id)
+    return item
+
+
+def spawn_ward(world: World, *, room_id=None, strength: float = 1.0) -> Entity:
+    """Spawn a standalone ward entity, optionally placed in ``room_id`` to protect it."""
+    ward = spawn_entity(
+        world,
+        [
+            IdentityComponent(name="ward", kind="ward", tags=("spectersim",)),
+            WardComponent(strength=strength),
+        ],
+    )
+    _link_into_room(world, ward, room_id)
+    return ward
+
+
+__all__ = ["spawn_ghost_detector", "spawn_radio", "spawn_ritual_kit", "spawn_ward"]