Docstrings: crawl session and events - #99
Merged
Merged
Conversation
GameSession is the entry point of the library for anyone running a game, and its docstrings now carry the whole path a front end takes: build a session with new, execute a typed command, read the result, render the events, read state through a view, and save. Every public method says what it does, what you need first, what to call next, and what to use instead, with runnable examples on new, execute, view, and the listener protocol. Every crawl event class says when it fires, which command emits it, what each of its message codes means, and who may see it, and every field of every event has an attribute docstring, so the generated event pages and the API reference describe an event without the reader opening the source. Docstrings and comments only: no signature, default, field, or behavior changed. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
The noise_since_check docstring said failing to force a door sets the flag, but _handle_force_door sets it before the roll, so any attempt past the gate sets it whether the door opens or not. A failed attempt is what alerts the area beyond, which is the part that denies the party surprise there. 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 developer reading the published reference can now run a game from the session page alone: build one with GameSession.new, execute a typed command, read the result envelope, render the events, read state through a view, and save. Every public method answers what it does, what it needs first, what to call next, and what to use instead, and new, execute, view, and the listener protocol each carry an example I ran. The public instance attributes of GameSession (the mode, the logs, the flags, the journal, the quest states, the exploration counters) each have a docstring now, so the page no longer shows a column of bare names.
Every crawl event class says when it fires, which command emits it, what each message code in its set means, and who may see it, and every field has an attribute docstring. That covers the generated pages under reference/events/, whose body is the class docstring plus the schema.
Two corrections where the code disagreed with the docstring. HoardGeneratedEvent said cache_ref is "the engine-created cache's state reference (or the group id for carried bundles)"; the only emission site (src/osrlib/crawl/exploration.py:3024, inside _generate_cache) always passes the allocated cache id, so the field now says that (src/osrlib/crawl/events.py:1137). MonsterFledEvent declares battle.side.surrendered in its code set, and nothing in the engine sets EncounterGroup.surrendered or emits that code, so the code set now says which code the engine emits and that a game adjudicating a surrender itself can use the other (src/osrlib/crawl/events.py:1033). That looks like a gap in the battle resolution rather than a docstring problem, so I left the code alone.
No block is marked no-run, and I left nothing undocumented that the reference renders.
https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa