Add bunnyland-fortunesim plugin: luck, charms, omens, fortune-telling, superstitions

Out-of-tree Bunnyland plugin (plugin id `bunnyland.fortunesim`, package
`bunnyland_fortunesim`) bundling five cooperating mechanics, each in its own
module with its own test file:

- Luck stat: an open `LuckComponent` whose materialised `value` is maintained
  each tick by `LuckConsequence` (base + held charms + active ritual bonus),
  emitting `LuckChangedEvent` on band crossings.
- Charms & talismans: carried `CharmComponent` items that raise (or, when
  cursed, lower) their holder's luck.
- Omens: `OmenConsequence` casts rooms foreboding/auspicious from loose charms,
  leaving sticky worldgen omens alone; `OmenSightedEvent`/`OmenClearedEvent`.
- Fortune-telling: the `read-fortune` verb over a held tarot/tea-leaves tool,
  assembling a deterministic reading biased by luck and the room omen.
- Superstitions: the `ward-luck` verb (knock-on-wood, toss-salt, cross-fingers)
  buys a temporary luck boost.

Good/bad fortune colours mood by reusing the core affect system. Every
luck-biased outcome and fortune reading is derived from a hashlib digest of
stable ids plus the world epoch, reduced over sorted tables — no random, no
wall-clock time, deterministic across PYTHONHASHSEED. A worldgen hook tags
generated charms/trinkets and casts ominous/auspicious rooms.

Mirrors the bunnyland-spectersim repo layout and APIs. 73 tests, ruff clean.

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

Author: thalismind

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  server:
+    name: Server Plugin (lint + tests)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout fortunesim plugin
+        uses: actions/checkout@v4
+        with:
+          path: bunnyland-fortunesim
+
+      # The plugin runs against a sibling bunnyland-server checkout: tests/conftest.py
+      # puts ../bunnyland-server/src on sys.path, and its virtualenv provides bunnyland +
+      # relics + ruff. This mirrors local development instead of building a container.
+      - name: Checkout bunnyland-server
+        uses: actions/checkout@v4
+        with:
+          repository: thalismind/bunnyland-server
+          ref: main
+          path: bunnyland-server
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Lint
+        working-directory: bunnyland-fortunesim/server
+        run: uv run --project ../../bunnyland-server ruff check src tests
+
+      - name: Test
+        working-directory: bunnyland-fortunesim/server
+        run: uv run --project ../../bunnyland-server -m pytest

.gitignore

@@ -0,0 +1,10 @@
+dist/
+build/
+*.egg-info/
+artifacts/
+*.log
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+.venv/

CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+This plugin follows the Bunnyland project code of conduct:
+
+https://github.com/thalismind/bunnyland-server/blob/main/CODE_OF_CONDUCT.md

CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+This plugin follows the Bunnyland project contribution guidelines:
+
+https://github.com/thalismind/bunnyland-server/blob/main/CONTRIBUTING.md

LICENSE

