Skip to content

LocationEnteredEvent

The party crossed into a new area, level, dungeon, or town.

Full documentation: LocationEnteredEvent. Wire type: location_entered.

Default visibility: player

Message codes: exploration.location.entered

JSON Schema

{
  "$defs": {
    "Visibility": {
      "description": "Who may see an event: the players, or only the referee.\n\nEvery event has one of these values, because in B/X the referee makes some rolls behind a screen. Filter\na log on it before you show anything to a player, or call\n`GameSession.view`, which builds the players' view and the referee's\nview for you. A narrator that plays the referee reads every event.\n\nA serialized event contains the lowercase value. The values stay fixed within a `schema_version`, the version\nstamp of the saved format.\n\nExamples:\n    ```python\n    from osrlib.core.events import DamageDealtEvent, HitPointsReportedEvent, Visibility\n\n    log = [\n        DamageDealtEvent(target_id=\"monster-0001\", amount=5),\n        HitPointsReportedEvent(target_id=\"monster-0001\", current_hp=2, max_hp=7),\n    ]\n    shown = [event.code for event in log if event.visibility is Visibility.PLAYER]\n    assert shown == [\"combat.damage.dealt\"]  # the goblin's remaining hit points stay hidden\n    ```",
      "enum": [
        "player",
        "referee"
      ],
      "title": "Visibility",
      "type": "string"
    }
  },
  "description": "The party crossed into a new area, level, dungeon, or town.\n\nAn area is a room or other region of a level that the adventure's author keyed with\ncontent. The session emits the event whenever the party's location changes at one of\nthose four scales:\n\n- `EnterDungeon` reports a dungeon entry.\n- `UseStairs`, a passage crossed with\n  `MoveParty`, and a trap that moves the party\n  report a level entry when they change the level, or a dungeon entry when they change\n  the dungeon.\n- Each of those also reports an area entry when the cell the party arrives on is in\n  an area, and so does a `MoveParty` step into a different area.\n- `TravelToTown` reports a town entry.\n- `PlaceParty`, when a referee puts the party\n  somewhere, reports a dungeon entry or a town entry.\n\nWhich fields are filled depends on the scale, because an area id is unique only\nwithin its level. An area entry has the area, its level number, and its dungeon. A\nlevel or dungeon entry has the dungeon in `location_id` and the level number beside\nit. A town entry has neither. A level or dungeon entry also records how the party got\nthere, in `via` and, for a transition it took, `transition_ref`, so you can tell from\nthe event alone whether the party climbed or descended. Use the event to\nchange the screen's header, and read the text the party can see from\n`GameSession.view`.",
  "properties": {
    "code": {
      "default": "exploration.location.entered",
      "title": "Code",
      "type": "string",
      "description": "The message code, always `exploration.location.entered`. The scale is in `location_kind`."
    },
    "visibility": {
      "$ref": "#/$defs/Visibility",
      "default": "player",
      "description": "Player visibility: arriving somewhere is the first thing the players are told."
    },
    "event_type": {
      "const": "location_entered",
      "default": "location_entered",
      "title": "Event Type",
      "type": "string",
      "description": "The event type, `location_entered`, which identifies this class in serialized form."
    },
    "location_kind": {
      "title": "Location Kind",
      "type": "string",
      "description": "Which scale was crossed: `\"area\"`, `\"level\"`, `\"dungeon\"`, or `\"town\"`."
    },
    "location_id": {
      "title": "Location Id",
      "type": "string",
      "description": "What was entered: the area id for an area entry, the dungeon id for a level or dungeon\nentry, and `\"town\"` for the town."
    },
    "level_number": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Level Number",
      "description": "The level the party is on, for area, level, and dungeon entries, and `None` for town."
    },
    "dungeon_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dungeon Id",
      "description": "The dungeon the area belongs to, filled on area entries only. On level and dungeon entries,\n`location_id` is already the dungeon id."
    },
    "narrative": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Narrative",
      "description": "The success text the adventure's author wrote on the gate the party passed, or `None` when\nthere was no gate or no text. A gate is a condition the author puts on a door or a transition,\nlike a key the party must have. The author wrote this text, not the engine, and\n`format_message` adds it after the line it builds from the\ncode. A transition to another cell of the same level enters no new level, so its gate's text is\non the `PartyMovedEvent` for the landing cell instead."
    },
    "via": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Via",
      "description": "How the party got there, on level and dungeon entries: the kind of the transition it took\n(`\"stairs_down\"`, `\"stairs_up\"`, `\"trapdoor\"`, or `\"chute\"`), `\"passage\"` for a passage it\nwalked through with `MoveParty`, `\"trap\"` for a trap that\nmoved the party, like a chute, `\"entrance\"` for\n`EnterDungeon`, and `\"placed\"` for\n`PlaceParty`. It is `None` on area and town entries, and on\nan event loaded from a save written before the field existed."
    },
    "transition_ref": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Transition Ref",
      "description": "The cell of the authored transition the party took, as\n`cell_ref` gives it, so you can find the\n`TransitionSpec` and the gate on it. Filled on a level or\ndungeon entry made through `UseStairs` or through a passage,\n`None` otherwise. For a passage crossing, it refers to the passage's cell. That cell can also have\nstairs, and passages on its other sides, so find the passage with\n`LevelSpec.passage_at` and the `direction` of the\n`MoveParty` that crossed it."
    }
  },
  "required": [
    "location_kind",
    "location_id"
  ],
  "title": "LocationEnteredEvent",
  "type": "object"
}