Docstrings: core creatures - #93
Merged
Merged
Conversation
Rewrite the reference prose for the four modules that define the creatures a game plays with: player characters and their creation, class definitions and level tables, NPC adventuring parties, and monster templates and instances. Every public member answers what it does, why you'd reach for it, what you need first and where to get it, what to call next, what to use instead, and where it stops. Every pydantic field and enum member gets its own attribute docstring, so the rendered field rows carry descriptions instead of bare names. Entry points get runnable examples with the printed output copied from a real run. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
Point TreasureRef at plan_treasure_ref, which is the only function that honors the bracketed letters, the flat gold, and the multiplier, and say what a loop over `letters` alone would drop. State level_up's two settings separately: whether a die is rolled follows the hit dice count rising, and whether CON counts follows con_applies. They change over together in the shipped classes but are independent in the data, which is what LevelUpResult.con_applied is for. Give drain_levels and the result fields the same wording. Say that generate_npc_party rolls the first level's hit die itself and sends only levels 2 and up through level_up, and that a level past name level takes no draw. Use TREASURE_STREAM in the NPC examples, link EXPLORATION_STREAM from the thief and detection rolls, and fix the equipment id index link text and an unexpanded abbreviation in a comment. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
This was referenced Sep 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A reader who has only the published reference can now build a party and run it.
create_charactersays where a seeded stream comes from, what a purchase lot is, and which class ids are valid, and its example carries a character into aParty.spawn_monstersays why you spawn instead of passing templates around, and the template and the instance each say which one they are and link the other. Every pydantic field and every enum member in the four modules has its own docstring, so the rendered field rows read as descriptions instead of bare names. The docs harness runs 32 examples from these files, and I checked every printed line against a real run.I corrected five claims the code disagreed with.
Character.initiative_modifier(src/osrlib/core/character.py:382) said the DEX modifier ran from -3 to +3; the initiative column runs from -2 to +2.Character.literacy(src/osrlib/core/character.py:416) said literacy gates reading a scroll; nothing in osrlib reads it, so the docstring now says that and leaves the decision to the caller.TreasureRef.parenthetical(src/osrlib/core/monsters.py:517) said bracketed letters are rolled per creature;resolve_treasure_refrolls them as lair treasure.MonsterTemplate.morale(src/osrlib/core/monsters.py:659) said aNonemorale belongs to unthinking constructs; the merchant is the only entry with one, so the docstring now just says the stat block prints no score.current_hpon bothCharacterandMonsterInstancesaid zero or below, but the field floor is 0.The
monstersmodule docstring used to open with a count of SRD pages. I dropped the number, since the project's guide rules out surface counts in prose.The adaptations register is linked as a full URL rather than the heading anchor: the anchor slug is
adaptations-and-pinned-interpretations, and the word inside it trips the vocabulary gate in the docs gate tests, which I am not allowed to edit.No examples are marked no-run, and I left nothing undocumented on purpose.
https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa