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 is allowed to see an event.\n\nEvery event has one of these two values, and the split exists because B/X keeps some rolls behind the\nreferee's screen. Filter a log on it before you show anything to a player, or call\n`GameSession.view`, which builds the player's and the referee's\nviews for you. A narrator playing referee reads both.\n\nThe values are the lowercase strings and they serialize into every event, so a renamed value is a\n`schema_version` bump.\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\nEmitted whenever the party's location changes at one of those four scales:\n`EnterDungeon` on arrival at a dungeon,\n`UseStairs` on a level or dungeon change,\n`MoveParty` on stepping into a keyed area,\n`TravelToTown` on arriving back in town,\nand `PlaceParty` when a referee puts the\nparty somewhere.\n\nWhich fields are filled depends on the scale, because an area id is unique only\nwithin its level: an area entry names the area, its level number, and its dungeon,\na level or dungeon entry names the dungeon in `location_id` with the level number\nbeside it, and a town entry names neither. A level or dungeon entry also says how the\nparty got there, in `via` and, for a transition it took, `transition_ref`, so a line\nwritten from the event alone can say the party climbed rather than descended. Use it\nto swap 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 table is told."
    },
    "event_type": {
      "const": "location_entered",
      "default": "location_entered",
      "title": "Event Type",
      "type": "string",
      "description": "The wire discriminator, `location_entered`."
    },
    "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. The other kinds already name\nthe dungeon in `location_id`."
    },
    "narrative": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Narrative",
      "description": "The success text the adventure's author wrote on the gate that was crossed, when there was\none, else `None`. A gate is the condition an author puts on a transition, like a door that\nopens only for a key. This is content rather than prose the engine wrote: the event still has\nits code and its facts, and `format_message` appends this line\nafter the templated one."
    },
    "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\"`), `\"trap\"` for a trap that dropped\nthe party through the floor, `\"entrance\"` for `EnterDungeon`,\nand `\"placed\"` for `PlaceParty`. It is `None` on area and\ntown entries, and on an 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 a consumer can find the\n`TransitionSpec` and the gate on it. Filled on a level or\ndungeon entry made through `UseStairs`, `None` otherwise."
    }
  },
  "required": [
    "location_kind",
    "location_id"
  ],
  "title": "LocationEnteredEvent",
  "type": "object"
}