Skip to content

PlaceParty

Referee: move the party straight to a dungeon cell or to town.

Full documentation: PlaceParty. Wire type: place_party.

Legal session modes: exploring, game_over, town

JSON Schema

{
  "$defs": {
    "Direction": {
      "description": "The four grid directions the party faces and moves in.\n\nYou use these for the way `MoveParty` steps, the side of a\ncell `OpenDoor` works on, and the way a transition turns the\nparty on arrival. There is no up or down. A\n`TransitionSpec` moves the party between levels.\n\nThe values are lowercase strings, like `\"north\"`, and they appear in commands, events, and saves.",
      "enum": [
        "north",
        "east",
        "south",
        "west"
      ],
      "title": "Direction",
      "type": "string"
    },
    "PartyLocation": {
      "description": "Where the party is: in the base town, or on a dungeon cell facing a direction.\n\nThe session keeps one in `DungeonState.location`\nand replaces it as the party moves. Read it to draw the map and to know whether the party is in\ntown or in a dungeon. Don't change it yourself: to move the party by the referee's decision,\nexecute `PlaceParty`, which takes one of these.\n\nA town location has none of the dungeon fields, and a dungeon location has all four.\n\nAttributes:\n    kind: Whether the party is in town or in a dungeon.\n    dungeon_id: The dungeon the party is in.\n    level_number: The level the party is on.\n    position: The cell the party stands on.\n    facing: The direction the party faces.\n\nRaises:\n    ValueError: If `kind` is `\"dungeon\"` and any dungeon field is missing, or if `kind` is\n        `\"town\"` and any is set.\n\nExamples:\n    ```python\n    from osrlib.crawl.dungeon import Direction, PartyLocation\n\n    here = PartyLocation(kind=\"dungeon\", dungeon_id=\"crypt\", level_number=1, position=(0, 0), facing=Direction.EAST)\n    print(here.position, here.facing)\n    # (0, 0) east\n    ```",
      "properties": {
        "kind": {
          "enum": [
            "town",
            "dungeon"
          ],
          "title": "Kind",
          "type": "string",
          "description": "`\"town\"` when the party is in the base town, or `\"dungeon\"` when it stands on a dungeon cell.\nA new session starts in town."
        },
        "dungeon_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Dungeon Id",
          "description": "The id of the dungeon the party is in, and `None` in town."
        },
        "level_number": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Level Number",
          "description": "The number of the level the party is on, and `None` in town."
        },
        "position": {
          "anyOf": [
            {
              "maxItems": 2,
              "minItems": 2,
              "prefixItems": [
                {
                  "type": "integer"
                },
                {
                  "type": "integer"
                }
              ],
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Position",
          "description": "The cell the party stands on, and `None` in town."
        },
        "facing": {
          "anyOf": [
            {
              "$ref": "#/$defs/Direction"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The direction the party faces, and `None` in town. Draw the party's view facing this way.\n`MoveParty` includes a direction, so the party can\nstep any way, whichever way it faces, and the step turns it to face the way it moved."
        }
      },
      "required": [
        "kind"
      ],
      "title": "PartyLocation",
      "type": "object"
    }
  },
  "description": "Referee: move the party straight to a dungeon cell or to town.\n\nUse it for an authored teleport, a trapdoor you handle yourself, or a rescue. The\nparty can't be moved out of an open encounter or battle, so the command isn't legal in\n`encounter` or `battle`. To move the party away from monsters, close the encounter first\nwith `EndEncounter`. Placing the party in a dungeon\nmarks the cell explored and switches the session to `exploring`. Placing it in town\nswitches the session to `town`. The party arrives without the entry checks of a step, so\nno treasure roll, room trap, or encounter happens on the destination cell, and no game\ntime passes.\n\nBecause the switch restarts play, the command isn't legal in `victory`. It's legal in\n`game_over`, where it's the only way out: placing the dead party in town lets you buy\n*raise dead* with `PurchaseHealing`.\n\nModes:\n    `town`, `exploring`, `game_over`\n\nRejections:\n    - `session.command.wrong_mode` - an encounter or a battle is open, or the session\n      is in `victory`.\n    - `session.command.unknown_location` - the location matches no dungeon, or no\n      level in it.\n    - `session.command.out_of_bounds` - the position is off the level's grid.\n\nEvents:\n    `LocationEnteredEvent` for the\n    destination. A dungeon destination has `via` set to `\"placed\"`, so the log\n    shows that the referee moved the party rather than that it took the stairs.",
  "properties": {
    "command_type": {
      "const": "place_party",
      "default": "place_party",
      "title": "Command Type",
      "type": "string",
      "description": "The name that identifies the command class in serialized data. Each command class fixes\nit to a distinct snake_case string, like `\"move_party\"` or `\"open_door\"`, and constructing\nthe class sets it, so you never pass it yourself.\n`parse_command` and the\n`AnyCommand` union use it to rebuild the right class\nfrom a serialized mapping. A class's value never changes between releases."
    },
    "source": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source",
      "description": "Who or what issued the command on whose behalf: an authored trigger or quest id, or the\nname of one of your game's systems. The engine never reads it, so a command with a\n`source` does exactly what the same command without one does. The session logs and\nreplays it with the command, so the log alone shows why something happened. Leave it\n`None` when there's nothing to record. An empty string fails validation when the command\nis constructed."
    },
    "location": {
      "$ref": "#/$defs/PartyLocation",
      "description": "Where the party ends up. A `PartyLocation` with\n`kind=\"town\"` has no other fields. One with `kind=\"dungeon\"` needs the dungeon id, the\nlevel number, the cell, and the facing, all four together, or constructing it fails\nvalidation. The session refuses a position off the level's grid with\n`session.command.out_of_bounds`."
    }
  },
  "required": [
    "location"
  ],
  "title": "PlaceParty",
  "type": "object"
}