@@ -0,0 +1,89 @@
+# Bunnyland Fortunesim
+
+Out-of-tree [Bunnyland](https://github.com/thalismind/bunnyland-server) plugin about **luck,
+charms, and omens** — an expansion-pack-sized themed bundle that gently nudges outcomes and
+rewards ritual behavior. It pairs wickedly with a haunting pack (bad omens near the dead) and a
+fishing pack (a lucky charm for the big catch).
+
+> **Luck is a stat. Superstition is a strategy.**
+
+The bundle ships five cooperating mechanics:
+
+- **Luck stat** — an open `LuckComponent` on characters. Its materialised `value` (base +
+  charms + active rituals) is maintained every tick by `LuckConsequence`, so any pack that opts
+  in can read one field to bias its own probabilistic outcomes. Luck shifts the *weighting*; it
+  never rolls dice.
+- **Charms & talismans** — carried `CharmComponent` items (a rabbit's foot, a four-leaf clover)
+  that raise luck while held; cursed trinkets lower it.
+- **Omens** — `OmenConsequence` reads the world and casts a room foreboding or auspicious,
+  surfacing a deterministic omen line ("A crow watches you from the rafters.") into prompts.
+- **Fortune-telling** — a `read-fortune` verb over a held tarot / tea-leaves tool that assembles
+  a deterministic reading from the seeker, their luck, and the current room omen.
+- **Superstitions** — a `ward-luck` verb (knock on wood, toss salt, cross fingers) that buys a
+  temporary luck boost — fun busy-work with a real payoff.
+
+**Determinism:** every luck-biased outcome and fortune reading is derived from a `hashlib`
+digest of stable ids plus the world `epoch`, reduced over sorted tables. There is no `random`
+and no wall-clock time anywhere in the package, so the same world state always yields the same
+result regardless of `PYTHONHASHSEED`.
+
+This repo intentionally keeps all of the fortune work outside the main `bunnyland-server` repo.
+
+## Layout
+
+- `server/` — Python Bunnyland plugin package with the luck/charm/omen components, the luck and
+  omen consequences, the two verbs, prompt fragments, a worldgen enrichment hook, spawn
+  factories, and tests.
+
+## Server Plugin
+
+The plugin exposes `bunnyland_fortunesim.bunnyland_plugins()` and contributes:
+
+- `LuckComponent`, `CharmComponent`, `OmenComponent`, `FortuneToolComponent`.
+- `LuckConsequence` — materialises each character's total luck from held charms and active
+  rituals every tick, emitting `LuckChangedEvent` on band crossings.
+- `OmenConsequence` — adds, updates, and clears dynamic room omens driven by loose charms,
+  leaving sticky worldgen omens alone; emits `OmenSightedEvent` / `OmenClearedEvent`.
+- `luck_fragments`, `charm_fragments`, `omen_fragments` — render luck band, held charms, and
+  room omens into both human and AI prompts.
+- `FortuneWorldgenHook` — turns generated charm/trinket objects into `CharmComponent`s and casts
+  ominous or auspicious generated rooms with a sticky `OmenComponent`.
+- `read-fortune` and `ward-luck` — verbs for the seeker (human or AI), emitting `FortuneReadEvent`
+  and `WardLuckEvent`.
+- `spawn_charm`, `spawn_talisman`, `spawn_cursed_trinket`, `spawn_fortune_tool` — spawn factories.
+- Good and bad fortune colour a character's mood by reusing the core affect system
+  (`remember_fortune` attaches a decaying `AffectDelta` thought).
+
+## Running
+
+This package builds no containers. It is loaded into the stock server via `--module`:
+
+```bash
+bunnyland serve --module bunnyland_fortunesim
+```
+
+`default_enabled=True`, so no `--plugin` flag is required once the module is imported. The
+`bunnyland_fortunesim` package must be importable by the server (installed into the server's
+environment, or on `PYTHONPATH`).
+
+## Development
+
+Run server tests against a sibling `bunnyland-server` checkout (no install required —
+`server/tests/conftest.py` puts both packages on `sys.path`). From `server/`:
+
+```bash
+uv run --project ../../bunnyland-server -m pytest
+uv run --project ../../bunnyland-server ruff check src tests
+```
+
+See [`server/README.md`](server/README.md) for more detail.
+
+## Contributing & Conduct
+
+This plugin follows the Bunnyland project's
+[contribution guidelines](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md),
+which point back to the `bunnyland-server` repository.
+
+## License
+
+Licensed under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE).

README.md

@@ -0,0 +1,65 @@
+# bunnyland-fortunesim (server plugin)
+
+The out-of-tree Bunnyland plugin package `bunnyland_fortunesim` (plugin id
+`bunnyland.fortunesim`).
+
+## Development
+
+Tests run against a sibling `bunnyland-server` checkout without installing anything —
+`tests/conftest.py` puts both this package's `src/` and `../bunnyland-server/src` on
+`sys.path`. From this `server/` directory:
+
+```bash
+# uses the sibling bunnyland-server's virtualenv/deps
+uv run --project ../../bunnyland-server -m pytest
+# or, if bunnyland + relics are already importable:
+python -m pytest
+```
+
+Lint:
+
+```bash
+uv run --project ../../bunnyland-server ruff check src tests
+```
+
+## Loading into the server
+
+```bash
+bunnyland serve --module bunnyland_fortunesim
+```
+
+`default_enabled=True`, so no `--plugin` flag is required once the module is imported.
+
+## What it contributes
+
+- **Components** — `LuckComponent` (an open stat other packs can read), `CharmComponent`,
+  `OmenComponent`, and `FortuneToolComponent`.
+- **Luck** — `LuckConsequence` recomputes each character's materialised luck `value` every
+  tick from `base` luck, the sum of held charms, and any active `ward-luck` ritual bonus (which
+  expires on its own epoch), emitting `LuckChangedEvent` on band crossings. `luck_fragments`
+  render the first-person luck-band line ("Fortune favors you today.").
+- **Charms & talismans** — a held `CharmComponent` shifts its holder's luck; a negative one is a
+  cursed trinket. `charm_fragments` render the first-person "you carry a lucky …" line, and
+  `spawn_charm` / `spawn_talisman` / `spawn_cursed_trinket` make the items.
+- **Omens** — `OmenConsequence` casts a room foreboding (a cursed charm loose on the floor) or
+  auspicious (a lucky one), picking the omen line deterministically and clearing it when the
+  charms leave. Sticky worldgen omens are left untouched. `omen_fragments` render the room's
+  omen; `OmenSightedEvent` / `OmenClearedEvent` fire on change.
+- **Fortune-telling** — the `read-fortune` verb over a held tarot/tea-leaves tool assembles a
+  deterministic reading (biased upward by the seeker's luck and weaving in the room omen) and
+  emits a private `FortuneReadEvent`. `spawn_fortune_tool` makes the tool.
+- **Superstitions** — the `ward-luck` verb (knock-on-wood, toss-salt, cross-fingers) grants a
+  temporary luck boost, granting a `LuckComponent` on the fly if the character lacks one, and
+  emits `WardLuckEvent`.
+- **Mood reuse** — good/bad fortune colours a character's mood by reusing the core affect
+  system: `remember_fortune` attaches a decaying `ThoughtComponent` carrying an `AffectDelta`,
+  which the stock `AffectAggregation` folds into the character's `AffectComponent`.
+- **Worldgen** — `FortuneWorldgenHook` tags generated charm/trinket objects with
+  `CharmComponent` and casts ominous/auspicious generated rooms with a sticky `OmenComponent`.
+
+## Determinism
+
+Every luck-biased outcome and fortune reading comes from a `hashlib` digest of stable ids plus
+the world `epoch`, reduced over sorted tables (`bands.digest_unit`, `bands.biased_index`,
+`bands.luck_multiplier`). No `random`, no wall-clock time — results are stable across machines
+and across `PYTHONHASHSEED`.

server/README.md

@@ -0,0 +1,33 @@
+[project]
+name = "bunnyland-fortunesim"
+version = "0.1.0"
+description = "Out-of-tree Bunnyland plugin: an expansion-pack-sized bundle of luck, charms, omens, fortune-telling, and superstitions."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "bunnyland",
+    "pydantic>=2.0",
+    "relics",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bunnyland_fortunesim"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

server/pyproject.toml

@@ -0,0 +1,107 @@
+"""Out-of-tree Bunnyland plugin: luck, charms, omens, fortune-telling, and superstitions.
+
+An expansion-pack-sized themed bundle. Luck is a stat other packs can read; charms and
+talismans shift it while held; omens colour rooms foreboding or auspicious; ``read-fortune``
+surfaces a deterministic reading; and ``ward-luck`` rituals buy a temporary luck boost. Every
+luck-biased outcome and fortune reading is derived from a hash of stable ids plus the world
+epoch, so results are deterministic and never use runtime randomness.
+"""
+
+from .bands import (
+    BLESSED,
+    CURSED,
+    EVEN,
+    LUCKY,
+    UNLUCKY,
+    biased_index,
+    digest_unit,
+    luck_band,
+    luck_multiplier,
+)
+from .charms import (
+    charm_fragments,
+    held_charm_bonus,
+    spawn_charm,
+    spawn_cursed_trinket,
+    spawn_talisman,
+)
+from .components import (
+    AUSPICIOUS,
+    FOREBODING,
+    CharmComponent,
+    LuckComponent,
+    OmenComponent,
+)
+from .enrichment import FortuneWorldgenHook
+from .fortune import (
+    FortuneReadEvent,
+    FortuneToolComponent,
+    ReadFortuneHandler,
+    compose_reading,
+    spawn_fortune_tool,
+)
+from .install import install_fortunesim, install_fortunesim_omens
+from .luck import (
+    LuckChangedEvent,
+    LuckConsequence,
+    effective_luck,
+    fortune_mood,
+    luck_fragments,
+    remember_fortune,
+)
+from .omens import (
+    OmenClearedEvent,
+    OmenConsequence,
+    OmenSightedEvent,
+    omen_fragments,
+)
+from .plugin import PLUGIN_ID, bunnyland_plugins, plugin
+from .spatial import holder_of, room_of
+from .superstition import WardLuckEvent, WardLuckHandler
+
+__all__ = [
+    "AUSPICIOUS",
+    "BLESSED",
+    "CURSED",
+    "EVEN",
+    "FOREBODING",
+    "LUCKY",
+    "PLUGIN_ID",
+    "UNLUCKY",
+    "CharmComponent",
+    "FortuneReadEvent",
+    "FortuneToolComponent",
+    "FortuneWorldgenHook",
+    "LuckChangedEvent",
+    "LuckComponent",
+    "LuckConsequence",
+    "OmenClearedEvent",
+    "OmenComponent",
+    "OmenConsequence",
+    "OmenSightedEvent",
+    "ReadFortuneHandler",
+    "WardLuckEvent",
+    "WardLuckHandler",
+    "biased_index",
+    "bunnyland_plugins",
+    "charm_fragments",
+    "compose_reading",
+    "digest_unit",
+    "effective_luck",
+    "fortune_mood",
+    "held_charm_bonus",
+    "holder_of",
+    "install_fortunesim",
+    "install_fortunesim_omens",
+    "luck_band",
+    "luck_fragments",
+    "luck_multiplier",
+    "omen_fragments",
+    "plugin",
+    "remember_fortune",
+    "room_of",
+    "spawn_charm",
+    "spawn_cursed_trinket",
+    "spawn_fortune_tool",
+    "spawn_talisman",
+]