osrlib 1.0.0__tar.gz

osrlib-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marsh Macy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osrlib-1.0.0/LICENSE-OGL.md

@@ -0,0 +1,97 @@
+# Open Game License
+
+The files under `srd/` are the scraped [Old-School Essentials System Reference Document](https://oldschoolessentials.necroticgnome.com/srd/) and are Open Game Content under the Open Game License 1.0a, reproduced below with its complete Section 15 copyright notice as published by Necrotic Gnome. The same license applies to `src/osrlib/data/`, the machine-readable content compiled from `srd/`, which ships its own copy of this license (with the osrlib Section 15 entry) inside the package.
+
+The osrlib library code is separately licensed under the MIT license (see `LICENSE`) and is not Open Game Content.
+
+DESIGNATION OF PRODUCT IDENTITY
+
+All artwork, logos, and presentation are product identity. The names “Necrotic Gnome” and “Old-School Essentials” are product identity. All text on the main page (<https://oldschoolessentials.necroticgnome.com/srd>) is product identity.
+
+DESIGNATION OF OPEN GAME CONTENT
+
+All text and tables not declared as product identity are Open Game Content.
+
+OPEN GAME LICENSE Version 1.0a
+
+The following text is the property of Wizards of the Coast, Inc. and is Copyright 2000 Wizards of the Coast, Inc (“Wizards”). All Rights Reserved.
+
+1. Definitions: (a)”Contributors” means the copyright and/or trademark owners who have contributed Open Game Content; (b)”Derivative Material” means copyrighted material including derivative works and translations (including into other computer languages), potation, modification, correction, addition, extension, upgrade, improvement, compilation, abridgment or other form in which an existing work may be recast, transformed or adapted; (c) “Distribute” means to reproduce, license, rent, lease, sell, broadcast, publicly display, transmit or otherwise distribute; (d)”Open Game Content” means the game mechanic and includes the methods, procedures, processes and routines to the extent such content does not embody the Product Identity and is an enhancement over the prior art and any additional content clearly identified as Open Game Content by the Contributor, and means any work covered by this License, including translations and derivative works under copyright law, but specifically excludes Product Identity. (e) “Product Identity” means product and product line names, logos and identifying marks including trade dress; artifacts; creatures characters; stories, storylines, plots, thematic elements, dialogue, incidents, language, artwork, symbols, designs, depictions, likenesses, formats, poses, concepts, themes and graphic, photographic and other visual or audio representations; names and descriptions of characters, spells, enchantments, personalities, teams, personas, likenesses and special abilities; places, locations, environments, creatures, equipment, magical or supernatural abilities or effects, logos, symbols, or graphic designs; and any other trademark or registered trademark clearly identified as Product identity by the owner of the Product Identity, and which specifically excludes the Open Game Content; (f) “Trademark” means the logos, names, mark, sign, motto, designs that are used by a Contributor to identify itself or its products or the associated products contributed to the Open Game License by the Contributor (g) “Use”, “Used” or “Using” means to use, Distribute, copy, edit, format, modify, translate and otherwise create Derivative Material of Open Game Content. (h) “You” or “Your” means the licensee in terms of this agreement.
+
+2. The License: This License applies to any Open Game Content that contains a notice indicating that the Open Game Content may only be Used under and in terms of this License. You must affix such a notice to any Open Game Content that you Use. No terms may be added to or subtracted from this License except as described by the License itself. No other terms or conditions may be applied to any Open Game Content distributed using this License.
+
+3.Offer and Acceptance: By Using the Open Game Content You indicate Your acceptance of the terms of this License.
+
+4. Grant and Consideration: In consideration for agreeing to use this License, the Contributors grant You a perpetual, worldwide, royalty-free, non-exclusive license with the exact terms of this License to Use, the Open Game Content.
+
+5.Representation of Authority to Contribute: If You are contributing original material as Open Game Content, You represent that Your Contributions are Your original creation and/or You have sufficient rights to grant the rights conveyed by this License.
+
+6.Notice of License Copyright: You must update the COPYRIGHT NOTICE portion of this License to include the exact text of the COPYRIGHT NOTICE of any Open Game Content You are copying, modifying or distributing, and You must add the title, the copyright date, and the copyright holder’s name to the COPYRIGHT NOTICE of any original Open Game Content you Distribute.
+
+7. Use of Product Identity: You agree not to Use any Product Identity, including as an indication as to compatibility, except as expressly licensed in another, independent Agreement with the owner of each element of that Product Identity. You agree not to indicate compatibility or co-adaptability with any Trademark or Registered Trademark in conjunction with a work containing Open Game Content except as expressly licensed in another, independent Agreement with the owner of such Trademark or Registered Trademark. The use of any Product Identity in Open Game Content does not constitute a challenge to the ownership of that Product Identity. The owner of any Product Identity used in Open Game Content shall retain all rights, title and interest in and to that Product Identity.
+
+8. Identification: If you distribute Open Game Content You must clearly indicate which portions of the work that you are distributing are Open Game Content.
+
+9. Updating the License: Wizards or its designated Agents may publish updated versions of this License. You may use any authorized version of this License to copy, modify and distribute any Open Game Content originally distributed under any version of this License.
+
+10 Copy of this License: You MUST include a copy of this License with every copy of the Open Game Content You Distribute.
+
+11. Use of Contributor Credits: You may not market or advertise the Open Game Content using the name of any Contributor unless You have written permission from the Contributor to do so.
+
+12 Inability to Comply: If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Open Game Content due to statute, judicial order, or governmental regulation then You may not Use any Open Game Material so affected.
+
+13 Termination: This License will terminate automatically if You fail to comply with all terms herein and fail to cure such breach within 30 days of becoming aware of the breach. All sublicenses shall survive the termination of this License.
+
+14 Reformation: If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable.
+
+15 COPYRIGHT NOTICE
+
+Open Game License v 1.0 © 2000, Wizards of the Coast, Inc.
+
+System Reference Document © 2000, Wizards of the Coast, Inc.; Authors Jonathan Tweet, Monte Cook, Skip Williams, based on original material by E. Gary Gygax and Dave Arneson.
+
+System Reference Document © 2000-2003, Wizards of the Coast, Inc.; Authors Jonathan Tweet, Monte Cook, Skip Williams, Rich Baker, Andy Collins, David Noonan, Rich Redman, Bruce R. Cordell, John D. Rateliff, Thomas Reid, James Wyatt, based on original material by E. Gary Gygax and Dave Arneson.
+
+Modern System Reference Document © 2002-2004, Wizards of the Coast, Inc.; Authors Bill Slavicsek, Jeff Grubb, Rich Redman, Charles Ryan, Eric Cagle, David Noonan, Stan!, Christopher Perkins, Rodney Thompson, and JD Wiker, based on material by Jonathan Tweet, Monte Cook, Skip Williams, Richard Baker, Peter Adkison, Bruce R. Cordell, John Tynes, Andy Collins, and JD Wiker.
+
+Castles & Crusades: Players Handbook, © 2004, Troll Lord Games; Authors Davis Chenault and Mac Golden.
+
+Cave Cricket from the Tome of Horrors, © 2002, Necromancer Games, Inc.; Authors Scott Greene and Clark Peterson, based on original material by Gary Gygax.
+
+Crab, Monstrous from the Tome of Horrors, © 2002, Necromancer Games, Inc.; Author Scott Greene, based on original material by Gary Gygax.
+
+Fly, Giant from the Tome of Horrors, © 2002, Necromancer Games, Inc.; Author Scott Greene, based on original material by Gary Gygax.
+
+Golem, Wood from the Tome of Horrors, © 2002, Necromancer Games, Inc.; Authors Scott Greene and Patrick Lawinger.
+
+Kamadan from the Tome of Horrors, © 2002, Necromancer Games, Inc.; Author Scott Greene, based on original material by Nick Louth.
+
+Rot Grub from the Tome of Horrors, © 2002, Necromancer Games, Inc.; Authors Scott Greene and Clark Peterson, based on original material by Gary Gygax.
+
+Labyrinth Lord™ © 2007-2009, Daniel Proctor. Author Daniel Proctor.
+
+B/X Essentials: Core Rules © 2017 Gavin Norman. Author Gavin Norman.
+
+B/X Essentials: Classes and Equipment © 2017 Gavin Norman. Author Gavin Norman.
+
+B/X Essentials: Cleric and Magic-User Spells © 2017 Gavin Norman. Author Gavin Norman.
+
+B/X Essentials: Monsters © 2017 Gavin Norman. Author Gavin Norman.
+
+B/X Essentials: Adventures and Treasures © 2018 Gavin Norman. Author Gavin Norman.
+
+Old-School Essentials Core Rules © 2018 Gavin Norman.
+
+Old-School Essentials Classic Fantasy: Genre Rules © 2018 Gavin Norman.
+
+Old-School Essentials Classic Fantasy: Cleric and Magic-User Spells © 2018 Gavin Norman.
+
+Old-School Essentials Classic Fantasy: Monsters © 2018 Gavin Norman.
+
+Old-School Essentials Classic Fantasy: Treasures © 2018 Gavin Norman.
+
+Old-School Essentials Classic Fantasy: Rules Tome © 2019 Gavin Norman.
+
+Old-School Essentials System Reference Document © 2019 Gavin Norman. Author Gavin Norman.
+
+END OF LICENSE

osrlib-1.0.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: osrlib
+Version: 1.0.0
+Summary: B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers
+Keywords: bx,dungeon-crawler,game-engine,old-school-essentials,osr,rpg,srd,ttrpg
+Author: Marsh Macy
+License-Expression: MIT AND LicenseRef-OGL-1.0a
+License-File: LICENSE
+License-File: LICENSE-OGL.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.14
+Project-URL: Changelog, https://github.com/mmacy/osrlib-python/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://mmacy.github.io/osrlib-python/
+Project-URL: Issues, https://github.com/mmacy/osrlib-python/issues
+Project-URL: Repository, https://github.com/mmacy/osrlib-python
+Description-Content-Type: text/markdown
+
+# osrlib
+
+A Python library implementing 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 are sourced 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.
+
+The library is headless and sans-I/O — it never renders, prompts, sleeps, or touches the network — and every game it runs is deterministic: the same seed and the same commands always replay the same game. Four kinds of consumer are first-class: 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 using the kernel à la carte.
+
+**Status:** released — [osrlib on PyPI](https://pypi.org/project/osrlib/). The public API is frozen, and 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 command, event, rejection code, and content id.
+
+## Installation
+
+Requires Python ≥ 3.14. The only runtime dependency is [pydantic](https://docs.pydantic.dev/).
+
+```sh
+uv add osrlib
+```
+
+or, with pip:
+
+```sh
+pip install osrlib
+```
+
+## Quickstart
+
+```python
+from osrlib.core.alignment import Alignment
+from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
+from osrlib.core.rng import RngStreams
+from osrlib.core.ruleset import Ruleset
+from osrlib.crawl.adventure import Adventure, TownSpec
+from osrlib.crawl.commands import EnterDungeon, MoveParty, SessionMode
+from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
+from osrlib.crawl.party import Party
+from osrlib.crawl.session import GameSession
+from osrlib.messages import format_message
+from osrlib.persistence import load_game, save_game
+
+# Roll two 1st-level characters; every random draw comes from a named, seeded stream.
+rules = Ruleset()
+creation = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
+fighter = create_character(name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
+cleric = create_character(name="Osric", class_id="cleric", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
+party = Party(members=[fighter.character, cleric.character])
+
+# The smallest adventure: a town and a one-corridor dungeon, two cells joined west-east.
+crypt = DungeonSpec(
+    id="crypt",
+    name="The Old Crypt",
+    levels=(LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)}),),
+)
+town = TownSpec(name="Threshold", travel_turns={"crypt": 1})
+adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,))
+
+# A session starts in town; entering the dungeon switches it to exploring.
+session = GameSession.new(party, adventure, seed=7)
+session.execute(EnterDungeon(dungeon_id="crypt"))
+assert session.mode is SessionMode.EXPLORING
+
+# Commands in, events out: every rules resolution is a typed event with a message code.
+result = session.execute(MoveParty(direction=Direction.EAST))
+assert result.accepted
+lines = [format_message(event) for event in result.events]
+assert lines  # every event formats to a default English line
+
+# The whole session round-trips through JSON: same seed, same commands, same game.
+document = save_game(session)
+restored = load_game(document)
+assert save_game(restored) == document
+```
+
+The [documentation site](https://mmacy.github.io/osrlib-python/) walks this example step by step, then builds out from it: [building an adventure](https://mmacy.github.io/osrlib-python/getting-started/building-an-adventure/), the [session and event loop](https://mmacy.github.io/osrlib-python/guides/sessions-commands-events/), and complete [front-end walk-throughs](https://mmacy.github.io/osrlib-python/front-ends/tui-crawler/) for the two example games in `examples/`.
+
+## Determinism
+
+Determinism is a public API guarantee. All randomness flows through named PCG64 streams forked from a master seed, so the same seed and the same key always produce the same stream — independently of any other stream:
+
+```python
+from osrlib.core.dice import roll
+from osrlib.core.rng import RngStreams
+
+streams_a = RngStreams(master_seed=42)
+streams_b = RngStreams(master_seed=42)
+
+rolls_a = [roll("2d6×10", streams_a.get("treasure")).total for _ in range(3)]
+rolls_b = [roll("2d6×10", streams_b.get("treasure")).total for _ in range(3)]
+assert rolls_a == rolls_b  # same seed + same key → identical sequences
+```
+
+Successive rolls on one stream differ, of course; reproducibility across derivations is the contract. Saved games replay from the seed and the command log, so a loaded game is bit-for-bit the game you saved.
+
+## SRD data pipeline
+
+The game data in `src/osrlib/data/` is generated from the scraped SRD markdown in `srd/` and is never hand-edited. Regenerate it with:
+
+```sh
+uv run python -m tools.srd_compile
+```
+
+CI regenerates the data and fails on any diff, so `srd/`, the compiler, and the generated data cannot silently drift. Parser corrections belong in `tools/srd_compile/overrides/`, never in the output; every override carries a reason and is recorded in the output entry's `overrides_applied` provenance list. Rules interpretations and adaptations are documented in the [adaptations register](https://mmacy.github.io/osrlib-python/adaptations/).
+
+## Contributing
+
+Requires Python ≥ 3.14 and [uv](https://docs.astral.sh/uv/). Install from source and run the checks the way CI does:
+
+```sh
+git clone https://github.com/mmacy/osrlib-python.git
+cd osrlib-python
+uv sync
+uv run ruff format --check
+uv run ruff check
+uv run pyright
+uv run pytest
+uv run mkdocs build --strict
+```
+
+The design is documented in [the specification](docs/spec.md): architecture, contracts, rules scope, and the phased roadmap.
+
+## Licensing
+
+This repository contains two kinds of material under two licenses:
+
+- **Library code** is licensed under the [MIT license](LICENSE).
+- **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 ships its own copy of the license, with the osrlib Section 15 entry, inside the built wheel.
+
+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; no claim of compatibility is made.

osrlib-1.0.0/README.md

@@ -0,0 +1,125 @@
+# osrlib
+
+A Python library implementing 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 are sourced 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.
+
+The library is headless and sans-I/O — it never renders, prompts, sleeps, or touches the network — and every game it runs is deterministic: the same seed and the same commands always replay the same game. Four kinds of consumer are first-class: 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 using the kernel à la carte.
+
+**Status:** released — [osrlib on PyPI](https://pypi.org/project/osrlib/). The public API is frozen, and 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 command, event, rejection code, and content id.
+
+## Installation
+
+Requires Python ≥ 3.14. The only runtime dependency is [pydantic](https://docs.pydantic.dev/).
+
+```sh
+uv add osrlib
+```
+
+or, with pip:
+
+```sh
+pip install osrlib
+```
+
+## Quickstart
+
+```python
+from osrlib.core.alignment import Alignment
+from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
+from osrlib.core.rng import RngStreams
+from osrlib.core.ruleset import Ruleset
+from osrlib.crawl.adventure import Adventure, TownSpec
+from osrlib.crawl.commands import EnterDungeon, MoveParty, SessionMode
+from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
+from osrlib.crawl.party import Party
+from osrlib.crawl.session import GameSession
+from osrlib.messages import format_message
+from osrlib.persistence import load_game, save_game
+
+# Roll two 1st-level characters; every random draw comes from a named, seeded stream.
+rules = Ruleset()
+creation = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
+fighter = create_character(name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
+cleric = create_character(name="Osric", class_id="cleric", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
+party = Party(members=[fighter.character, cleric.character])
+
+# The smallest adventure: a town and a one-corridor dungeon, two cells joined west-east.
+crypt = DungeonSpec(
+    id="crypt",
+    name="The Old Crypt",
+    levels=(LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)}),),
+)
+town = TownSpec(name="Threshold", travel_turns={"crypt": 1})
+adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,))
+
+# A session starts in town; entering the dungeon switches it to exploring.
+session = GameSession.new(party, adventure, seed=7)
+session.execute(EnterDungeon(dungeon_id="crypt"))
+assert session.mode is SessionMode.EXPLORING
+
+# Commands in, events out: every rules resolution is a typed event with a message code.
+result = session.execute(MoveParty(direction=Direction.EAST))
+assert result.accepted
+lines = [format_message(event) for event in result.events]
+assert lines  # every event formats to a default English line
+
+# The whole session round-trips through JSON: same seed, same commands, same game.
+document = save_game(session)
+restored = load_game(document)
+assert save_game(restored) == document
+```
+
+The [documentation site](https://mmacy.github.io/osrlib-python/) walks this example step by step, then builds out from it: [building an adventure](https://mmacy.github.io/osrlib-python/getting-started/building-an-adventure/), the [session and event loop](https://mmacy.github.io/osrlib-python/guides/sessions-commands-events/), and complete [front-end walk-throughs](https://mmacy.github.io/osrlib-python/front-ends/tui-crawler/) for the two example games in `examples/`.
+
+## Determinism
+
+Determinism is a public API guarantee. All randomness flows through named PCG64 streams forked from a master seed, so the same seed and the same key always produce the same stream — independently of any other stream:
+
+```python
+from osrlib.core.dice import roll
+from osrlib.core.rng import RngStreams
+
+streams_a = RngStreams(master_seed=42)
+streams_b = RngStreams(master_seed=42)
+
+rolls_a = [roll("2d6×10", streams_a.get("treasure")).total for _ in range(3)]
+rolls_b = [roll("2d6×10", streams_b.get("treasure")).total for _ in range(3)]
+assert rolls_a == rolls_b  # same seed + same key → identical sequences
+```
+
+Successive rolls on one stream differ, of course; reproducibility across derivations is the contract. Saved games replay from the seed and the command log, so a loaded game is bit-for-bit the game you saved.
+
+## SRD data pipeline
+
+The game data in `src/osrlib/data/` is generated from the scraped SRD markdown in `srd/` and is never hand-edited. Regenerate it with:
+
+```sh
+uv run python -m tools.srd_compile
+```
+
+CI regenerates the data and fails on any diff, so `srd/`, the compiler, and the generated data cannot silently drift. Parser corrections belong in `tools/srd_compile/overrides/`, never in the output; every override carries a reason and is recorded in the output entry's `overrides_applied` provenance list. Rules interpretations and adaptations are documented in the [adaptations register](https://mmacy.github.io/osrlib-python/adaptations/).
+
+## Contributing
+
+Requires Python ≥ 3.14 and [uv](https://docs.astral.sh/uv/). Install from source and run the checks the way CI does:
+
+```sh
+git clone https://github.com/mmacy/osrlib-python.git
+cd osrlib-python
+uv sync
+uv run ruff format --check
+uv run ruff check
+uv run pyright
+uv run pytest
+uv run mkdocs build --strict
+```
+
+The design is documented in [the specification](docs/spec.md): architecture, contracts, rules scope, and the phased roadmap.
+
+## Licensing
+
+This repository contains two kinds of material under two licenses:
+
+- **Library code** is licensed under the [MIT license](LICENSE).
+- **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 ships its own copy of the license, with the osrlib Section 15 entry, inside the built wheel.
+
+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; no claim of compatibility is made.

osrlib-1.0.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "osrlib"
+version = "1.0.0"
+description = "B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers"
+readme = "README.md"
+# The wheel ships Open Game Content (osrlib/data/*.json and its LICENSE-OGL.md
+# copy) beside MIT-licensed code, so the expression names both; the LicenseRef-
+# form is PEP 639's escape hatch for licenses off the SPDX list.
+license = "MIT AND LicenseRef-OGL-1.0a"
+license-files = ["LICENSE", "LICENSE-OGL.md"]
+authors = [{ name = "Marsh Macy" }]
+requires-python = ">=3.14"
+dependencies = ["pydantic>=2"]
+keywords = [
+    "bx",
+    "dungeon-crawler",
+    "game-engine",
+    "old-school-essentials",
+    "osr",
+    "rpg",
+    "srd",
+    "ttrpg",
+]
+# No `License ::` classifier beside an SPDX expression, per PEP 639. Only 3.14
+# carries a version classifier because only 3.14 is tested; future minors earn
+# theirs by entering CI.
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment :: Role-Playing",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://mmacy.github.io/osrlib-python/"
+Repository = "https://github.com/mmacy/osrlib-python"
+Issues = "https://github.com/mmacy/osrlib-python/issues"
+Changelog = "https://github.com/mmacy/osrlib-python/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6",
+    "pyright>=1.1.411",
+    "pytest>=8",
+    "pytest-examples>=0.0.18",
+    "ruff>=0.11",
+    { include-group = "docs" },
+    { include-group = "examples" },
+]
+# The documentation site's toolchain (mkdocs-material + mkdocstrings and the
+# build-time page generators); included by dev so `uv sync` stays one command.
+# gen-files and literate-nav are pinned exactly: their next releases (0.6.1 and
+# 0.6.3) depend on `properdocs`, an unvetted mkdocs fork that ships an import
+# hook redirecting all mkdocs.* imports to itself. Do not bump either pin
+# without inspecting the release's dependency set first.
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-gen-files==0.5.0",
+    "mkdocs-literate-nav==0.6.1",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+]
+# The example front ends' dependencies (the FastAPI wrapper and its TestClient);
+# the package's runtime dependency remains pydantic alone.
+examples = [
+    "fastapi>=0.115",
+    "httpx>=0.28",
+    "uvicorn>=0.32",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "B",   # bugbear
+    "D",   # pydocstyle
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "W",   # pycodestyle warnings
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["osrlib"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pyright]
+include = ["src", "examples"]
+typeCheckingMode = "basic"
+pythonVersion = "3.14"

osrlib-1.0.0/src/osrlib/__init__.py

@@ -0,0 +1,65 @@
+"""Old-School Essentials (B/X) rules engine for turn-based dungeon crawlers.
+
+osrlib is the rules authority and game-state engine; the game supplies presentation,
+input, and content. The library is headless and sans-I/O: it never renders, prompts,
+sleeps, or touches the network, and all randomness flows through named deterministic
+streams (see [`osrlib.core.rng`][osrlib.core.rng]).
+
+Every symbol has exactly one import home: the kernel under `osrlib.core`, the crawl
+framework under `osrlib.crawl`, and the shared services at the top level —
+[`osrlib.data`][osrlib.data] (compiled SRD catalogs), [`osrlib.errors`][osrlib.errors]
+(the typed exception hierarchy), [`osrlib.messages`][osrlib.messages] (message-code
+formatting), [`osrlib.persistence`][osrlib.persistence] (saves and replay), and
+[`osrlib.versioning`][osrlib.versioning] (schema and engine version stamping). The
+package root re-exports nothing.
+
+The quickstart below crosses the whole loop — characters, party, adventure, session,
+commands, events, save, and load. Full documentation, including a stepwise version of
+this example: https://mmacy.github.io/osrlib-python/
+
+```python
+from osrlib.core.alignment import Alignment
+from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
+from osrlib.core.rng import RngStreams
+from osrlib.core.ruleset import Ruleset
+from osrlib.crawl.adventure import Adventure, TownSpec
+from osrlib.crawl.commands import EnterDungeon, MoveParty, SessionMode
+from osrlib.crawl.dungeon import Direction, DungeonSpec, Edge, EdgeKind, LevelSpec
+from osrlib.crawl.party import Party
+from osrlib.crawl.session import GameSession
+from osrlib.messages import format_message
+from osrlib.persistence import load_game, save_game
+
+# Roll two 1st-level characters; every random draw comes from a named, seeded stream.
+rules = Ruleset()
+creation = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
+fighter = create_character(name="Hild", class_id="fighter", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
+cleric = create_character(name="Osric", class_id="cleric", alignment=Alignment.LAWFUL, ruleset=rules, stream=creation)
+party = Party(members=[fighter.character, cleric.character])
+
+# The smallest adventure: a town and a one-corridor dungeon, two cells joined west-east.
+crypt = DungeonSpec(
+    id="crypt",
+    name="The Old Crypt",
+    levels=(LevelSpec(number=1, width=2, height=1, entrance=(0, 0), edges={"1,0:west": Edge(kind=EdgeKind.OPEN)}),),
+)
+town = TownSpec(name="Threshold", travel_turns={"crypt": 1})
+adventure = Adventure(name="A First Delve", town=town, dungeons=(crypt,))
+
+# A session starts in town; entering the dungeon switches it to exploring.
+session = GameSession.new(party, adventure, seed=7)
+session.execute(EnterDungeon(dungeon_id="crypt"))
+assert session.mode is SessionMode.EXPLORING
+
+# Commands in, events out: every rules resolution is a typed event with a message code.
+result = session.execute(MoveParty(direction=Direction.EAST))
+assert result.accepted
+lines = [format_message(event) for event in result.events]
+assert lines  # every event formats to a default English line
+
+# The whole session round-trips through JSON: same seed, same commands, same game.
+document = save_game(session)
+restored = load_game(document)
+assert save_game(restored) == document
+```
+"""

osrlib-1.0.0/src/osrlib/core/__init__.py

@@ -0,0 +1,5 @@
+"""The rules kernel: pure mechanics with no game loop.
+
+Kernel modules never import from `osrlib.crawl` (the framework layer) and are usable
+à la carte — a game that wants only the math can call them directly.
+"""