dndkit 0.4.0__py3-none-any.whl

dndkit/__init__.py

@@ -0,0 +1,10 @@
+"""dndkit: a D&D 5e campaign server for voice and chat game masters."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dndkit")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

dndkit/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m dndkit` runs the server over stdio."""
+
+from dndkit.app import main
+
+if __name__ == "__main__":
+    main()

dndkit/activity.py

@@ -0,0 +1,68 @@
+"""What the model asks of the server, kept for the game master's backstage.
+
+Every tool call is recorded with its arguments, its answer or its error and
+how long it took, and so are the skills the client fetches: enough to follow
+what the model does, and to see why something did not happen. The log lives
+in memory for the session, like the dice log; nothing is saved. Calls a client
+refuses before sending them never reach the server, so they are not here.
+"""
+
+import itertools
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+
+TEXT_LIMIT = 1200  # characters kept of arguments and answers
+
+
+@dataclass(frozen=True)
+class Call:
+    """One request from the model."""
+
+    number: int
+    at: float  # unix time
+    kind: str  # "tool" or "skill"
+    name: str
+    arguments: str
+    outcome: str
+    failed: bool
+    milliseconds: int
+
+
+class ActivityLog:
+    """The latest calls, safe from FastMCP's worker threads."""
+
+    def __init__(self, size: int = 200) -> None:
+        self._calls: deque[Call] = deque(maxlen=size)
+        self._counter = itertools.count(1)
+        self._lock = threading.Lock()
+        self.on_record: Callable[[], None] = lambda: None  # set by the server's lifespan
+
+    def record(
+        self, kind: str, name: str, arguments: str, outcome: str, failed: bool, started: float
+    ) -> None:
+        """Keep one call; *started* is its ``time.perf_counter()`` start."""
+        call = Call(
+            number=next(self._counter),
+            at=time.time(),
+            kind=kind,
+            name=name,
+            arguments=_cut(arguments),
+            outcome=_cut(outcome),
+            failed=failed,
+            milliseconds=round((time.perf_counter() - started) * 1000),
+        )
+        with self._lock:
+            self._calls.append(call)
+        self.on_record()
+
+    def recent(self) -> list[Call]:
+        """Oldest first."""
+        with self._lock:
+            return list(self._calls)
+
+
+def _cut(text: str) -> str:
+    return text if len(text) <= TEXT_LIMIT else text[: TEXT_LIMIT - 1] + "…"

dndkit/app.py

