osrlib 2.0.0__tar.gz → 2.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. {osrlib-2.0.0 → osrlib-2.0.1}/PKG-INFO +8 -8
  2. {osrlib-2.0.0 → osrlib-2.0.1}/README.md +7 -7
  3. {osrlib-2.0.0 → osrlib-2.0.1}/pyproject.toml +1 -1
  4. osrlib-2.0.1/src/osrlib/__init__.py +135 -0
  5. osrlib-2.0.1/src/osrlib/core/__init__.py +93 -0
  6. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/abilities.py +330 -129
  7. osrlib-2.0.1/src/osrlib/core/alignment.py +72 -0
  8. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/character.py +502 -389
  9. osrlib-2.0.1/src/osrlib/core/classes.py +1487 -0
  10. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/clock.py +66 -51
  11. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/combat.py +1189 -963
  12. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/creature.py +60 -43
  13. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/dice.py +53 -45
  14. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/effects.py +566 -397
  15. osrlib-2.0.1/src/osrlib/core/events.py +1426 -0
  16. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/items.py +693 -475
  17. osrlib-2.0.1/src/osrlib/core/monsters.py +1242 -0
  18. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/npc.py +144 -115
  19. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/rng.py +213 -149
  20. osrlib-2.0.1/src/osrlib/core/ruleset.py +264 -0
  21. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/spells.py +960 -806
  22. osrlib-2.0.1/src/osrlib/core/tables.py +1286 -0
  23. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/treasure.py +200 -163
  24. osrlib-2.0.1/src/osrlib/core/validation.py +114 -0
  25. osrlib-2.0.1/src/osrlib/crawl/__init__.py +81 -0
  26. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/adventure.py +236 -209
  27. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/battle.py +520 -308
  28. osrlib-2.0.1/src/osrlib/crawl/commands.py +3682 -0
  29. osrlib-2.0.1/src/osrlib/crawl/content_pack.py +517 -0
  30. osrlib-2.0.1/src/osrlib/crawl/dungeon.py +1957 -0
  31. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/encounter.py +322 -257
  32. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/events.py +644 -569
  33. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/exploration.py +341 -304
  34. osrlib-2.0.1/src/osrlib/crawl/gates.py +426 -0
  35. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/interpreter.py +147 -142
  36. osrlib-2.0.1/src/osrlib/crawl/narrative.py +133 -0
  37. osrlib-2.0.1/src/osrlib/crawl/party.py +277 -0
  38. osrlib-2.0.1/src/osrlib/crawl/quests.py +332 -0
  39. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/session.py +893 -422
  40. osrlib-2.0.1/src/osrlib/crawl/stocking.py +286 -0
  41. osrlib-2.0.1/src/osrlib/crawl/triggers.py +445 -0
  42. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/views.py +362 -329
  43. osrlib-2.0.1/src/osrlib/data/__init__.py +623 -0
  44. osrlib-2.0.1/src/osrlib/errors.py +216 -0
  45. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/messages.py +55 -44
  46. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/persistence.py +221 -177
  47. osrlib-2.0.1/src/osrlib/versioning.py +264 -0
  48. osrlib-2.0.0/src/osrlib/__init__.py +0 -135
  49. osrlib-2.0.0/src/osrlib/core/__init__.py +0 -81
  50. osrlib-2.0.0/src/osrlib/core/alignment.py +0 -67
  51. osrlib-2.0.0/src/osrlib/core/classes.py +0 -1434
  52. osrlib-2.0.0/src/osrlib/core/events.py +0 -1380
  53. osrlib-2.0.0/src/osrlib/core/monsters.py +0 -1095
  54. osrlib-2.0.0/src/osrlib/core/ruleset.py +0 -256
  55. osrlib-2.0.0/src/osrlib/core/tables.py +0 -1230
  56. osrlib-2.0.0/src/osrlib/core/validation.py +0 -107
  57. osrlib-2.0.0/src/osrlib/crawl/__init__.py +0 -79
  58. osrlib-2.0.0/src/osrlib/crawl/commands.py +0 -3106
  59. osrlib-2.0.0/src/osrlib/crawl/content_pack.py +0 -476
  60. osrlib-2.0.0/src/osrlib/crawl/dungeon.py +0 -1747
  61. osrlib-2.0.0/src/osrlib/crawl/gates.py +0 -352
  62. osrlib-2.0.0/src/osrlib/crawl/narrative.py +0 -133
  63. osrlib-2.0.0/src/osrlib/crawl/party.py +0 -188
  64. osrlib-2.0.0/src/osrlib/crawl/quests.py +0 -287
  65. osrlib-2.0.0/src/osrlib/crawl/stocking.py +0 -268
  66. osrlib-2.0.0/src/osrlib/crawl/triggers.py +0 -423
  67. osrlib-2.0.0/src/osrlib/data/__init__.py +0 -593
  68. osrlib-2.0.0/src/osrlib/errors.py +0 -144
  69. osrlib-2.0.0/src/osrlib/versioning.py +0 -239
  70. {osrlib-2.0.0 → osrlib-2.0.1}/LICENSE +0 -0
  71. {osrlib-2.0.0 → osrlib-2.0.1}/LICENSE-OGL.md +0 -0
  72. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/LICENSE-OGL.md +0 -0
  73. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/abilities.json +0 -0
  74. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/classes.json +0 -0
  75. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/combat_tables.json +0 -0
  76. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/encounter_tables.json +0 -0
  77. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/equipment.json +0 -0
  78. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/languages.json +0 -0
  79. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/magic_items.json +0 -0
  80. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/monsters.json +0 -0
  81. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/spells.json +0 -0
  82. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/treasure.json +0 -0
  83. {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: osrlib
3
- Version: 2.0.0
3
+ Version: 2.0.1
4
4
  Summary: B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers
5
5
  Keywords: basic-expert,bx,dungeon-crawler,game-engine,osr,rpg,srd,ttrpg
6
6
  Author: Marsh Macy
@@ -27,13 +27,13 @@ Description-Content-Type: text/markdown
27
27
 
28
28
  osrlib is a Python library that implements the classic 1981 B/X (Basic/Expert) fantasy adventure game rules for turn-based, grid-based dungeon crawlers in the style of the original Bard's Tale. The rules come from the [Old-School Essentials System Reference Document](https://oldschoolessentials.necroticgnome.com/srd/), an Open Game Content restatement of the B/X rules. osrlib is the rules authority and game-state engine. Your game supplies presentation, input, and content.
29
29
 
30
- The library is headless and sans-I/O: it never renders, prompts, sleeps, or touches the network. Every game it runs is deterministic. The same seed and the same commands always replay the same game. An adventure defines its own content and behavior (bundled items, gated doors, triggers, and quests), and the library includes the interpreter that plays the adventure through to a victory ending. osrlib is designed for four kinds of consumer: a web or mobile backend (FastAPI over HTTP), a terminal game (a local TUI crawler), an LLM referee or narrator driven by structured events and typed commands, and scripts or simulations that call the rules kernel with no session at all.
30
+ The library is headless and sans-I/O: it never renders, prompts, sleeps, or touches the network. Every game it runs is deterministic. The same seed and the same commands always replay the same game. An adventure defines its content and behavior (bundled items, gated doors, triggers, and quests), and the library includes the interpreter that plays the adventure through to a victory ending. osrlib is designed for four kinds of consumer: a web or mobile backend (FastAPI over HTTP), a terminal game (a local TUI crawler), an LLM referee or narrator driven by structured events and typed commands, and scripts or simulations that call the rules kernel with no session at all.
31
31
 
32
32
  **Status:** released and published as [osrlib on PyPI](https://pypi.org/project/osrlib/). The public API is frozen. The [documentation site](https://mmacy.github.io/osrlib-python/) is the place to learn the library: quickstart, guides, front-end walk-throughs, and a full reference for every public symbol, command, event, rejection code, message code, RNG stream, and content id.
33
33
 
34
34
  ## Installation
35
35
 
36
- Requires Python ≥ 3.14. The only runtime dependency is [pydantic](https://docs.pydantic.dev/).
36
+ osrlib requires Python 3.14 or later. The only runtime dependency is [pydantic](https://docs.pydantic.dev/).
37
37
 
38
38
  ```sh
39
39
  uv add osrlib
@@ -97,7 +97,7 @@ The [documentation site](https://mmacy.github.io/osrlib-python/) walks you throu
97
97
 
98
98
  ## Determinism
99
99
 
100
- Determinism is a public API guarantee. All randomness flows through named PCG64 streams forked from a master seed. The same seed and the same key always produce the same stream, independent of any other stream:
100
+ Determinism is a public API guarantee. Every random draw comes from a named PCG64 stream forked from a master seed. The same seed and the same key always produce the same stream, independent of any other stream:
101
101
 
102
102
  ```python
103
103
  from osrlib.core.dice import roll
@@ -111,7 +111,7 @@ rolls_b = [roll("2d6×10", streams_b.get("treasure")).total for _ in range(3)]
111
111
  assert rolls_a == rolls_b # the same seed and the same key give identical sequences
112
112
  ```
113
113
 
114
- Successive rolls on one stream differ. The contract is that deriving a stream again, from the same seed and key, reproduces the same sequence. `load_game` restores a saved game from its serialized state alone, with no re-execution. `replay_game` rebuilds the same session by re-executing the seed and the command log from scratch. The determinism guarantee is that the two paths always agree, and a standing test checks that they do.
114
+ Successive rolls on one stream differ. The contract is that deriving a stream again, from the same seed and key, reproduces the same sequence. `load_game` restores a saved game from its serialized state alone, with no re-execution. `replay_game` rebuilds the same session by re-executing the seed and the command log from scratch. The determinism guarantee is that the two paths always agree, and a test checks that they do.
115
115
 
116
116
  ## SRD data pipeline
117
117
 
@@ -121,11 +121,11 @@ The compiler in `tools/srd_compile/` generates the game data in `src/osrlib/data
121
121
  uv run python -m tools.srd_compile
122
122
  ```
123
123
 
124
- CI regenerates the data and fails on any diff, so `srd/`, the compiler, and the generated data can't drift apart. Parser corrections belong in `tools/srd_compile/overrides/`, never in the output. Every override includes a reason, and the compiler records each overridden field path in the output entry's `overrides_applied` provenance list. The [adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) documents the rules interpretations and adaptations.
124
+ CI regenerates the data and fails on any diff, so `srd/`, the compiler, and the generated data can't drift apart. Parser corrections belong in `tools/srd_compile/overrides/`, never in the output. Every override includes a reason, and the compiler lists each overridden field path in the `overrides_applied` field of the output entry. The [adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) documents the rules interpretations and adaptations.
125
125
 
126
126
  ## Contributing
127
127
 
128
- Requires Python ≥ 3.14 and [uv](https://docs.astral.sh/uv/). Install from source and run the checks the way CI does:
128
+ You need Python 3.14 or later and [uv](https://docs.astral.sh/uv/). Install from source and run the checks the way CI does:
129
129
 
130
130
  ```sh
131
131
  git clone https://github.com/mmacy/osrlib-python.git
@@ -142,6 +142,6 @@ For the design (architecture, contracts, rules scope, and the phased roadmap), s
142
142
 
143
143
  ## Licensing
144
144
 
145
- This repository contains two kinds of material under two licenses. The library code is licensed under the [MIT license](LICENSE). The SRD-derived content (the scraped SRD text in `srd/` and the compiled game data in `src/osrlib/data/`) is Open Game Content used under the [Open Game License 1.0a](LICENSE-OGL.md), which includes the complete Section 15 copyright notice. The data package includes its own copy of the license, with the osrlib Section 15 entry, inside the built wheel.
145
+ This repository contains two kinds of material under two licenses. The library code is licensed under the [MIT license](LICENSE). The SRD-derived content (the scraped SRD text in `srd/` and the compiled game data in `src/osrlib/data/`) is Open Game Content used under the [Open Game License 1.0a](LICENSE-OGL.md), which includes the complete Section 15 copyright notice. The data package in the built wheel includes a copy of the license, with the osrlib Section 15 entry.
146
146
 
147
147
  osrlib is an independent project, not affiliated with or endorsed by Necrotic Gnome. "Old-School Essentials" is a trademark of Necrotic Gnome, used here only to identify the source document. osrlib makes no claim of compatibility.
@@ -2,13 +2,13 @@
2
2
 
3
3
  osrlib is a Python library that implements the classic 1981 B/X (Basic/Expert) fantasy adventure game rules for turn-based, grid-based dungeon crawlers in the style of the original Bard's Tale. The rules come from the [Old-School Essentials System Reference Document](https://oldschoolessentials.necroticgnome.com/srd/), an Open Game Content restatement of the B/X rules. osrlib is the rules authority and game-state engine. Your game supplies presentation, input, and content.
4
4
 
5
- The library is headless and sans-I/O: it never renders, prompts, sleeps, or touches the network. Every game it runs is deterministic. The same seed and the same commands always replay the same game. An adventure defines its own content and behavior (bundled items, gated doors, triggers, and quests), and the library includes the interpreter that plays the adventure through to a victory ending. osrlib is designed for four kinds of consumer: a web or mobile backend (FastAPI over HTTP), a terminal game (a local TUI crawler), an LLM referee or narrator driven by structured events and typed commands, and scripts or simulations that call the rules kernel with no session at all.
5
+ The library is headless and sans-I/O: it never renders, prompts, sleeps, or touches the network. Every game it runs is deterministic. The same seed and the same commands always replay the same game. An adventure defines its content and behavior (bundled items, gated doors, triggers, and quests), and the library includes the interpreter that plays the adventure through to a victory ending. osrlib is designed for four kinds of consumer: a web or mobile backend (FastAPI over HTTP), a terminal game (a local TUI crawler), an LLM referee or narrator driven by structured events and typed commands, and scripts or simulations that call the rules kernel with no session at all.
6
6
 
7
7
  **Status:** released and published as [osrlib on PyPI](https://pypi.org/project/osrlib/). The public API is frozen. The [documentation site](https://mmacy.github.io/osrlib-python/) is the place to learn the library: quickstart, guides, front-end walk-throughs, and a full reference for every public symbol, command, event, rejection code, message code, RNG stream, and content id.
8
8
 
9
9
  ## Installation
10
10
 
11
- Requires Python ≥ 3.14. The only runtime dependency is [pydantic](https://docs.pydantic.dev/).
11
+ osrlib requires Python 3.14 or later. The only runtime dependency is [pydantic](https://docs.pydantic.dev/).
12
12
 
13
13
  ```sh
14
14
  uv add osrlib
@@ -72,7 +72,7 @@ The [documentation site](https://mmacy.github.io/osrlib-python/) walks you throu
72
72
 
73
73
  ## Determinism
74
74
 
75
- Determinism is a public API guarantee. All randomness flows through named PCG64 streams forked from a master seed. The same seed and the same key always produce the same stream, independent of any other stream:
75
+ Determinism is a public API guarantee. Every random draw comes from a named PCG64 stream forked from a master seed. The same seed and the same key always produce the same stream, independent of any other stream:
76
76
 
77
77
  ```python
78
78
  from osrlib.core.dice import roll
@@ -86,7 +86,7 @@ rolls_b = [roll("2d6×10", streams_b.get("treasure")).total for _ in range(3)]
86
86
  assert rolls_a == rolls_b # the same seed and the same key give identical sequences
87
87
  ```
88
88
 
89
- Successive rolls on one stream differ. The contract is that deriving a stream again, from the same seed and key, reproduces the same sequence. `load_game` restores a saved game from its serialized state alone, with no re-execution. `replay_game` rebuilds the same session by re-executing the seed and the command log from scratch. The determinism guarantee is that the two paths always agree, and a standing test checks that they do.
89
+ Successive rolls on one stream differ. The contract is that deriving a stream again, from the same seed and key, reproduces the same sequence. `load_game` restores a saved game from its serialized state alone, with no re-execution. `replay_game` rebuilds the same session by re-executing the seed and the command log from scratch. The determinism guarantee is that the two paths always agree, and a test checks that they do.
90
90
 
91
91
  ## SRD data pipeline
92
92
 
@@ -96,11 +96,11 @@ The compiler in `tools/srd_compile/` generates the game data in `src/osrlib/data
96
96
  uv run python -m tools.srd_compile
97
97
  ```
98
98
 
99
- CI regenerates the data and fails on any diff, so `srd/`, the compiler, and the generated data can't drift apart. Parser corrections belong in `tools/srd_compile/overrides/`, never in the output. Every override includes a reason, and the compiler records each overridden field path in the output entry's `overrides_applied` provenance list. The [adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) documents the rules interpretations and adaptations.
99
+ CI regenerates the data and fails on any diff, so `srd/`, the compiler, and the generated data can't drift apart. Parser corrections belong in `tools/srd_compile/overrides/`, never in the output. Every override includes a reason, and the compiler lists each overridden field path in the `overrides_applied` field of the output entry. The [adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) documents the rules interpretations and adaptations.
100
100
 
101
101
  ## Contributing
102
102
 
103
- Requires Python ≥ 3.14 and [uv](https://docs.astral.sh/uv/). Install from source and run the checks the way CI does:
103
+ You need Python 3.14 or later and [uv](https://docs.astral.sh/uv/). Install from source and run the checks the way CI does:
104
104
 
105
105
  ```sh
106
106
  git clone https://github.com/mmacy/osrlib-python.git
@@ -117,6 +117,6 @@ For the design (architecture, contracts, rules scope, and the phased roadmap), s
117
117
 
118
118
  ## Licensing
119
119
 
120
- This repository contains two kinds of material under two licenses. The library code is licensed under the [MIT license](LICENSE). The SRD-derived content (the scraped SRD text in `srd/` and the compiled game data in `src/osrlib/data/`) is Open Game Content used under the [Open Game License 1.0a](LICENSE-OGL.md), which includes the complete Section 15 copyright notice. The data package includes its own copy of the license, with the osrlib Section 15 entry, inside the built wheel.
120
+ This repository contains two kinds of material under two licenses. The library code is licensed under the [MIT license](LICENSE). The SRD-derived content (the scraped SRD text in `srd/` and the compiled game data in `src/osrlib/data/`) is Open Game Content used under the [Open Game License 1.0a](LICENSE-OGL.md), which includes the complete Section 15 copyright notice. The data package in the built wheel includes a copy of the license, with the osrlib Section 15 entry.
121
121
 
122
122
  osrlib is an independent project, not affiliated with or endorsed by Necrotic Gnome. "Old-School Essentials" is a trademark of Necrotic Gnome, used here only to identify the source document. osrlib makes no claim of compatibility.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "osrlib"
3
- version = "2.0.0"
3
+ version = "2.0.1"
4
4
  description = "B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers"
5
5
  readme = "README.md"
6
6
  # The wheel ships Open Game Content (osrlib/data/*.json and its LICENSE-OGL.md
@@ -0,0 +1,135 @@
1
+ """B/X (1981 Basic/Expert) rules engine for turn-based dungeon crawlers.
2
+
3
+ osrlib applies the rules of a game and stores its state. It has no user interface (UI), never
4
+ waits for a player, and makes no network calls. You write the program a player uses, and that
5
+ program calls osrlib. You pass osrlib a command, an object that describes one player action.
6
+ osrlib applies the rules and returns typed events, each a record of one thing that happened. Your
7
+ program turns those events into what the player sees. Every random number comes from a named,
8
+ seeded stream, so if you replay the same commands from the same seed, you get the same game.
9
+
10
+ Each name is defined in one module, and the package root doesn't re-export any names, so import
11
+ each name from the module that defines it. osrlib has three layers of modules.
12
+
13
+ ## The core kernel
14
+
15
+ The kernel, under `osrlib.core`, contains the rules without a session, a dungeon, or an
16
+ adventure. You pass a kernel function the inputs for one rule, plus a seeded stream and a
17
+ ruleset, and it returns the outcome and the events that describe it. Call kernel functions
18
+ directly to roll a character, resolve an attack, or price a sword without starting a session.
19
+ Kernel modules never import from `osrlib.crawl`, so you can use them without it.
20
+
21
+ | Module | What it's for |
22
+ | --- | --- |
23
+ | [`osrlib.core.rng`][] | Turn a master seed into a separate random-number stream for each subsystem. |
24
+ | [`osrlib.core.dice`][] | Parse a dice expression like `"2d6+1"`, and roll it. |
25
+ | [`osrlib.core.ruleset`][] | Turn optional rules on or off, in one model the kernel reads. |
26
+ | [`osrlib.core.clock`][] | Count game time in rounds, and report each turn and day that passes. |
27
+ | [`osrlib.core.alignment`][] | The three alignments that characters and monsters share. |
28
+ | [`osrlib.core.validation`][] | The refusal a rules check returns instead of raising an exception. |
29
+ | [`osrlib.core.abilities`][] | Look up the modifier or chance an ability score gives, and make ability checks. |
30
+ | [`osrlib.core.classes`][] | Read a class's titles and level table, and award experience points (XP). |
31
+ | [`osrlib.core.monsters`][] | Read monster templates, and spawn a monster with rolled hit points. |
32
+ | [`osrlib.core.items`][] | Buy and equip items, and work out how much a character carries. |
33
+ | [`osrlib.core.spells`][] | Memorize and cast spells, and turn undead. |
34
+ | [`osrlib.core.tables`][] | Look up the printed tables, like the attack roll a THAC0 needs against an armour class. |
35
+ | [`osrlib.core.character`][] | Roll a 1st-level character, in one call or one step at a time. |
36
+ | [`osrlib.core.npc`][] | Generate a party of non-player characters (NPCs). |
37
+ | [`osrlib.core.creature`][] | The attributes rules functions read, so they accept a character or a monster. |
38
+ | [`osrlib.core.combat`][] | Roll initiative, attacks, damage, saving throws, and morale. |
39
+ | [`osrlib.core.effects`][] | Run a timed effect, like a *sleep* spell, against the clock and end it on time. |
40
+ | [`osrlib.core.treasure`][] | Roll treasure from a treasure type: coins, gems, jewellery, and magic items. |
41
+ | [`osrlib.core.events`][] | The base class of every event, and the events the kernel functions return. |
42
+
43
+ ## The crawl framework
44
+
45
+ The crawl framework, under `osrlib.crawl`, is the game built on those rules: a party that
46
+ explores a mapped dungeon, driven by commands. You author the content, start a session, and pass
47
+ it one command per player action. The session runs the exploration, encounter, and battle
48
+ procedures for you and returns the events. The table lists the modules for authoring content
49
+ first, then the session and the modules it runs.
50
+
51
+ | Module | What it's for |
52
+ | --- | --- |
53
+ | [`osrlib.crawl.dungeon`][] | Build dungeon levels from cells, edges, doors, areas, and traps. |
54
+ | [`osrlib.crawl.adventure`][] | Combine dungeons and a town into an adventure a session can play, and validate it. |
55
+ | [`osrlib.crawl.party`][] | Put characters in marching order, and move them as one group. |
56
+ | [`osrlib.crawl.gates`][] | Write the conditions the party must meet before it can go through a door or a transition. |
57
+ | [`osrlib.crawl.triggers`][] | Write what happens when an event you describe occurs in play. |
58
+ | [`osrlib.crawl.quests`][] | Write quests: their objectives and the events that complete them. |
59
+ | [`osrlib.crawl.narrative`][] | Write the text shown with a gate, trigger, or quest, and the guidance for a narrator. |
60
+ | [`osrlib.crawl.stocking`][] | Roll a room's monsters and treasure from the B/X tables. |
61
+ | [`osrlib.crawl.content_pack`][] | Move room contents from one adventure to another, without the map. |
62
+ | [`osrlib.crawl.session`][] | Start a game from a party, an adventure, and a seed, and run it one command at a time. |
63
+ | [`osrlib.crawl.commands`][] | Every command you can execute, and the session modes each one is legal in. |
64
+ | [`osrlib.crawl.events`][] | Every event a command can return, and the parser that reads a stored one. |
65
+ | [`osrlib.crawl.views`][] | What the players may see of a session, or the fuller view for the referee (game master). |
66
+ | [`osrlib.crawl.interpreter`][] | Register this listener on a session to run the adventure's triggers and quests. |
67
+ | [`osrlib.crawl.exploration`][] | How the session runs movement, doors, searching, light, rest, and wandering checks. |
68
+ | [`osrlib.crawl.encounter`][] | How the session runs surprise, distance, reaction, evasion, and pursuit. |
69
+ | [`osrlib.crawl.battle`][] | How the session runs a battle, one round at a time. |
70
+
71
+ ## Shared services
72
+
73
+ The shared services are at the top level, and both layers use them: the compiled rules content,
74
+ the exceptions, the message formatter, and the save and version documents.
75
+
76
+ | Module | What it's for |
77
+ | --- | --- |
78
+ | [`osrlib.data`][] | Load the compiled rules content and look up an entry by id, like `"fighter"` or `"goblin"`. |
79
+ | [`osrlib.errors`][] | The exceptions osrlib raises, and the failure each one means. |
80
+ | [`osrlib.messages`][] | Turn an event into a line of default English text. |
81
+ | [`osrlib.persistence`][] | Save a session to a document, and restore it by loading or replaying. |
82
+ | [`osrlib.versioning`][] | The two version numbers in every saved document, and the wrapper that contains them. |
83
+
84
+ ## Quickstart
85
+
86
+ The quickstart goes through the whole loop: characters, party, adventure, session, commands,
87
+ events, save, and load. For a step-by-step explanation of this example, see the quickstart at
88
+ https://mmacy.github.io/osrlib-python/getting-started/quickstart/.
89
+
90
+ ```python
91
+ from osrlib.core.alignment import Alignment
92
+ from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
93
+ from osrlib.core.rng import RngStreams
94
+ from osrlib.core.ruleset import Ruleset
95
+ from osrlib.crawl.adventure import Adventure, TownSpec
96
+ from osrlib.crawl.commands import EnterDungeon, MoveParty, SessionMode
97
+ from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
98
+ from osrlib.crawl.party import Party
99
+ from osrlib.crawl.session import GameSession
100
+ from osrlib.messages import format_message
101
+ from osrlib.persistence import load_game, save_game
102
+
103
+ # Roll two 1st-level characters; every random draw comes from a named, seeded stream.
104
+ rules = Ruleset()
105
+ creation = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
106
+ fighter = create_character(name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
107
+ cleric = create_character(name="Osric", class_id="cleric", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
108
+ party = Party(members=[fighter.character, cleric.character])
109
+
110
+ # The smallest adventure: a town and a one-corridor dungeon, two cells joined west-east.
111
+ crypt = DungeonSpec(
112
+ id="crypt",
113
+ name="The Old Crypt",
114
+ levels=(LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)}),),
115
+ )
116
+ town = TownSpec(name="Threshold", travel_turns={"crypt": 1})
117
+ adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,))
118
+
119
+ # A session starts in town; entering the dungeon switches it to exploring.
120
+ session = GameSession.new(party, adventure, seed=7)
121
+ session.execute(EnterDungeon(dungeon_id="crypt"))
122
+ assert session.mode is SessionMode.EXPLORING
123
+
124
+ # Commands in, events out: every rules resolution is a typed event with a message code.
125
+ result = session.execute(MoveParty(direction=Direction.EAST))
126
+ assert result.accepted
127
+ lines = [format_message(event) for event in result.events]
128
+ assert lines # every event formats to a default English line
129
+
130
+ # The whole session round-trips through JSON: same seed, same commands, same game.
131
+ document = save_game(session)
132
+ restored = load_game(document)
133
+ assert save_game(restored) == document
134
+ ```
135
+ """
@@ -0,0 +1,93 @@
1
+ """The rules kernel: the B/X rules as functions that don't need a game session.
2
+
3
+ You pass a kernel function the inputs for one rule, plus a random-number stream and a
4
+ [`Ruleset`][osrlib.core.ruleset.Ruleset]. A stream is a seeded sequence of random numbers that
5
+ repeats when you use the same seed. A ruleset is a frozen set of flags that turn optional rules on
6
+ or off for a game. The function returns the outcome together with the typed events that describe
7
+ it. An event is a frozen record of one thing that happened, like an attack roll.
8
+
9
+ The kernel has no session, no turn order, and no record of where the party is. Call the kernel
10
+ directly when you want the rules without a session, for example in a combat simulator, a script that
11
+ tests game balance, or a script that checks authored content. The dungeon-crawl framework in
12
+ `osrlib.crawl` is built on the kernel. Kernel modules never import from `osrlib.crawl`, so you
13
+ can use them without it.
14
+
15
+ Most kernel functions read rules content that osrlib compiles from the OSE SRD, the Open Game
16
+ Content text of the B/X rules. That content is the class, monster, item, and spell catalogs and the
17
+ printed tables, and [`osrlib.data`][osrlib.data] loads it. The exceptions the kernel raises are in
18
+ [`osrlib.errors`][osrlib.errors].
19
+
20
+ The kernel has these modules, in the order you usually need them:
21
+
22
+ - [`osrlib.core.rng`][osrlib.core.rng]: turn a master seed into a separate stream for each
23
+ subsystem. Every function below that rolls dice takes one of those streams.
24
+ - [`osrlib.core.dice`][osrlib.core.dice]: parse a dice expression like `"2d6+1"`, and roll it to
25
+ get each die and the total.
26
+ - [`osrlib.core.ruleset`][osrlib.core.ruleset]: the `Ruleset` that most resolution functions read.
27
+ - [`osrlib.core.clock`][osrlib.core.clock]: count game time in rounds, and get each turn and day
28
+ boundary that an advance crosses. A turn is 60 rounds.
29
+ - [`osrlib.core.alignment`][osrlib.core.alignment]: the three alignments that characters and
30
+ monsters share.
31
+ - [`osrlib.core.validation`][osrlib.core.validation]: the
32
+ [`Rejection`][osrlib.core.validation.Rejection] a rules check returns instead of raising, with
33
+ a code for the reason. A check returns a list of them, and an empty list means the action is
34
+ legal.
35
+ - [`osrlib.core.abilities`][osrlib.core.abilities]: look up the modifiers an ability score from 3
36
+ to 18 gives, make ability checks, and adjust a set of scores.
37
+ - [`osrlib.core.classes`][osrlib.core.classes]: read a class's titles and level table, award
38
+ experience points, advance levels, and make thief skill checks.
39
+ - [`osrlib.core.monsters`][osrlib.core.monsters]: read a monster template, and spawn a monster
40
+ with rolled hit points.
41
+ - [`osrlib.core.items`][osrlib.core.items]: buy and equip items, and work out encumbrance.
42
+ - [`osrlib.core.spells`][osrlib.core.spells]: memorize and cast spells, and turn undead.
43
+ - [`osrlib.core.tables`][osrlib.core.tables]: look up a cell of the printed tables from Hit Dice,
44
+ an armour class, or a 2d6 total.
45
+ - [`osrlib.core.character`][osrlib.core.character]: roll a 1st-level character from a class id,
46
+ your choices, a ruleset, and a stream. To create one step at a time, use the functions that
47
+ check each choice. They return a `Rejection` for each problem.
48
+ - [`osrlib.core.npc`][osrlib.core.npc]: generate a party of non-player characters (NPCs) from a
49
+ kind, `"basic"` or `"expert"`, a count, and two streams.
50
+ - [`osrlib.core.creature`][osrlib.core.creature]: the protocols that a character and a monster both
51
+ satisfy. The combat, spell, and effect functions take their creature arguments as these
52
+ protocols, so you can pass either.
53
+ - [`osrlib.core.combat`][osrlib.core.combat]: roll initiative, attacks, damage, saving throws, and
54
+ morale.
55
+ - [`osrlib.core.effects`][osrlib.core.effects]: run a timed effect, like a *sleep* spell, against
56
+ the clock, and end it on time.
57
+ - [`osrlib.core.treasure`][osrlib.core.treasure]: roll coins, gems, jewellery, and magic items from
58
+ a treasure-type letter.
59
+ - [`osrlib.core.events`][osrlib.core.events]: the base class of every kernel event, and the events
60
+ the kernel functions return.
61
+
62
+ Typical usage:
63
+
64
+ ```python
65
+ from osrlib.core.abilities import ability_check
66
+ from osrlib.core.clock import GameClock, TimeUnit
67
+ from osrlib.core.dice import roll
68
+ from osrlib.core.rng import RngStreams, StreamName
69
+ from osrlib.data import load_ability_tables
70
+
71
+ # One master seed forks every stream the kernel draws from.
72
+ stream = RngStreams(master_seed=7).get(StreamName.CHARACTER_CREATION)
73
+
74
+ # Roll a strength score, then read what the SRD's table grants at that score.
75
+ strength = roll("3d6", stream)
76
+ assert strength.rolls == (2, 6, 6)
77
+ assert strength.total == 14
78
+
79
+ tables = load_ability_tables()
80
+ assert tables.melee_modifier(strength.total) == 1
81
+ assert tables.open_doors_chance(strength.total) == 3
82
+
83
+ # An ability check rolls 1d20 and succeeds on equal-or-under the score.
84
+ check = ability_check(strength.total, stream)
85
+ assert (check.roll, check.success) == (13, True)
86
+
87
+ # The clock counts rounds and reports the turn and day boundaries an advance crosses.
88
+ clock = GameClock()
89
+ crossings = clock.advance(1, TimeUnit.TURN)
90
+ assert clock.rounds == 60
91
+ assert [(crossing.unit, crossing.index) for crossing in crossings] == [(TimeUnit.TURN, 1)]
92
+ ```
93
+ """