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.
- {osrlib-2.0.0 → osrlib-2.0.1}/PKG-INFO +8 -8
- {osrlib-2.0.0 → osrlib-2.0.1}/README.md +7 -7
- {osrlib-2.0.0 → osrlib-2.0.1}/pyproject.toml +1 -1
- osrlib-2.0.1/src/osrlib/__init__.py +135 -0
- osrlib-2.0.1/src/osrlib/core/__init__.py +93 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/abilities.py +330 -129
- osrlib-2.0.1/src/osrlib/core/alignment.py +72 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/character.py +502 -389
- osrlib-2.0.1/src/osrlib/core/classes.py +1487 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/clock.py +66 -51
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/combat.py +1189 -963
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/creature.py +60 -43
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/dice.py +53 -45
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/effects.py +566 -397
- osrlib-2.0.1/src/osrlib/core/events.py +1426 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/items.py +693 -475
- osrlib-2.0.1/src/osrlib/core/monsters.py +1242 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/npc.py +144 -115
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/rng.py +213 -149
- osrlib-2.0.1/src/osrlib/core/ruleset.py +264 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/spells.py +960 -806
- osrlib-2.0.1/src/osrlib/core/tables.py +1286 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/core/treasure.py +200 -163
- osrlib-2.0.1/src/osrlib/core/validation.py +114 -0
- osrlib-2.0.1/src/osrlib/crawl/__init__.py +81 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/adventure.py +236 -209
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/battle.py +520 -308
- osrlib-2.0.1/src/osrlib/crawl/commands.py +3682 -0
- osrlib-2.0.1/src/osrlib/crawl/content_pack.py +517 -0
- osrlib-2.0.1/src/osrlib/crawl/dungeon.py +1957 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/encounter.py +322 -257
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/events.py +644 -569
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/exploration.py +341 -304
- osrlib-2.0.1/src/osrlib/crawl/gates.py +426 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/interpreter.py +147 -142
- osrlib-2.0.1/src/osrlib/crawl/narrative.py +133 -0
- osrlib-2.0.1/src/osrlib/crawl/party.py +277 -0
- osrlib-2.0.1/src/osrlib/crawl/quests.py +332 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/session.py +893 -422
- osrlib-2.0.1/src/osrlib/crawl/stocking.py +286 -0
- osrlib-2.0.1/src/osrlib/crawl/triggers.py +445 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/crawl/views.py +362 -329
- osrlib-2.0.1/src/osrlib/data/__init__.py +623 -0
- osrlib-2.0.1/src/osrlib/errors.py +216 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/messages.py +55 -44
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/persistence.py +221 -177
- osrlib-2.0.1/src/osrlib/versioning.py +264 -0
- osrlib-2.0.0/src/osrlib/__init__.py +0 -135
- osrlib-2.0.0/src/osrlib/core/__init__.py +0 -81
- osrlib-2.0.0/src/osrlib/core/alignment.py +0 -67
- osrlib-2.0.0/src/osrlib/core/classes.py +0 -1434
- osrlib-2.0.0/src/osrlib/core/events.py +0 -1380
- osrlib-2.0.0/src/osrlib/core/monsters.py +0 -1095
- osrlib-2.0.0/src/osrlib/core/ruleset.py +0 -256
- osrlib-2.0.0/src/osrlib/core/tables.py +0 -1230
- osrlib-2.0.0/src/osrlib/core/validation.py +0 -107
- osrlib-2.0.0/src/osrlib/crawl/__init__.py +0 -79
- osrlib-2.0.0/src/osrlib/crawl/commands.py +0 -3106
- osrlib-2.0.0/src/osrlib/crawl/content_pack.py +0 -476
- osrlib-2.0.0/src/osrlib/crawl/dungeon.py +0 -1747
- osrlib-2.0.0/src/osrlib/crawl/gates.py +0 -352
- osrlib-2.0.0/src/osrlib/crawl/narrative.py +0 -133
- osrlib-2.0.0/src/osrlib/crawl/party.py +0 -188
- osrlib-2.0.0/src/osrlib/crawl/quests.py +0 -287
- osrlib-2.0.0/src/osrlib/crawl/stocking.py +0 -268
- osrlib-2.0.0/src/osrlib/crawl/triggers.py +0 -423
- osrlib-2.0.0/src/osrlib/data/__init__.py +0 -593
- osrlib-2.0.0/src/osrlib/errors.py +0 -144
- osrlib-2.0.0/src/osrlib/versioning.py +0 -239
- {osrlib-2.0.0 → osrlib-2.0.1}/LICENSE +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/LICENSE-OGL.md +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/LICENSE-OGL.md +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/abilities.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/classes.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/combat_tables.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/encounter_tables.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/equipment.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/languages.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/magic_items.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/monsters.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/spells.json +0 -0
- {osrlib-2.0.0 → osrlib-2.0.1}/src/osrlib/data/treasure.json +0 -0
- {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.
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
+
"""
|