@@ -0,0 +1,105 @@
+"""Server assembly and the command-line entry point.
+
+Nothing touches the disk at import: the campaign store opens in the server's
+lifespan, so importing the package (tests, ``fastmcp inspect``) has no side
+effect, and a bad data directory fails the start with one clear log line.
+The web pages, when configured, run in the same lifespan.
+"""
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastmcp import FastMCP
+
+from dndkit import __version__
+from dndkit.activity import ActivityLog
+from dndkit.config import (
+    WebSettings,
+    configure_logging,
+    resolve_data_dir,
+    resolve_web_settings,
+)
+from dndkit.game.dice import DiceLog
+from dndkit.skills import register_skills
+from dndkit.storage import CampaignStore
+from dndkit.tools import ALL_TOOLS
+from dndkit.tools.apps import register_apps
+from dndkit.tools.deps import DICE_LOG_KEY, STORE_KEY
+from dndkit.tools.recorder import Recorder
+from dndkit.tools.schema import compact
+from dndkit.web import Changes, web_pages
+
+logger = logging.getLogger(__name__)
+
+INSTRUCTIONS = """\
+Campaign manager for a Dungeons & Dragons 5e game master, built for voice play.
+You are the game master: you lead, and act with the tools without asking leave.
+Read skill://dnd-game-master/SKILL.md first: the tools, a session's course, and
+preparing a campaign by the rules; check_campaign then lists what is missing.
+One campaign is active at a time; list_campaigns and load_campaign switch it.
+Each spoken turn opens with the speaker's name: a player. seat_players says
+who plays which character; "I attack" from a player is their character's
+action. At the start of a session, ask who is at the table and call
+seat_players with start_over; call it again when someone arrives or leaves.
+Characters, NPCs, locations and quests are found by name (case and accents do
+not matter) or by ID. A failed call says why and lists the known names: retry
+with one of them rather than inventing a new entity. Use change_hit_points for
+damage and healing (characters and monsters alike), roll_dice for every roll,
+and log notable moments with add_event. Resolve every roll yourself: the attack
+against the target's AC, then the damage, applied with change_hit_points; never
+ask the players for a total or a number the tools hold (get_character gives a
+character's spell attack and save DC). You run the monsters: one the story
+needs and the bestiary lacks is yours to create with save_monster (a challenge
+rating sets its stats; mark the boss), then plan_encounter rates the fight.
+How-to skills, which also bring their tools when your client hides them:
+skill://dnd-monsters/SKILL.md (save_monster, plan_encounter: monsters, bosses,
+sizing a fight) and skill://dnd-battle-map/SKILL.md (the map tools)."""
+
+
+def build_server(data_dir: Path | None = None, web: WebSettings | None = None) -> FastMCP:
+    """The MCP server; campaigns live in *data_dir*, else the configured directory.
+
+    With *web*, the server also serves the live web pages (``web/``).
+    """
+
+    activity = ActivityLog()  # in memory, filled by the Recorder middleware
+
+    @asynccontextmanager
+    async def lifespan(_server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+        directory = data_dir or resolve_data_dir()
+        logger.info("dndkit %s, data in %s", __version__, directory)
+        changes = Changes()
+        store = CampaignStore(directory, on_change=changes.notify)
+        dice_log = DiceLog(on_record=changes.notify)
+        activity.on_record = changes.notify_activity
+        try:
+            async with web_pages(web, store, dice_log, activity, changes):
+                yield {STORE_KEY: store, DICE_LOG_KEY: dice_log}
+        finally:
+            store.close()
+
+    server = FastMCP(
+        name="dndkit",
+        instructions=INSTRUCTIONS,
+        version=__version__,
+        lifespan=lifespan,
+        # Unexpected exceptions reach the client as a bare failure; game
+        # errors (``GameError``) keep their message, written for the model.
+        mask_error_details=True,
+        middleware=[Recorder(activity)],
+    )
+    for fn in ALL_TOOLS:
+        tool = server.add_tool(fn)
+        tool.parameters = compact(tool.parameters)
+    register_apps(server)
+    register_skills(server, activity)
+    return server
+
+
+def main() -> None:
+    """Run the server over stdio, the transport MCP clients launch."""
+    configure_logging()
+    build_server(web=resolve_web_settings()).run(show_banner=False)

dndkit/config.py

@@ -0,0 +1,104 @@
+"""Runtime configuration: where the data lives, how much is logged, the web pages.
+
+MCP clients such as roomkit-ui or Claude Desktop start the server with no
+working directory of their own (often ``/`` on macOS), so the data directory
+never depends on the current directory: it comes from the environment, else
+the platform's per-user data directory.
+
+The project was called gamemaster-mcp before its rename: its ``GAMEMASTER_*``
+variables and its data directory still work.
+"""
+
+import logging
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_data_path
+
+APP_NAME = "dndkit"
+LEGACY_NAME = "gamemaster-mcp"
+ENV_PREFIX, LEGACY_ENV_PREFIX = "DNDKIT_", "GAMEMASTER_"
+ENV_DATA_DIR = "DNDKIT_STORAGE_DIR"
+ENV_LOG_LEVEL = "DNDKIT_LOG_LEVEL"
+ENV_WEB_PORT = "DNDKIT_WEB_PORT"
+ENV_WEB_HOST = "DNDKIT_WEB_HOST"
+ENV_WEB_URL = "DNDKIT_WEB_URL"
+DEFAULT_WEB_HOST = "127.0.0.1"
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class WebSettings:
+    """Where the web pages listen. Port 0 picks a free one (tests)."""
+
+    port: int
+    host: str = DEFAULT_WEB_HOST
+    public_url: str | None = None  # how phones reach the pages when the server cannot tell
+
+
+def setting(env: Mapping[str, str], name: str) -> str:
+    """``$name``, else the same variable under its name from before the rename."""
+    value = env.get(name, "").strip()
+    if not value and name.startswith(ENV_PREFIX):
+        value = env.get(LEGACY_ENV_PREFIX + name.removeprefix(ENV_PREFIX), "").strip()
+    return value
+
+
+def resolve_data_dir(env: Mapping[str, str] = os.environ) -> Path:
+    """The data directory: ``$DNDKIT_STORAGE_DIR``, else the per-user data dir.
+
+    A relative path would depend on the client's working directory: it is
+    refused, and the per-user data dir used instead.
+    """
+    configured = setting(env, ENV_DATA_DIR)
+    if configured:
+        path = Path(configured).expanduser()
+        if path.is_absolute():
+            return path.resolve()
+        logger.warning("Ignoring %s=%r: give an absolute path.", ENV_DATA_DIR, configured)
+    return per_user_data_dir(
+        user_data_path(APP_NAME, appauthor=False), user_data_path(LEGACY_NAME, appauthor=False)
+    )
+
+
+def per_user_data_dir(current: Path, legacy: Path) -> Path:
+    """*current*, unless only the data directory from before the rename exists."""
+    if not current.exists() and legacy.is_dir():
+        return legacy
+    return current
+
+
+def configure_logging(env: Mapping[str, str] = os.environ) -> None:
+    """Log to stderr: on the stdio transport, stdout carries the MCP protocol."""
+    name = (setting(env, ENV_LOG_LEVEL) or "INFO").upper()
+    # A misspelt level falls back to INFO: a typo must not stop the server.
+    level = logging.getLevelNamesMapping().get(name, logging.INFO)
+    logging.basicConfig(
+        level=level,
+        stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+
+def resolve_web_settings(env: Mapping[str, str] = os.environ) -> WebSettings | None:
+    """The web pages' settings; None (no web pages) unless ``$DNDKIT_WEB_PORT`` is set."""
+    raw_port = setting(env, ENV_WEB_PORT)
+    if not raw_port:
+        return None
+    if not (raw_port.isascii() and raw_port.isdigit()) or int(raw_port) > 65535:
+        # The game must still run: only the web pages are lost to a typo.
+        logger.warning("Web pages are off: %s=%r is not a port number.", ENV_WEB_PORT, raw_port)
+        return None
+    public_url = setting(env, ENV_WEB_URL).rstrip("/") or None
+    if public_url and not public_url.startswith(("http://", "https://")):
+        logger.warning("Ignoring %s=%r: not an http(s) address.", ENV_WEB_URL, public_url)
+        public_url = None
+    return WebSettings(
+        port=int(raw_port),
+        host=setting(env, ENV_WEB_HOST) or DEFAULT_WEB_HOST,
+        public_url=public_url,
+    )

dndkit/errors.py

@@ -0,0 +1,48 @@
+"""Errors the game raises when a request cannot be carried out.
+
+They subclass FastMCP's ``ToolError`` on purpose: FastMCP sends a ``ToolError``
+message to the client verbatim as an ``is_error`` result, while any other
+exception is masked. The model therefore reads "No character named 'Arya'.
+Known characters: Aria." and can correct itself, instead of a bare failure.
+"""
+
+import logging
+
+from fastmcp.exceptions import ToolError
+
+
+class GameError(ToolError):
+    """A request the game cannot carry out; the message is written for the model."""
+
+    def __init__(self, message: str) -> None:
+        # An expected game outcome, not a server fault: keep it out of error logs.
+        super().__init__(message, log_level=logging.INFO)
+
+
+class NotFoundError(GameError):
+    """No entity answers to the given name or ID."""
+
+
+class AlreadyExistsError(GameError):
+    """The name is already taken by another entity of the same kind."""
+
+
+class InvalidChangeError(GameError):
+    """The change would leave the game in an invalid state."""
+
+
+class DiceError(GameError):
+    """The dice notation cannot be parsed or is out of bounds."""
+
+
+NO_ACTIVE_CAMPAIGN = (
+    "No campaign is active. Create one with create_campaign "
+    "or open one with load_campaign (list_campaigns shows them)."
+)
+
+
+class NoActiveCampaignError(GameError):
+    """Every game tool needs an active campaign."""
+
+    def __init__(self, message: str = NO_ACTIVE_CAMPAIGN) -> None:
+        super().__init__(message)

dndkit/game/__init__.py

@@ -0,0 +1 @@
+"""Game logic over a Campaign object: no MCP, no disk, testable on its own."""

dndkit/game/areas.py

@@ -0,0 +1,181 @@
+"""Areas of effect on the battle map (PHB ch. 10, DMG ch. 8 "Areas of Effect").
+
+A sphere (a cylinder, seen from above) of radius R holds every square within
+R feet of its centre square, measured as movement is. A cube of side S is
+S/5 squares a side: centred on a square or a creature, or against its
+caster's side facing the target. Cones and lines start at the edge of their
+caster's space; a square is in when at least half of it is (DMG), and a cone
+is as wide as it is far. Walls stop an area: a square is out when the line
+from the area's origin to its centre crosses a wall. A creature is caught
+when any square it holds is in.
+"""
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import battlefield, combat, grid, sight
+from dndkit.game.grid import Square
+from dndkit.game.sight import Point
+from dndkit.models import Combatant, GameState
+
+Shape = Literal["sphere", "cube", "cone", "line"]
+SAMPLES = 4  # per side of a square, to measure how much of it an area covers
+_SQUARE = re.compile(r"\s*[A-Za-z]\s*\d{1,2}\s*")
+
+
+@dataclass(frozen=True)
+class Spot:
+    """Where an area is anchored: some squares, and the creature on them if any."""
+
+    squares: list[Square]
+    creature: Combatant | None
+
+
+@dataclass(frozen=True)
+class Area:
+    """What an area of effect covers and who it catches."""
+
+    label: str
+    squares: list[Square]
+    caught: list[Combatant]
+
+
+@dataclass(frozen=True)
+class Aim:
+    """How an area is aimed, as a tool call describes it."""
+
+    shape: Shape
+    feet: int  # radius (sphere), side (cube), length (cone, line)
+    at: str | None = None  # centre: a square or a creature
+    source: str | None = None  # the caster, for a cone, a line or a cube against them
+    toward: str | None = None  # where a cone, line or cube points
+    width: int = grid.FEET  # a line's width
+
+
+def resolve(state: GameState, aim: Aim) -> Area:
+    """The area *aim* covers, drawn on the map until the next turn."""
+    field = battlefield.require(state)
+    walls = battlefield.wall_squares(field)
+    if aim.shape in ("cone", "line") or (aim.shape == "cube" and aim.source):
+        source, toward = _need(state, aim.source, "source"), _need(state, aim.toward, "toward")
+        origin, squares = _from_caster(state, aim, source, toward)
+        exclude = source
+    else:
+        centre = _need(state, aim.at, "at")
+        origin = sight.centre(centre.squares)
+        squares = (
+            _sphere(state, centre, aim.feet) if aim.shape == "sphere" else _cube(centre, aim.feet)
+        )
+        exclude = Spot([], None)
+    inside = [
+        s
+        for s in squares
+        if grid.inside(s, field)
+        and s not in walls
+        and s not in exclude.squares
+        and not sight.blocked(origin, sight.centre([s]), walls)
+    ]
+    held = set(inside)
+    caught = [
+        c
+        for c, squares_held in _everyone(state)
+        if c is not exclude.creature and held & set(squares_held)
+    ]
+    label = f"{aim.feet}-ft {aim.shape}"
+    field.area, field.area_label = [grid.name(s) for s in inside], label
+    return Area(label, inside, caught)
+
+
+def _sphere(state: GameState, centre: Spot, feet: int) -> list[Square]:
+    field = battlefield.require(state)
+    every = [(x, y) for y in range(field.height) for x in range(field.width)]
+    return [s for s in every if grid.feet_between([s], centre.squares) <= feet]
+
+
+def _cube(centre: Spot, feet: int) -> list[Square]:
+    side = max(1, feet // grid.FEET)
+    xs = [x for x, _ in centre.squares]
+    ys = [y for _, y in centre.squares]
+    return [
+        (x, y) for y in _span(min(ys), max(ys), 0, side) for x in _span(min(xs), max(xs), 0, side)
+    ]
+
+
+def _from_caster(
+    state: GameState, aim: Aim, source: Spot, toward: Spot
+) -> tuple[Point, list[Square]]:
+    start, end = sight.centre(source.squares), sight.centre(toward.squares)
+    dx, dy = end[0] - start[0], end[1] - start[1]
+    if not (dx or dy):
+        raise InvalidChangeError("The area points nowhere: aim it at another square.")
+    if aim.shape == "cube":
+        return start, _cube_against(source, dx, dy, aim.feet)
+    length = math.hypot(dx, dy)
+    ux, uy = dx / length, dy / length
+    # The origin is where the line from the caster's centre leaves its space.
+    half = (max(x for x, _ in source.squares) - min(x for x, _ in source.squares) + 1) * 2.5
+    edge = half / max(abs(ux), abs(uy))
+    origin = (start[0] + ux * edge, start[1] + uy * edge)
+    field = battlefield.require(state)
+    every = [(x, y) for y in range(field.height) for x in range(field.width)]
+    covered = [s for s in every if _share(s, origin, (ux, uy), aim) >= 0.5]
+    return origin, covered
+
+
+def _cube_against(source: Spot, dx: float, dy: float, feet: int) -> list[Square]:
+    side = max(1, feet // grid.FEET)
+    xs = [x for x, _ in source.squares]
+    ys = [y for _, y in source.squares]
+    return [
+        (x, y)
+        for y in _span(min(ys), max(ys), dy, side)
+        for x in _span(min(xs), max(xs), dx, side)
+    ]
+
+
+def _span(low: int, high: int, step: float, side: int) -> range:
+    """*side* rows or columns: past *high* (step > 0), before *low* (< 0), or centred."""
+    if step > 0:
+        return range(high + 1, high + 1 + side)
+    if step < 0:
+        return range(low - side, low)
+    first = low + (high - low + 1 - side) // 2
+    return range(first, first + side)
+
+
+def _share(square: Square, origin: Point, direction: Point, aim: Aim) -> float:
+    """How much of *square* the cone or line covers, from 0 to 1."""
+    inside = 0
+    for i in range(SAMPLES):
+        for j in range(SAMPLES):
+            px = (square[0] + (i + 0.5) / SAMPLES) * grid.FEET - origin[0]
+            py = (square[1] + (j + 0.5) / SAMPLES) * grid.FEET - origin[1]
+            along = px * direction[0] + py * direction[1]
+            across = abs(px * direction[1] - py * direction[0])
+            limit = along / 2 if aim.shape == "cone" else aim.width / 2
+            inside += 0 < along <= aim.feet and across <= limit
+    return inside / SAMPLES**2
+
+
+def _need(state: GameState, text: str | None, role: str) -> Spot:
+    if not text:
+        raise InvalidChangeError(f"This area needs {role}: a square like E5, or a creature.")
+    if _SQUARE.fullmatch(text):
+        return Spot([grid.parse(text, battlefield.require(state))], None)
+    creature = combat.find(state, text)
+    held = battlefield.footprint_of(state, creature)
+    if held is None:
+        raise InvalidChangeError(f"{creature.name} is not on the map.")
+    return Spot(held, creature)
+
+
+def _everyone(state: GameState) -> list[tuple[Combatant, list[Square]]]:
+    placed = []
+    for combatant in state.initiative_order:
+        held = battlefield.footprint_of(state, combatant)
+        if held is not None:
+            placed.append((combatant, held))
+    return placed

dndkit/game/battlefield.py

@@ -0,0 +1,154 @@
+"""The battle map of the running fight: its terrain, and who stands where.
+
+Combatants keep their own square (``Combatant.position``, the top-left one
+for a creature bigger than a square). Whoever has none when the map is laid
+out or the fight starts is placed at an edge: the party on the left, its
+foes on the right.
+"""
+
+from collections.abc import Iterable, Sequence
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import grid
+from dndkit.game.grid import Square
+from dndkit.models import Battlefield, Combatant, GameState
+
+
+def require(state: GameState) -> Battlefield:
+    """The map, or an error saying how to lay one out."""
+    if state.battlefield is None:
+        raise InvalidChangeError(
+            "There is no battle map: lay one out with set_battlefield, "
+            "or keep describing positions in words."
+        )
+    return state.battlefield
+
+
+def build(width: int, height: int, walls: Iterable[str], difficult: Iterable[str]) -> Battlefield:
+    """A map with its terrain squares checked and listed one by one."""
+    field = Battlefield(width=width, height=height)
+    blocked = _names(field, walls)
+    field.walls = blocked
+    field.difficult = [s for s in _names(field, difficult) if s not in blocked]
+    return field
+
+
+def lay_out(
+    state: GameState, width: int, height: int, walls: Iterable[str], difficult: Iterable[str]
+) -> list[Combatant]:
+    """Replace the map; returns those who lost their square (off the map, in a wall)."""
+    state.battlefield = build(width, height, walls, difficult)
+    return settle(state)
+
+
+def settle(state: GameState) -> list[Combatant]:
+    """Take off the map whoever stands off it, in a wall or on someone placed before."""
+    field = require(state)
+    walls = wall_squares(field)
+    taken: set[Square] = set()
+    displaced = []
+    for combatant in state.initiative_order:
+        if combatant.position is None:
+            continue
+        try:
+            held = set(footprint_of(state, combatant) or [])
+        except InvalidChangeError:  # off the map
+            held = set()
+        if not held or held & (walls | taken) or any(not grid.inside(s, field) for s in held):
+            combatant.position = None
+            displaced.append(combatant)
+            continue
+        combatant.position = grid.name(min(held, key=lambda s: (s[1], s[0])))  # "d 7" -> "D7"
+        taken |= held
+    return displaced
+
+
+def is_party(combatant: Combatant) -> bool:
+    """Whether *combatant* fights on the party's side."""
+    return combatant.character_id is not None or combatant.ally
+
+
+def square_of(state: GameState, combatant: Combatant) -> Square | None:
+    """The top-left square *combatant* stands on, if it has one on the map."""
+    if combatant.position is None or state.battlefield is None:
+        return None
+    return grid.parse(combatant.position, state.battlefield)
+
+
+def footprint_of(state: GameState, combatant: Combatant) -> list[Square] | None:
+    """The squares *combatant* holds, if it is on the map."""
+    top_left = square_of(state, combatant)
+    return None if top_left is None else grid.footprint(top_left, combatant.size)
+
+
+def free(state: GameState, mover: Combatant, top_left: Square) -> bool:
+    """Whether *mover* can stand at *top_left*: on the map, off walls, alone."""
+    field = require(state)
+    squares = grid.footprint(top_left, mover.size)
+    walls = wall_squares(field)
+    if any(not grid.inside(s, field) or s in walls for s in squares):
+        return False
+    return not any(set(squares) & set(held) for _, held in others(state, mover))
+
+
+def others(state: GameState, mover: Combatant) -> list[tuple[Combatant, list[Square]]]:
+    """Every other combatant on the map, with the squares it holds."""
+    placed = []
+    for combatant in state.initiative_order:
+        held = None if combatant is mover else footprint_of(state, combatant)
+        if held is not None:
+            placed.append((combatant, held))
+    return placed
+
+
+def place(state: GameState, combatant: Combatant, square: str) -> None:
+    """Put *combatant* on *square* (its top-left one), which must be free."""
+    top_left = grid.parse(square, require(state))
+    if not free(state, combatant, top_left):
+        raise InvalidChangeError(
+            f"{combatant.name} cannot stand on {grid.name(top_left)}: "
+            "a wall, the map's edge or someone else is in the way."
+        )
+    combatant.position = grid.name(top_left)
+
+
+def place_the_rest(state: GameState) -> list[Combatant]:
+    """Place everyone still off the map at their side's edge; returns who was placed."""
+    if state.battlefield is None:
+        return []
+    placed = []
+    for combatant in state.initiative_order:
+        if combatant.position is None and _place_at_edge(state, combatant):
+            placed.append(combatant)
+    return placed
+
+
+def wall_squares(field: Battlefield) -> set[Square]:
+    """The blocked squares."""
+    return {grid.parse(s, field) for s in field.walls}
+
+
+def difficult_squares(field: Battlefield) -> set[Square]:
+    """The squares of difficult terrain."""
+    return {grid.parse(s, field) for s in field.difficult}
+
+
+def _place_at_edge(state: GameState, combatant: Combatant) -> bool:
+    field = require(state)
+    side = grid.SIZE_SQUARES[combatant.size]
+    columns: Sequence[int] = range(field.width - side + 1)
+    if not is_party(combatant):
+        columns = list(reversed(columns))
+    middle = (field.height - side) / 2
+    rows = sorted(range(field.height - side + 1), key=lambda row: abs(row - middle))
+    for column in columns:
+        for row in rows:
+            if free(state, combatant, (column, row)):
+                combatant.position = grid.name((column, row))
+                return True
+    return False
+
+
+def _names(field: Battlefield, areas: Iterable[str]) -> list[str]:
+    squares = {square for text in areas for square in grid.area(text, field)}
+    return [grid.name(s) for s in sorted(squares, key=lambda s: (s[1], s[0]))]