rpgsync 0.1.0__py3-none-any.whl

rpgsync/dsl.py

@@ -0,0 +1,2616 @@
+"""The event script language of rpgsync: typed and documented vocabulary.
+
+Every script starts with ``from rpgsync.dsl import *``.  rpgsync *parses*
+scripts and never runs them, so nothing here does anything at runtime: the
+classes and signatures exist so that editors autocomplete, show these docs
+on hover, and type checkers (ty, pyright) flag wrong values while you type.
+
+Example::
+
+    @event(9, "Guard", x=10, y=5)
+    class Guard(Event):
+        sprite = ("Actor1", 3)
+        layer = "same"
+
+        def page_1(self):
+            \"\"\"Asks for the toll (stored in the game as the page's first comment)\"\"\"
+            text("Halt!")
+            if variables[1] >= variables[2]:
+                party.gold -= 100
+            match show_choices("Pay", "Leave"):
+                case "Pay":
+                    switches[4] = True
+                case "Leave":
+                    this.move(move_away_from_player, frequency=6)
+                    return
+
+        @page(when=switches[4])
+        def page_2(self):
+            text("Welcome back.")
+
+Conventions:
+
+* Ranges use Python slices: ``variables[1:11]`` is variables 1 to 10.
+* Most numbers can also be given as ``variables[id]`` (the value is read
+  when the command runs).
+* ``extra=(...)`` keeps raw parameters added by newer editor versions or
+  patches; ``some_field=None`` marks a parameter that older editors did not
+  write.  Both are generated by rpgsync to keep data byte-identical; you
+  rarely need them yourself.
+* Python ``#`` comments on their own line are stored as RPG Maker comments.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import AbstractContextManager, nullcontext
+from typing import TYPE_CHECKING, Literal, Never, Protocol, TypeVar, overload
+
+_F = TypeVar("_F", bound=Callable[..., object])
+_E = TypeVar("_E", bound="Event")
+
+# ==========================================================================
+# Accepted values
+# ==========================================================================
+
+Direction = Literal["up", "right", "down", "left"]
+"""A facing direction."""
+TeleportDirection = Literal["retain", "up", "right", "down", "left"]
+"""Facing after a teleport / move: ``"retain"`` keeps the current one."""
+Trigger = Literal["action", "touch", "collision", "autorun", "parallel"]
+"""How an event page starts:
+
+* ``"action"``: the player presses the action key next to it (or on it).
+* ``"touch"``: the player walks into it.
+* ``"collision"``: the player walks into it, or it walks into the player.
+* ``"autorun"``: starts by itself and blocks the player until it ends.
+* ``"parallel"``: runs repeatedly in the background while the player moves.
+"""
+Layer = Literal["below", "same", "above"]
+"""Drawing/collision layer of an event: below the hero (walkable), same as
+the hero (blocks, can be talked to) or above the hero."""
+MoveType = Literal["stationary", "random", "vertical", "horizontal", "toward_player", "away_from_player", "custom"]
+"""Automatic movement of an event page (``"custom"`` uses ``route=``)."""
+Pattern = Literal["left", "middle", "right", "middle2"]
+"""Animation frame of the sprite shown when the event stands still."""
+AnimationType = Literal[
+    "non_continuous",
+    "continuous",
+    "fixed_non_continuous",
+    "fixed_continuous",
+    "fixed_graphic",
+    "spin",
+    "step_frame_fix",
+]
+"""How the sprite animates: walking only when moving (non_continuous),
+always (continuous), with a fixed direction, frozen (fixed_graphic) or
+spinning."""
+Speed = Literal[1, 2, 3, 4, 5, 6]
+"""Movement speed: 1 = 1/8, 2 = 1/4, 3 = 1/2, 4 = normal, 5 = x2, 6 = x4."""
+Frequency = Literal[1, 2, 3, 4, 5, 6, 7, 8]
+"""How often an event acts: 1 = rarely ... 8 = continuously.  It affects
+moving, turning and waiting, not graphic changes."""
+SpriteIndex = Literal[0, 1, 2, 3, 4, 5, 6, 7] | int  # int: a value the editor cannot set
+"""Which of the 8 characters of a CharSet image (288x256), counted left to
+right, top to bottom, from 0 at the top left::
+
+    +---+---+---+---+
+    | 0 | 1 | 2 | 3 |
+    +---+---+---+---+
+    | 4 | 5 | 6 | 7 |
+    +---+---+---+---+
+
+Each character block holds 3 walking frames across and 4 directions down
+(up, right, down, left); the page's ``direction`` and ``pattern`` pick the
+pose inside it."""
+FaceIndex = Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
+"""Which of the 16 faces (48x48) of a FaceSet image, counted left to right,
+top to bottom: 0-3 on the first row ... 12-15 on the last."""
+CommonEventTrigger = Literal["call", "autorun", "parallel"]
+"""When a common event runs: only when called, automatically (blocking), or
+in parallel; autorun/parallel common events need their condition switch ON."""
+MessagePosition = Literal["top", "middle", "bottom"]
+Vehicle = Literal["boat", "ship", "airship"]
+CancelOption = Literal[1, 2, 3, 4]
+Digits = Literal[1, 2, 3, 4, 5, 6, 7, 8, 9] | int  # 8-9: Maniac Patch; int: a value the editor cannot set
+Transition = (
+    Literal[
+        "default",
+        "fade",
+        "random_blocks",
+        "random_blocks_down",
+        "random_blocks_up",
+        "blinds",
+        "vertical_stripes",
+        "horizontal_stripes",
+        "border_to_center",
+        "center_to_border",
+        "scroll_up",
+        "scroll_down",
+        "scroll_left",
+        "scroll_right",
+        "vertical_split",
+        "horizontal_split",
+        "cross_split",
+        "zoom",
+        "mosaic",
+        "ripple",
+        "instant",
+        "none",
+    ]
+    | int
+)  # int: a value the editor cannot set
+"""Screen transition; ``"default"`` uses the one set in the database
+(System tab) or with set_transition()."""
+TransitionKind = (
+    Literal[
+        "teleport_erase",
+        "teleport_show",
+        "battle_start_erase",
+        "battle_start_show",
+        "battle_end_erase",
+        "battle_end_show",
+    ]
+    | int
+)  # int: a value the editor cannot set
+WeatherKind = Literal["none", "rain", "snow", "fog", "sandstorm"]
+Strength = Literal["weak", "medium", "strong"]
+FlashMode = Literal["once", "begin", "end"]
+"""``"once"`` flashes/shakes once; ``"begin"`` repeats until ``"end"`` (2003)."""
+PictureEffect = Literal["none", "rotation", "wave"] | int  # int: a value the editor cannot set
+Stat = Literal["max_hp", "max_sp", "attack", "defense", "spirit", "agility"]
+EquipSlot = Literal["weapon", "shield", "armor", "helmet", "accessory", "all"]
+BgmContext = (
+    Literal["battle", "victory", "inn", "boat", "ship", "airship", "game_over"] | int
+)  # int: a value the editor cannot set
+SeContext = (
+    Literal[
+        "cursor",
+        "decision",
+        "cancel",
+        "buzzer",
+        "battle_start",
+        "escape",
+        "enemy_attack",
+        "enemy_damaged",
+        "ally_damaged",
+        "evade",
+        "enemy_dies",
+        "item",
+    ]
+    | int
+)  # int: a value the editor cannot set
+SkillMode = Literal["keep", "replace", "add"]
+StatMode = Literal["keep", "halve", "level1", "current_level"]
+
+# Command names accepted by cmd(...), from liblcf.
+CommandName = Literal[
+    "BreakLoop",
+    "CallCommonEvent",
+    "CallEvent",
+    "ChangeActorFace",
+    "ChangeBattleBG",
+    "ChangeBattleCommands",
+    "ChangeClass",
+    "ChangeCondition",
+    "ChangeEncounterSteps",
+    "ChangeEquipment",
+    "ChangeEscapeAccess",
+    "ChangeEventLocation",
+    "ChangeExp",
+    "ChangeFaceGraphic",
+    "ChangeGold",
+    "ChangeHP",
+    "ChangeHeroName",
+    "ChangeHeroTitle",
+    "ChangeItems",
+    "ChangeLevel",
+    "ChangeMainMenuAccess",
+    "ChangeMapTileset",
+    "ChangeMonsterCondition",
+    "ChangeMonsterHP",
+    "ChangeMonsterMP",
+    "ChangePBG",
+    "ChangeParameters",
+    "ChangePartyMembers",
+    "ChangeSP",
+    "ChangeSaveAccess",
+    "ChangeScreenTransitions",
+    "ChangeSkills",
+    "ChangeSpriteAssociation",
+    "ChangeSystemBGM",
+    "ChangeSystemGraphics",
+    "ChangeSystemSFX",
+    "ChangeTeleportAccess",
+    "ChangeVehicleGraphic",
+    "Comment",
+    "Comment_2",
+    "ConditionalBranch",
+    "ConditionalBranch_B",
+    "ControlSwitches",
+    "ControlVars",
+    "DefeatHandler",
+    "END",
+    "ElseBranch",
+    "ElseBranch_B",
+    "EnableCombo",
+    "EndBattle",
+    "EndBranch",
+    "EndBranch_B",
+    "EndEventProcessing",
+    "EndInn",
+    "EndLoop",
+    "EndShop",
+    "EnemyEncounter",
+    "EnterExitVehicle",
+    "EnterHeroName",
+    "EraseEvent",
+    "ErasePicture",
+    "EraseScreen",
+    "EscapeHandler",
+    "EscapeTarget",
+    "ExitGame",
+    "FadeOutBGM",
+    "FlashScreen",
+    "FlashSprite",
+    "ForceFlee",
+    "FullHeal",
+    "GameOver",
+    "HaltAllMovement",
+    "InputNumber",
+    "JumpToLabel",
+    "KeyInputProc",
+    "Label",
+    "Loop",
+    "MemorizeBGM",
+    "MemorizeLocation",
+    "MessageOptions",
+    "MoveEvent",
+    "MovePicture",
+    "NoStay",
+    "NoTransaction",
+    "OpenLoadMenu",
+    "OpenMainMenu",
+    "OpenSaveMenu",
+    "OpenShop",
+    "OpenVideoOptions",
+    "PanScreen",
+    "PlayBGM",
+    "PlayMemorizedBGM",
+    "PlayMovie",
+    "PlaySound",
+    "PlayerVisibility",
+    "ProceedWithMovement",
+    "RecallToLocation",
+    "ReturntoTitleScreen",
+    "SetVehicleLocation",
+    "ShakeScreen",
+    "ShowBattleAnimation",
+    "ShowBattleAnimation_B",
+    "ShowChoice",
+    "ShowChoiceEnd",
+    "ShowChoiceOption",
+    "ShowHiddenMonster",
+    "ShowInn",
+    "ShowMessage",
+    "ShowMessage_2",
+    "ShowPicture",
+    "ShowScreen",
+    "SimulatedAttack",
+    "Stay",
+    "StoreEventID",
+    "StoreTerrainID",
+    "TeleportTargets",
+    "Teleport",
+    "TerminateBattle",
+    "TileSubstitution",
+    "TimerOperation",
+    "ToggleAtbMode",
+    "ToggleFullscreen",
+    "TradeEventLocations",
+    "Transaction",
+    "VictoryHandler",
+    "Wait",
+    "WeatherEffects",
+]
+
+Extra = tuple[int, ...]
+"""Raw trailing parameters kept for lossless round trips (newer editors, patches)."""
+
+
+# ==========================================================================
+# Values and conditions
+# ==========================================================================
+
+
+class Condition:
+    """Something an ``if`` or ``@page(when=...)`` can test."""
+
+    def __bool__(self) -> bool: ...
+
+
+class Value:
+    """A number read from the game when the command runs (a variable, a
+    stat, the gold...).  Compare it to get a condition:
+    ``variables[1] >= 10``, ``variables[1] == variables[2]``."""
+
+    def __eq__(self, other: object) -> Condition: ...  # type: ignore[override]
+    def __ne__(self, other: object) -> Condition: ...  # type: ignore[override]
+    def __lt__(self, other: int | Value) -> Condition: ...
+    def __le__(self, other: int | Value) -> Condition: ...
+    def __gt__(self, other: int | Value) -> Condition: ...
+    def __ge__(self, other: int | Value) -> Condition: ...
+    def __neg__(self) -> Value: ...
+    def __pos__(self) -> Value: ...
+
+
+Number = int | Value
+"""A number, or a value read from the game such as ``variables[3]``."""
+
+if TYPE_CHECKING:
+    # written by rpgsync into each game's Scripts/database: Variable when the game
+    # runs the DynParams plugin, else Never
+    from database.game_types import Dynamic  # type: ignore
+else:
+    Dynamic = Never
+
+Fixed = int | Dynamic
+"""A number that RPG Maker keeps as such in the command.  In a game that runs the
+DynParams plugin (DynPlugins/DynParams.dll), also a variable such as
+``variables.id``: its value is used when the command runs."""
+
+
+class Counter(Value):
+    """A value changed with ``+=`` / ``-=`` (gold, item counts)."""
+
+    def __iadd__(self, amount: Number) -> Counter: ...
+    def __isub__(self, amount: Number) -> Counter: ...
+
+
+class Variable(Value):
+    """One game variable, ``variables[id]``.
+
+    Assign with ``=``, change with ``+= -= *= //= %=`` (``%`` is the
+    remainder: 1953 % 100 = 53).  Values range from -9999999 to 9999999 in
+    RPG Maker 2003 (-999999 to 999999 in 2000)."""
+
+    def __iadd__(self, value: Number) -> Variable: ...
+    def __isub__(self, value: Number) -> Variable: ...
+    def __imul__(self, value: Number) -> Variable: ...
+    def __ifloordiv__(self, value: Number) -> Variable: ...
+    def __imod__(self, value: Number) -> Variable: ...
+
+
+class VariableRange:
+    """``variables[first:last+1]``: the same operation on every variable of the range."""
+
+    def __iadd__(self, value: Number) -> VariableRange: ...
+    def __isub__(self, value: Number) -> VariableRange: ...
+    def __imul__(self, value: Number) -> VariableRange: ...
+    def __ifloordiv__(self, value: Number) -> VariableRange: ...
+    def __imod__(self, value: Number) -> VariableRange: ...
+
+
+class Variables:
+    """All game variables: ``variables[5]``, ``variables[1:11]`` (1 to 10),
+    ``variables[variables[3]]`` (the variable whose id is stored in variable 3).
+
+    Pointers (arrays, tables)::
+
+        variables.ptr = variables.slot
+        variables.ptr += 2001                    # the array starts at 2001
+        variables.hp = variables[variables.ptr]  # read
+        variables[variables.ptr] += 10           # write
+
+    A branch can't test ``variables[variables.ptr]`` directly: copy it into a
+    variable first.  There is no maths inside ``[]``: move the pointer instead."""
+
+    @overload
+    def __getitem__(self, key: int | Variable) -> Variable: ...
+    @overload
+    def __getitem__(self, key: slice) -> VariableRange: ...
+    def __getitem__(self, key): ...
+    def __setitem__(self, key: int | Variable | slice, value: Number | VariableRange | Variable) -> None: ...
+
+
+class Switch(Condition):
+    """One game switch, ``switches[id]`` (ON/OFF).  Set it with ``= True`` /
+    ``= False``, test it with ``if switches[id]:`` or ``if not switches[id]:``."""
+
+    def toggle(self) -> None:
+        """Flip the switch: ON becomes OFF and OFF becomes ON."""
+
+
+class SwitchRange:
+    """``switches[first:last+1]``: several switches at once."""
+
+    def toggle(self) -> None:
+        """Flip every switch of the range."""
+
+
+class Switches:
+    """All game switches: ``switches[5]``, ``switches[1:11]`` (1 to 10),
+    ``switches[variables[3]]`` (the switch whose id is in variable 3: it can
+    be set, but RPG Maker can't test it)."""
+
+    @overload
+    def __getitem__(self, key: int | Variable) -> Switch: ...
+    @overload
+    def __getitem__(self, key: slice) -> SwitchRange: ...
+    def __getitem__(self, key): ...
+    def __setitem__(self, key: int | Variable | slice, value: bool) -> None: ...
+
+
+class Item:
+    """``items[id]``: an item of the database.  ``items[3].count += 2`` gives
+    two, ``if items[3] in party:`` tests possession.  The inventory is sorted
+    by item id."""
+
+    count: Counter
+    """How many the party holds."""
+    equipped: Value
+    """How many are currently equipped by party members."""
+
+
+class Items:
+    def __getitem__(self, key: int | Variable) -> Item: ...
+
+
+class Actor:
+    """``actors[id]``: a hero of the database (in the party or not)."""
+
+    name: str
+    """The hero's name; assign to rename (``actors[1].name = "Alex"``).
+    Message codes work in it, but not \\v[] (variable display)."""
+    title: str
+    """The hero's title (grade); assign to change it."""
+    level: Value
+    exp: Value
+    hp: Value
+    sp: Value
+    max_hp: Value
+    max_sp: Value
+    attack: Value
+    defense: Value
+    spirit: Value
+    agility: Value
+    weapon: Value
+    """Id of the equipped weapon (0 = none)."""
+    shield: Value
+    armor: Value
+    helmet: Value
+    accessory: Value
+    can_act: Condition
+    """In ``battle_condition(...)``: the hero can act this turn."""
+
+    def knows(self, skill: Fixed) -> Condition:
+        """Condition: the hero has learned this skill."""
+
+    def has_equipped(self, item: Fixed) -> Condition:
+        """Condition: the hero has this item equipped."""
+
+    def has_state(self, state: Fixed) -> Condition:
+        """Condition: the hero has this state (poison, sleep...)."""
+
+    def uses_command(self, command: Fixed) -> Condition:
+        """In ``battle_condition(...)`` and troop page conditions: the hero uses this
+        battle command (2003)."""
+
+    def hp_percent(self, min: int = 0, max: int = 100) -> Condition:
+        """Troop page condition: the hero's HP is between min% and max% of its max HP."""
+
+    def turn(self, start: int, every: int = 0) -> Condition:
+        """Troop page condition (2003): the hero's own turn count is ``start``, then
+        every ``every`` turns (``every=0``: that turn only)."""
+
+    def set_sprite(
+        self, charset: str, index: Fixed | None = None, transparent: bool | None = None, *, extra: Extra = ()
+    ) -> None:
+        """Change the hero's walking sprite.
+
+        Args:
+            charset: CharSet image name.
+            index: character in the CharSet image (0-7).
+            transparent: draw the hero semi-transparent.
+        """
+
+    def set_face(self, faceset: str, index: Fixed | None = None, *, extra: Extra = ()) -> None:
+        """Change the hero's face (used by messages and menus).
+
+        Args:
+            faceset: FaceSet image name.
+            index: face in the FaceSet image (0-15).
+        """
+
+
+class Actors:
+    def __getitem__(self, key: int | Variable) -> Actor: ...
+
+
+class MoveStep:
+    """One step of a move route (move_up, face_player, switch_on(3), ...).
+    ``move_up * 3`` repeats a step."""
+
+    def __mul__(self, count: int) -> MoveStep: ...
+
+
+# ==========================================================================
+# Move route steps
+# ==========================================================================
+
+move_up = MoveStep()
+"""Move one tile up."""
+move_right = MoveStep()
+"""Move one tile right."""
+move_down = MoveStep()
+"""Move one tile down."""
+move_left = MoveStep()
+"""Move one tile left."""
+move_up_right = MoveStep()
+"""Move one tile diagonally up-right."""
+move_down_right = MoveStep()
+"""Move one tile diagonally down-right."""
+move_down_left = MoveStep()
+"""Move one tile diagonally down-left."""
+move_up_left = MoveStep()
+"""Move one tile diagonally up-left."""
+move_random = MoveStep()
+"""Move one tile in a random direction."""
+move_toward_player = MoveStep()
+"""Move one tile toward the player."""
+move_away_from_player = MoveStep()
+"""Move one tile away from the player."""
+move_forward = MoveStep()
+"""Move one tile in the facing direction."""
+face_up = MoveStep()
+"""Turn to face up."""
+face_right = MoveStep()
+"""Turn to face right."""
+face_down = MoveStep()
+"""Turn to face down."""
+face_left = MoveStep()
+"""Turn to face left."""
+turn_right = MoveStep()
+"""Turn 90 degrees clockwise."""
+turn_left = MoveStep()
+"""Turn 90 degrees counterclockwise."""
+turn_around = MoveStep()
+"""Turn 180 degrees."""
+turn_random = MoveStep()
+"""Turn 90 degrees left or right at random."""
+face_random = MoveStep()
+"""Face a random direction."""
+face_player = MoveStep()
+"""Face the player."""
+face_away_from_player = MoveStep()
+"""Turn the back to the player."""
+pause = MoveStep()
+"""Wait one movement step."""
+jump_start = MoveStep()
+"""Start a jump: the following movement steps set where it lands."""
+jump_end = MoveStep()
+"""End a jump started with jump_start: land where the steps in between lead."""
+lock_facing = MoveStep()
+"""Keep the current facing direction while moving."""
+unlock_facing = MoveStep()
+"""Face the direction of movement again."""
+speed_up = MoveStep()
+"""Move one speed faster (speeds go from 1 to 6)."""
+speed_down = MoveStep()
+"""Move one speed slower."""
+frequency_up = MoveStep()
+"""Act more often (frequency goes from 1 to 8)."""
+frequency_down = MoveStep()
+"""Act less often."""
+phasing_on = MoveStep()
+"""Walk through everything."""
+phasing_off = MoveStep()
+"""Stop walking through everything."""
+stop_animation = MoveStep()
+"""Stop the walking animation."""
+start_animation = MoveStep()
+"""Animate the walking again."""
+transparency_up = MoveStep()
+"""One step more transparent (0 = opaque, 7 = most)."""
+transparency_down = MoveStep()
+"""One step less transparent."""
+
+
+def switch_on(switch: Fixed | Switch) -> MoveStep:
+    """Move step: turn a switch ON: ``switch_on(switches.door_open)``."""
+    return MoveStep()
+
+
+def switch_off(switch: Fixed | Switch) -> MoveStep:
+    """Move step: turn a switch OFF: ``switch_off(switches.door_open)``."""
+    return MoveStep()
+
+
+def change_graphic(charset: str, index: SpriteIndex | Dynamic) -> MoveStep:
+    """Move step: change the character's graphic to character ``index`` (0-7,
+    see SpriteIndex) of the CharSet image ``charset`` (file name without
+    extension)."""
+    return MoveStep()
+
+
+# play_se(name, volume, tempo, balance) is a move step too (see Audio).
+
+
+def move(code: int) -> MoveStep:
+    """Move step by its raw code (for codes rpgsync has no name for)."""
+    return MoveStep()
+
+
+class Character:
+    """A character on the map: ``this``, ``player``, ``events[id]``, vehicles."""
+
+    map_id: Value
+    x: Value
+    y: Value
+    direction: Value
+    screen_x: Value
+    screen_y: Value
+    facing: Direction
+    """Test with ``this.facing == "up"``."""
+
+    def move(
+        self, *steps: MoveStep, frequency: Frequency | Dynamic = 6, repeat: bool = False, skippable: bool = False
+    ) -> None:
+        """Move Event: give the character a route to follow.
+
+        Between ``jump_start`` and ``jump_end`` only movement steps count.
+        Speed can only change relative to the current one (speed_up /
+        speed_down).
+
+        Args:
+            steps: the route, e.g. ``move_up * 3, face_left``.
+            frequency: 1 (slow) to 8 (continuous); affects moving, turning and waiting.
+            repeat: loop the route forever.
+            skippable: skip steps that cannot be done (blocked) instead of waiting.
+        """
+
+    def set_location(self, x: Number, y: Number, direction: TeleportDirection = "retain") -> None:
+        """Set Event Location: move this event instantly.  x and y are both
+        numbers or both variables[id]."""
+
+    def show_animation(self, animation: Fixed, wait: bool = False, whole_map: bool = False) -> None:
+        """Show Battle Animation on this character (also works outside battle).
+
+        Args:
+            animation: animation id of the database.
+            wait: wait until the animation ends.
+            whole_map: play it over the whole screen instead of the character.
+        """
+
+    def call(self, page: Number) -> None:
+        """Call Event: run one page of this map event and wait for it."""
+
+    def flash(
+        self,
+        red: Fixed | None = None,
+        green: Fixed | None = None,
+        blue: Fixed | None = None,
+        strength: Fixed | None = None,
+        duration: float | None = None,
+        wait: bool | None = None,
+        extra: Extra = (),
+    ) -> None:
+        """Flash the character with a colour.
+
+        Args:
+            red, green, blue: colour, 0-31 each (default 31).
+            strength: 0-31 (default 31).
+            duration: seconds, in steps of 0.1 (default 0.5).
+            wait: wait until the flash ends.
+        """
+
+
+class ThisEvent(Character):
+    def erase(self) -> None:
+        """Erase Event: remove this event until the player re-enters the map."""
+
+
+class PlayerCharacter(Character):
+    vehicle: Vehicle | None
+    """Test with ``player.vehicle == "boat"``."""
+    visible: bool
+    """Assign to hide or show the hero (``player.visible = False``)."""
+
+
+class VehicleCharacter(Character):
+    def set_sprite(self, charset: str, index: Fixed | None = None, *, extra: Extra = ()) -> None:
+        """Change the vehicle's graphic (CharSet name and character 0-7)."""
+
+
+class Events:
+    def __getitem__(self, key: int | Variable) -> Character: ...
+
+
+class CommonEvent:
+    def __call__(self) -> None:
+        """Call this common event and wait for it to end."""
+
+
+class CommonEvents:
+    def __getitem__(self, key: Fixed) -> CommonEvent: ...
+
+
+class CommonEventTable(CommonEvents):
+    """The common events of database/common_events.py: its @common_event
+    functions, called as ``common_events.name()`` (``common_events[10]()``
+    works too).  The nested ``class Config:`` holds ``size``, the number of
+    slots the editor shows."""
+
+
+class CommonEventFunction:
+    """A function decorated with @common_event: ``common_events.name()`` calls it."""
+
+    @overload
+    def __get__(self, obj: None, owner: type, /) -> CommonEventFunction: ...
+    @overload
+    def __get__(self, obj: object, owner: type, /) -> CommonEvent: ...
+    def __get__(self, obj: object, owner: type, /) -> CommonEventFunction | CommonEvent:
+        return CommonEvent()
+
+
+class TroopEventTable:
+    """The battle events of database/troop_events.py: one @troop function per
+    monster group that has some, holding its @page functions."""
+
+
+class Percent(Value):
+    """``percent(n)``: n% of the target's HP."""
+
+
+class Enemy:
+    """``enemies[i]``: an enemy of the current battle (troop member)."""
+
+    hp: Value
+    sp: Value
+    max_hp: Value
+    max_sp: Value
+    attack: Value
+    defense: Value
+    spirit: Value
+    agility: Value
+    can_act: Condition
+    """In ``battle_condition(...)``: the enemy can act."""
+    targeted: Condition
+    """In ``battle_condition(...)``: the enemy is the current target."""
+
+    def hp_percent(self, min: int = 0, max: int = 100) -> Condition:
+        """Troop page condition: the enemy's HP is between min% and max% of its max HP."""
+
+    def turn(self, start: int, every: int = 0) -> Condition:
+        """Troop page condition (2003): the enemy's own turn count is ``start``, then
+        every ``every`` turns (``every=0``: that turn only)."""
+
+    def change_hp(self, amount: Number | Percent, lethal: bool | None = None, extra: Extra = ()) -> None:
+        """Change the enemy's HP (negative = damage); ``percent(n)`` changes
+        by n% of its HP.  It cannot die unless ``lethal=True``."""
+
+    def change_sp(self, amount: Number, extra: Extra = ()) -> None:
+        """Change the enemy's SP (negative = lose)."""
+
+    def add_state(self, state: Fixed, *, extra: Extra = ()) -> None:
+        """Inflict a state on the enemy."""
+
+    def remove_state(self, state: Fixed, *, extra: Extra = ()) -> None:
+        """Cure a state of the enemy."""
+
+    def show(self, *, extra: Extra = ()) -> None:
+        """Make a hidden enemy appear."""
+
+
+class Enemies:
+    def __getitem__(self, key: Fixed) -> Enemy: ...
+
+
+class Picture:
+    """``pictures[id]``: one of the screen pictures.  Pictures with a higher
+    number are drawn on top; coordinates are the picture's centre."""
+
+    def show(
+        self,
+        name: str,
+        *,
+        x: Number = 0,
+        y: Number = 0,
+        scroll_with_map: bool | None = None,
+        magnify: Fixed | None = None,
+        transparency: Fixed | None = None,
+        transparent_color: bool | None = None,
+        red: Fixed | None = None,
+        green: Fixed | None = None,
+        blue: Fixed | None = None,
+        saturation: Fixed | None = None,
+        effect: PictureEffect | None = None,
+        effect_power: Fixed | None = None,
+        bottom_transparency: Fixed | None = None,
+        extra: Extra = (),
+    ) -> None:
+        """Show Picture.
+
+        Args:
+            name: image of the Picture folder.
+            x, y: centre position in pixels; both numbers or both variables[id].
+            scroll_with_map: move with the map instead of staying on screen.
+            magnify: zoom in percent (100 = normal).  Avoid scrolling the map
+                with a picture zoomed below 2%: RPG_RT can crash.
+            transparency: 0 (opaque) to 100 (invisible).
+            transparent_color: draw the image's transparent colour as transparent.
+            red, green, blue, saturation: tint, 0-200 (100 = unchanged).
+            effect: none, rotation or wave.
+            effect_power: speed of the rotation / strength of the wave.
+            bottom_transparency: transparency of the lower half (2003; defaults to transparency).
+        """
+
+    def move(
+        self,
+        *,
+        x: Number = 0,
+        y: Number = 0,
+        magnify: Fixed | None = None,
+        transparency: Fixed | None = None,
+        red: Fixed | None = None,
+        green: Fixed | None = None,
+        blue: Fixed | None = None,
+        saturation: Fixed | None = None,
+        effect: PictureEffect | None = None,
+        effect_power: Fixed | None = None,
+        duration: float | None = None,
+        wait: bool | None = None,
+        bottom_transparency: Fixed | None = None,
+        p4: Fixed | None = None,
+        p7: Fixed | None = None,
+        extra: Extra = (),
+    ) -> None:
+        """Move Picture: change position, zoom, transparency or tint over time.
+
+        Args:
+            x, y: new centre position (both numbers or both variables[id]).
+            duration: seconds, in steps of 0.1.
+            wait: wait until the move ends.
+            (other arguments: as in show(); p4/p7 are unused raw parameters)
+        """
+
+    def erase(self, extra: Extra = ()) -> None:
+        """Erase Picture."""
+
+
+class Pictures:
+    def __getitem__(self, key: Fixed) -> Picture: ...
+
+
+class Party:
+    """The hero party."""
+
+    gold: Counter
+    """``party.gold += 100``, ``if party.gold >= 100:``"""
+    size: Value
+    """Number of heroes in the party."""
+
+    def add(self, actor: Actor) -> None:
+        """Add a hero to the party (up to 4)."""
+
+    def remove(self, actor: Actor) -> None:
+        """Remove a hero from the party."""
+
+    def __contains__(self, member: Item | Actor) -> bool:
+        """``items[3] in party`` (holds the item) / ``actors[2] in party``."""
+
+
+class Timer:
+    """``timer1`` / ``timer2`` (2003): a countdown shown on screen."""
+
+    seconds: Value
+    """Seconds left; test with ``timer1.seconds <= 10``."""
+
+    def set(self, seconds: Number, visible: bool | None = None, in_battle: bool | None = None) -> None:
+        """Set the timer's start value (it does not start yet)."""
+
+    def start(self, seconds: Number | None = None, visible: bool | None = None, in_battle: bool | None = None) -> None:
+        """Start the countdown.
+
+        Args:
+            visible: show the timer on screen.
+            in_battle: keep counting during battles.
+            seconds: raw value stored with the command (unused by RPG Maker).
+        """
+
+    def stop(self, seconds: Number | None = None, visible: bool | None = None, in_battle: bool | None = None) -> None:
+        """Stop the countdown."""
+
+
+class GameState:
+    """Game-wide statistics and permissions."""
+
+    save_count: Value
+    battle_count: Value
+    win_count: Value
+    defeat_count: Value
+    escape_count: Value
+    midi_ticks: Value
+    """Position in the current MIDI music."""
+    allow_teleport: bool
+    """Assign to allow/forbid teleport skills."""
+    allow_escape: bool
+    """Assign to allow/forbid escape skills."""
+    allow_save: bool
+    """Assign to allow/forbid saving from the menu."""
+    allow_menu: bool
+    """Assign to allow/forbid opening the main menu."""
+
+
+class DynToken:
+    """A DynRPG variable/actor token: ``V[12]`` is written ``V12`` in the comment."""
+
+
+class _DynTokenPrefix:
+    def __getitem__(self, number: int) -> DynToken: ...
+
+
+class Word:
+    """Unquoted text in a DynRPG call, written as is in the comment: ``word.end`` is
+    the ``end`` of ``@remove_text "id", end``; ``word(" Page 2")`` (a text that is no
+    Python name) keeps the spaces of ``@dynparams_append_string  Page 2``.  A word
+    can't hold ``"``, ``,`` or a line break.  DynRPG gives most plugins a word
+    without its spaces, in lowercase: give texts as ``"strings"``.  A plugin's own
+    word is written the way the plugin reads it: ``word.fixed`` of ``dyn.write_text``
+    is the ``"fixed"`` DynText compares."""
+
+
+class _Words:
+    def __getattr__(self, text: str) -> Word: ...
+    def __call__(self, text: str, /) -> Word: ...
+
+
+DynNumber = int | float | Variable | DynToken
+"""A number in a DynRPG call: ``12``, ``variables.x`` (read when the call runs),
+``variables[variables.x]`` or a token like ``v[12]``."""
+DynString = str | DynToken
+"""A text in a DynRPG call: ``"text"``, ``actors[3].name`` (read when the call runs)
+or a token like ``n[3]``."""
+DynArg = DynNumber | DynString | Word
+"""Any argument of a DynRPG call."""
+
+
+class DynRPG:
+    """DynRPG plugin calls, stored as "@function args" comments:
+    ``dyn.change_text("id", r"\\v[1]", 0)``, ``dyn.dynparams_add_param(2, variables.clue)``.
+    Arguments are numbers, strings, ``variables[...]``, ``actors[...].name``, tokens like
+    ``v[12]`` or words (``word.end``).
+
+    The commands of the plugins rpgsync knows are below; ``rpgsync check`` warns about
+    their arguments and, from DynPlugins/, about calls no plugin of the game runs.  Any
+    other plugin's command works too: ``dyn.any_name(...)``.  A plugin version may read
+    more arguments than written here: they are accepted."""
+
+    def __getattr__(self, function: str) -> Callable[..., None]: ...
+
+    # DynTextPlugin.dll: texts drawn on the screen.  In the id and the text: \v[n]
+    # (variable), \n[n] (hero name), \i[n] / \I[n] (item name / description),
+    # \t[n] / \T[n] (skill name / description), \x[id] (another text)
+
+    def write_text(
+        self,
+        id: DynString,
+        x: DynNumber,
+        y: DynNumber,
+        text: DynString | DynNumber,
+        fixed: DynArg = ...,
+        color: DynNumber = ...,
+        picture: DynNumber = ...,
+        /,
+        *rest: DynArg,
+    ) -> None:
+        """DynTextPlugin: show a text at (x, y), drawn above a picture, while it shows
+        (with its transparency): ``dyn.write_text("gold", 10, 10, r"\\v[4] G", 0, 3)``.
+
+        Args:
+            fixed: ``word.fixed`` (written ``"fixed"``, as the plugin reads it) scrolls the
+                text with the map; 0: it stays on screen.
+            color: 0-19, a color of the system graphic.
+            picture: the picture it goes with (default: PictureID in DynRPG.ini).
+        """
+
+    def append_line(self, id: DynString, text: DynString | DynNumber, end: DynArg = ..., /, *rest: DynArg) -> None:
+        """DynTextPlugin: add a line below a text."""
+
+    def append_text(self, id: DynString, text: DynString | DynNumber, end: DynArg = ..., /, *rest: DynArg) -> None:
+        """DynTextPlugin: add to the end of a text's last line."""
+
+    def change_text(
+        self, id: DynString, text: DynString | DynNumber, color: DynNumber | Word, /, *rest: DynArg
+    ) -> None:
+        """DynTextPlugin: replace a text; ``color``: 0-19, or ``word.end`` to keep it."""
+
+    def change_position(self, id: DynString, x: DynNumber, y: DynNumber, /, *rest: DynArg) -> None:
+        """DynTextPlugin: move a text to (x, y)."""
+
+    def remove_text(self, id: DynString, end: DynArg = ..., /, *rest: DynArg) -> None:
+        """DynTextPlugin: erase a text (``dyn.remove_text("id", word.end)``)."""
+
+    def remove_all(self, /, *rest: DynArg) -> None:
+        """DynTextPlugin: erase every text."""
+
+    # DynParams.dll: rewrites the parameters of the next command (rpgsync writes these
+    # comments for a variable where RPG Maker takes a number, see the README)
+
+    def dynparams_add_param(self, index: DynNumber, value: DynNumber = ..., /, *rest: DynArg) -> None:
+        """DynParams: parameter ``index`` (from 1) of the next command := ``value``; with
+        one number, it is the value of the next parameter (5, 6... or from set_index)."""
+
+    def dynparams_set_index(self, index: DynNumber, /, *rest: DynArg) -> None:
+        """DynParams: the parameter ``dynparams_add_param(value)`` writes next."""
+
+    def dynparams_append_string(self, text: Word | DynString, /, *rest: DynArg) -> None:
+        """DynParams: add to the text of the next command; the comment's text after the
+        name, as is: ``word("Simu-Com 0")``."""
+
+    def dynparams_append_number(self, value: DynNumber, /, *rest: DynArg) -> None:
+        """DynParams: add a number to the text of the next command."""
+
+    def dynparams_message_line_append_string(self, line: DynNumber, text: DynString, /, *rest: DynArg) -> None:
+        """DynParams: add to line 1-4 of the next message."""
+
+    def dynparams_message_line_append_number(self, line: DynNumber, value: DynNumber, /, *rest: DynArg) -> None:
+        """DynParams: add a number to line 1-4 of the next message."""
+
+    def dynparams_choice_case_append_string(self, choice: DynNumber, text: DynString, /, *rest: DynArg) -> None:
+        """DynParams: add to a choice (from 1) of the next Show Choices."""
+
+    def dynparams_choice_case_append_number(self, choice: DynNumber, value: DynNumber, /, *rest: DynArg) -> None:
+        """DynParams: add a number to a choice (from 1) of the next Show Choices."""
+
+    def dynparams_overwrite_next(self, /, *rest: DynArg) -> None:
+        """DynParams: apply what the calls before built to the next command."""
+
+    def dynparams_clear_params(self, /, *rest: DynArg) -> None:
+        """DynParams: forget what the calls before built."""
+
+    def dynparams_list_params(self, /, *rest: DynArg) -> None:
+        """DynParams: show what the calls before built (a message box)."""
+
+    def dynparams_start_record(self, /, *rest: DynArg) -> None:
+        """DynParams: write each command that runs into DynPlugins/DynParamsRecord.txt."""
+
+    def dynparams_stop_record(self, /, *rest: DynArg) -> None:
+        """DynParams: stop writing DynPlugins/DynParamsRecord.txt."""
+
+    # msg_commands.dll
+
+    def process_cmd(self, /, *rest: DynArg) -> None:
+        """msg_commands."""
+
+    # EasyRPG Player's own commands (no DLL; "easyrpg" in the patches)
+
+    def call(self, function: Word | DynString, /, *args: DynArg) -> None:
+        """EasyRPG Player: run a command with the other arguments:
+        ``dyn.call(word.easyrpg_add, 5, 1, 2)``."""
+
+    def easyrpg_output(self, mode: Word | DynString, message: DynString, /, *args: DynArg) -> None:
+        """EasyRPG Player: write a message to its log; ``mode``: ``word.Debug``, ``word.Info``,
+        ``word.Warning`` or ``word.Error``; ``$1``-``$9`` in it: the arguments after it."""
+
+    def easyrpg_add(self, variable: DynNumber, value: DynNumber, /, *values: DynNumber) -> None:
+        """EasyRPG Player: variable number ``variable`` := the sum of the values."""
+
+
+ManiacValue = int | Value | Switch
+"""A Maniac value: a number, ``variables[n]``, ``variables[variables[n]]`` or
+``switches[n]`` (1 when ON)."""
+
+
+class ManiacPatch:
+    """Maniac Patch commands (add "maniac" to ``patches`` in pyproject.toml).
+
+    Every Maniac command is written ``maniac.name(...)``.  Commands with a
+    known layout take named arguments; any command can also be written with
+    its raw parameters as positional numbers: ``maniac.control_strings(0, 1, 2,
+    text="...")``.  rpgsync writes the raw form when a command's parameters
+    don't fit its named form."""
+
+    def get_save_info(
+        self,
+        *params: int,
+        slot: ManiacValue = 0,
+        leader_name: bool = False,
+        date: Variable = ...,
+        time: Variable = ...,
+        level: Variable = ...,
+        hp: Variable = ...,
+        name_string: Fixed = 0,
+        face1: ManiacValue = 0,
+        face2: ManiacValue = 0,
+        face3: ManiacValue = 0,
+        face4: ManiacValue = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Read a save's title data: date (YYMMDD, 0 = no save), time (HHMMSS), first hero's level and HP; leader_name also copies the leader's name into string name_string; faces go into pictures face1-face4 (0 = none; the four share how they are given). (3001)"""
+
+    def save(
+        self,
+        *params: int,
+        slot: ManiacValue = 0,
+        result: Variable | None = None,
+        use_result: bool = True,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Save into a slot (1 and up); result gets 1 on success, 0 on failure. (3002)"""
+
+    def load(
+        self,
+        *params: int,
+        slot: ManiacValue = 0,
+        skip_check: bool = False,
+        no_blackout: bool = False,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Load a slot; skip_check loads without checking the file first. (3003)"""
+
+    def end_load_process(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """End the dark state after a load (obsolete). (3004)"""
+
+    def get_mouse_position(
+        self, *params: int, x: Variable = ..., y: Variable = ..., extra: Extra = (), text: str = ""
+    ) -> None:
+        """The mouse position in 320 x 240 coordinates. (3005)"""
+
+    def set_mouse_position(
+        self, *params: int, x: ManiacValue = 0, y: ManiacValue = 0, extra: Extra = (), text: str = ""
+    ) -> None:
+        """Move the mouse (x and y share how they are given). (3006)"""
+
+    def show_string_picture(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Show a picture made of text (raw parameters; text is \\x01TEXT\\x01SYSTEM\\x01FONT). (3007)"""
+
+    def get_picture_info(
+        self,
+        *params: int,
+        info: Literal["original_size", "current_size", "target"] = "original_size",
+        origin: Literal["center", "top_left", "edges"] = "center",
+        picture: ManiacValue = 0,
+        x: Variable = ...,
+        y: Variable = ...,
+        width: Variable = ...,
+        height: Variable = ...,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Position and size of a picture: info original_size / current_size / target; origin center / top_left / edges (left, top, right, bottom). (3008)"""
+
+    def control_battle(
+        self,
+        *params: int,
+        hook: Literal["atb", "damage", "targeting", "state", "stat_change"] = "atb",
+        common_event: ManiacValue = 0,
+        first_var: Variable = ...,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Battle hooks: call common_event at each atb / damage / targeting / state / stat_change, values passed through variables from first_var. (3009)"""
+
+    def control_atb_gauge(
+        self,
+        *params: int,
+        target: Literal["actor", "member", "party", "enemy", "troop"] = "actor",
+        target_id: ManiacValue = 0,
+        op: Literal["set", "add", "sub"] = "set",
+        unit: Literal["value", "percent"] = "value",
+        value: ManiacValue = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Set, add to or subtract from an ATB gauge (0-300000, or percent). (3010)"""
+
+    def change_battle_command_ex(
+        self,
+        *params: int,
+        disable_row: bool = False,
+        no_fight: bool = False,
+        no_auto: bool = False,
+        no_escape: bool = False,
+        win: bool = False,
+        lose: bool = False,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Battle commands: disable the row command, remove fight / auto / escape, add win / lose. (3011)"""
+
+    def get_battle_info(
+        self,
+        *params: int,
+        target: Literal["actor", "member", "party", "enemy", "troop"] = "actor",
+        info: Fixed = 0,
+        target_id: ManiacValue = 0,
+        first_var: Variable = ...,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Battle information into variables from first_var. (3012)"""
+
+    def control_var_array(
+        self,
+        *params: int,
+        op: Literal[
+            "copy",
+            "swap",
+            "sort",
+            "sort_descending",
+            "shuffle",
+            "enumerate",
+            "add",
+            "sub",
+            "mul",
+            "div",
+            "mod",
+            "or",
+            "and",
+            "xor",
+            "shl",
+            "shr",
+        ] = "copy",
+        a: ManiacValue = 0,
+        length: ManiacValue = 0,
+        b: ManiacValue = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Operate on variable arrays: a (length variables from id a) with b (ids are numbers, or variables[n] for an id read from a variable). (3013)"""
+
+    def key_input_proc_ex(
+        self,
+        *params: int,
+        op: Literal["keyboard", "keyboard_raw", "key", "joypad", "joypad_raw", "remap_joypad"] = "keyboard",
+        output: Variable = ...,
+        key: ManiacValue = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Keyboard / joypad state into variables (op key: one key, given by key code). (3014)"""
+
+    def rewrite_map(
+        self,
+        *params: int,
+        tiles_from_vars: bool = False,
+        layer: Literal["lower", "upper"] = "lower",
+        tile: ManiacValue = 0,
+        x: ManiacValue = 0,
+        y: ManiacValue = 0,
+        width: ManiacValue = 0,
+        height: ManiacValue = 0,
+        no_autotile: bool = False,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Replace map tiles (until the map reloads); tiles_from_vars reads tile ids from variables starting at tile. (3015)"""
+
+    def control_global_save(
+        self,
+        *params: int,
+        op: Literal["open", "close", "save", "save_close", "load_values", "store_values"] = "open",
+        kind: Literal["switches", "variables"] = "switches",
+        game_id: ManiacValue = 0,
+        global_id: ManiacValue = 0,
+        count: ManiacValue = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Global save (Save.lgs) shared by every save: open, close, save, save_close, load_values / store_values switches or variables. (3016)"""
+
+    def change_picture_id(
+        self,
+        *params: int,
+        op: Literal["move", "swap", "slide"] = "move",
+        first: ManiacValue = 0,
+        count: ManiacValue = 0,
+        target: ManiacValue = 0,
+        ignore_out_of_range: bool = False,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Renumber pictures: move, swap or slide count pictures from first. (3017)"""
+
+    def set_game_option(
+        self,
+        *params: int,
+        option: Literal[
+            "run_when_inactive",
+            "fps",
+            "picture_limit",
+            "frame_skip",
+            "mouse_messages",
+            "battle_origin",
+            "battle_animation_limit",
+            "face_size",
+        ] = "run_when_inactive",
+        value: ManiacValue = 0,
+        value2: Fixed = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Game options: run_when_inactive, fps, picture_limit, frame_skip, mouse_messages, battle_origin, battle_animation_limit, face_size. (3018)"""
+
+    def call_command(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Run any event command (raw parameters). (3019)"""
+
+    def control_strings(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """String variables: assign, append, convert, search, split... (raw parameters). (3020)"""
+
+    def get_game_info(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Map, screen, tile, interpreter, face, BGM information into variables (raw parameters). (3021)"""
+
+    def edit_picture(
+        self,
+        *params: int,
+        picture: ManiacValue = 0,
+        x: ManiacValue = 0,
+        y: ManiacValue = 0,
+        width: ManiacValue = 0,
+        height: ManiacValue = 0,
+        first_var: ManiacValue = 0,
+        opaque: bool = False,
+        keep_area: bool = False,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Write pixels (ARGB values from variables from first_var) into a picture. (3025)"""
+
+    def write_picture(
+        self,
+        *params: int,
+        name_from: Literal["text", "string", "string_ref"] = "text",
+        target: Literal["screen", "picture"] = "screen",
+        picture: ManiacValue = 0,
+        name_string: Fixed = 0,
+        dynamic: bool = False,
+        opaque: bool = False,
+        filename: str = "",
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Save the screen or a picture as an image file. (3026)"""
+
+    def add_move_route(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Maniac command (3027)"""
+
+    def edit_tile(
+        self,
+        *params: int,
+        picture: ManiacValue = 0,
+        x: ManiacValue = 0,
+        y: ManiacValue = 0,
+        width: ManiacValue = 0,
+        height: ManiacValue = 0,
+        tile: ManiacValue = 0,
+        no_autotile: bool = False,
+        clear: bool = False,
+        tiles_from_vars: bool = False,
+        layer: Literal["lower", "upper"] = "lower",
+        tileset: ManiacValue = 0,
+        pattern: ManiacValue = 0,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Draw map tiles onto a picture. (3028)"""
+
+    def control_text_processing(
+        self,
+        *params: int,
+        source: Literal["id", "variable", "variable_ref", "name", "string", "string_ref"] = "id",
+        on_marker: bool = False,
+        on_open: bool = False,
+        on_close: bool = False,
+        on_char: bool = False,
+        event: Fixed = 0,
+        info_var: Fixed = 0,
+        info_string: Fixed = 0,
+        number_args: Fixed = 0,
+        string_args: Fixed = 0,
+        name: str = "",
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Call a common event on message events: on_marker (the \\e text marker), on_open, on_close, on_char. (3029)"""
+
+    def script(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Run a Maniac script (raw parameters; text is the first line). (3030)"""
+
+    def script_line(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """A following script line. (3031)"""
+
+    def zoom(
+        self,
+        *params: int,
+        x: ManiacValue = 0,
+        y: ManiacValue = 0,
+        scale: ManiacValue = 0,
+        duration: ManiacValue = 0,
+        layer: ManiacValue = 0,
+        wait: bool = False,
+        extra: Extra = (),
+        text: str = "",
+    ) -> None:
+        """Zoom the screen around x, y. (3032)"""
+
+    def console(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Text console (raw parameters). (3033)"""
+
+    def control_self_variable(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Control self variables, switches and strings (raw parameters). (3036)"""
+
+    def control_media_option(self, *params: int, extra: Extra = (), text: str = "") -> None:
+        """Media options (raw parameters). (3038)"""
+
+    def __getattr__(self, command: str) -> Callable[..., None]:
+        """Other Maniac commands, by name (control_strings, show_string_picture,
+        command_3036, ...): raw parameters as positional numbers, text=..."""
+        ...
+
+
+# `variables` and `switches` come from the game's database/variables.py and
+# database/switches.py (classes of rpgsync.tables), which name them.
+items = Items()
+actors = Actors()
+events = Events()
+"""Events of the current map, by id."""
+enemies = Enemies()
+pictures = Pictures()
+party = Party()
+this = ThisEvent()
+"""The event running the script."""
+player = PlayerCharacter()
+"""The hero on the map."""
+boat = VehicleCharacter()
+ship = VehicleCharacter()
+airship = VehicleCharacter()
+timer1 = Timer()
+timer2 = Timer()
+game = GameState()
+dyn = DynRPG()
+maniac = ManiacPatch()
+V = VV = VVV = v = vv = vvv = N = NV = NVV = n = nv = nvv = _DynTokenPrefix()
+word = _Words()
+"""Unquoted text in a DynRPG call: ``word.end``, ``word("Simu-Com Faceset 00")`` (see Word)."""
+started_by_action_key = Condition()
+"""Condition: the event was started with the action key."""
+bgm_looped = Condition()
+"""Condition: the current music has played through once (MIDI only; also
+true right after loading a save)."""
+
+
+def randint(a: Fixed, b: Fixed) -> Value:
+    """A random number from a to b (inclusive), like random.randint."""
+    return Value()
+
+
+def percent(value: Fixed) -> Percent:
+    """n% of the target's HP, for enemies[i].change_hp()."""
+    return Percent()
+
+
+def input_number(digits: Digits | Dynamic) -> Value:
+    """Input Number: the player types a number.
+
+    ``variables[3] = input_number(digits=4)``
+
+    Args:
+        digits: how many digits the player can type (1-6 in 2000, 1-7 in 2003,
+            up to 9 with the Maniac Patch).
+    """
+    return Value()
+
+
+def terrain_id(x: Number, y: Number) -> Value:
+    """The terrain id of a map tile: ``variables[5] = terrain_id(10, 4)``.
+    Empty tiles give the chipset's first terrain (water)."""
+    return Value()
+
+
+def event_id_at(x: Number, y: Number) -> Value:
+    """The id of the event on a tile (the highest if several, 0 if none):
+    ``variables[5] = event_id_at(this.x, this.y)``."""
+    return Value()
+
+
+def key_input(
+    *,
+    wait: bool | Fixed = False,
+    directions: bool | Fixed = False,
+    decision: bool | Fixed = False,
+    cancel: bool | Fixed = False,
+    numbers: bool | Fixed = False,
+    operators: bool | Fixed = False,
+    time_variable: Variable | None = None,
+    count_time: bool | Fixed = False,
+    shift: bool | Fixed = False,
+    down: bool | Fixed = False,
+    left: bool | Fixed = False,
+    right: bool | Fixed = False,
+    up: bool | Fixed = False,
+    layout: Literal[2000, 2003] | None = None,
+) -> Value:
+    """Key Input Processing: ``variables[148] = key_input(down=True, up=True, wait=True)``.
+
+    The variable receives the key pressed: 1 down, 2 left, 3 right, 4 up,
+    5 decision, 6 cancel, 7 shift, 10-19 numbers 0-9, 20-24 + - * / and .
+    (0 when nothing was pressed).
+
+    Args:
+        wait: wait until one of the keys is pressed.
+        directions: all four arrows at once (older editor versions).
+        decision, cancel, shift, down, left, right, up: keys to check.
+        numbers, operators: number and operator keys (2003).
+        time_variable: store the time taken, in tenths of a second (2003).
+        count_time: whether time_variable is used.
+        layout: parameter layout of another editor version (set by rpgsync).
+    Flags may be integers when the Maniac Patch stores mouse buttons.
+    """
+    return Value()
+
+
+def cond(kind: int, a: int, b: int, c: int, d: int) -> Condition:
+    """Any other Conditional Branch, by its raw parameters."""
+    return Condition()
+
+
+def battle_condition(condition: Condition | bool) -> Condition:
+    """A battle Conditional Branch (troop events): switches, variables,
+    ``actors[id].can_act``, ``enemies[i].can_act``, ``enemies[i].targeted``,
+    ``actors[id].uses_command(n)``.  Example: ``if battle_condition(enemies[0].targeted):``"""
+    return Condition()
+
+
+def turn(start: int, every: int = 0) -> Condition:
+    """Troop page condition: the battle's turn count is ``start``, then every
+    ``every`` turns: ``turn(0)`` is the start of the battle, ``turn(1, every=2)``
+    turns 1, 3, 5...  (``every=0``: that turn only)."""
+    return Condition()
+
+
+def fatigue(min: int = 0, max: int = 100) -> Condition:
+    """Troop page condition: the party's fatigue (exhaustion) is between min% and max%."""
+    return Condition()
+
+
+# ==========================================================================
+# Structure
+# ==========================================================================
+
+
+class Route:
+    """A custom move route for page(route=...)."""
+
+
+class Event(Character):
+    """A map event: ``@event(30, "Gary", x=17, y=16)`` on ``class Gary(Event):``.
+    The event is a character of the map: ``Gary.move(...)``, ``Gary.x``.
+
+    Its pages are its ``page_1(self)``, ``page_2(self)``... methods, numbered
+    like the editor's tabs.  The active page is the last one whose ``when=``
+    holds; when none holds, the event is not on the map.  ``Gary.page_3()``
+    runs page 3 (Call Event); in Gary's pages, ``self`` is Gary.
+
+    The class attributes are the settings of every page, unless a page's
+    ``@page(...)`` says otherwise; a page without ``@page`` has no condition
+    and the class's settings.  A page's docstring is its first comment in the
+    game.
+    """
+
+    sprite: tuple[str, SpriteIndex] | None = None
+    """("CharSet", 0-7): the graphic of the pages (None: no graphic)."""
+    tile: int | None = None
+    """A tile of the chipset as the graphic of the pages, instead of a sprite."""
+    pattern: Pattern = "middle"
+    """Animation frame shown when standing still."""
+    translucent: bool = False
+    """Draw semi-transparent."""
+    trigger: Trigger = "action"
+    """How the pages start (action, touch, collision, autorun, parallel)."""
+    layer: Layer = "below"
+    """Below, same level as, or above the hero."""
+    overlap_forbidden: bool = False
+    """Other events cannot walk through it."""
+    animation: AnimationType = "non_continuous"
+    """How the sprite animates."""
+    move_type: MoveType = "stationary"
+    """Automatic movement; "custom" follows ``route``."""
+    frequency: Frequency = 3
+    """How often it moves (1-8)."""
+    speed: Speed = 3
+    """Movement speed (1 = 1/8 ... 4 = normal ... 6 = x4)."""
+    # direction and route are set on each page: @page(direction="left", route=route(...))
+
+
+class _EventDecorator(Protocol):
+    @overload
+    def __call__(self, cls: type[_E], /) -> _E: ...
+    @overload
+    def __call__(self, fn: Callable[[], None], /) -> Character: ...
+
+
+def event(id: int | None = None, name: str = "", x: int = 0, y: int = 0) -> _EventDecorator:
+    """A map event, on its class: ``@event(30, "Gary", x=17, y=16)`` then
+    ``class Gary(Event):`` (see Event).
+
+    Args:
+        id: event id; leave it out for a new event: the lowest free id is
+            assigned and written back into the script.
+        name: name shown in the editor.
+        x, y: tile position on the map.
+    """
+    return lambda fn: fn  # type: ignore[return-value]
+
+
+def page(
+    *,
+    when: Condition | bool | None = None,
+    sprite: tuple[str, SpriteIndex] | None = None,
+    tile: int | None = None,
+    direction: Direction = "down",
+    pattern: Pattern = "middle",
+    translucent: bool = False,
+    trigger: Trigger = "action",
+    layer: Layer = "below",
+    overlap_forbidden: bool = False,
+    animation: AnimationType = "non_continuous",
+    move_type: MoveType = "stationary",
+    frequency: Frequency = 3,
+    speed: Speed = 3,
+    route: Route | None = None,
+    id: int | None = None,
+    raw: bool = False,
+    switch_a: int | None = None,
+    switch_b: int | None = None,
+    variable: tuple[int, str, int] | None = None,
+    item: int | None = None,
+    actor: int | None = None,
+    timer: int | None = None,
+    timer2: int | None = None,
+) -> Callable[[_F], _F]:
+    """The condition and settings of an event page (a ``page_N`` function of
+    the event's class).  Pages are listed in order, page_1 first; the last page
+    whose conditions hold is the active one.  A setting left out is the class's
+    (see Event), else the default below; a page with no condition and the
+    class's settings needs no ``@page``.
+
+    Args:
+        when: conditions joined with ``and``: up to two ``switches[id]``,
+            ``variables[id] >= n`` (any comparison in 2003),
+            ``items[id] in party``, ``actors[id] in party``,
+            ``timer1.seconds <= n``, ``timer2.seconds <= n``.
+        sprite: ("CharSet", 0-7), the event's graphic; the index counts the
+            8 characters of the image left to right, top to bottom (see
+            SpriteIndex).  ``sprite=None``: no graphic (when the class has one).
+        tile: a tile of the chipset as graphic, instead of a sprite.
+        direction: facing direction of the graphic.
+        pattern: animation frame shown when standing still.
+        translucent: draw semi-transparent.
+        trigger: how the page starts (action, touch, collision, autorun, parallel).
+        layer: below, same level as, or above the hero.
+        overlap_forbidden: other events cannot walk through it.
+        animation: how the sprite animates.
+        move_type: automatic movement; "custom" follows ``route``.
+        frequency: how often it moves (1-8).
+        speed: movement speed (1 = 1/8 ... 4 = normal ... 6 = x4).
+        route: route(...) followed when move_type="custom"; ``route=None``: no
+            route (when the class has one).
+        id: the page's stored number, when pages are not numbered 1, 2, 3...
+        raw: the body is raw cmd(..., indent=N) lines (set by rpgsync).
+        switch_b: the editor's second switch slot, for pages that leave the
+            first one unchecked (``when`` puts a single switch in the first
+            slot; both behave the same).
+        switch_a, variable, item, actor, timer, timer2: the conditions in
+            explicit form (used instead of ``when`` for rare combinations).
+
+    A battle event page of a troop (database/troop_events.py) only takes
+    ``when``, ``switch_b``, ``id`` and ``raw``; its ``when`` joins with ``and``:
+    up to two ``switches[id]``, ``variables[id] >= n``, ``turn(n, every=m)``,
+    ``fatigue(min, max)``, ``enemies[i].hp_percent(min, max)``,
+    ``actors[id].hp_percent(min, max)`` and, in 2003,
+    ``enemies[i].turn(n, every=m)``, ``actors[id].turn(n, every=m)``,
+    ``actors[id].uses_command(n)``.  The page runs when they all hold.
+    """
+    return lambda fn: fn
+
+
+def common_event(
+    id: int | None = None,
+    name: str = "",
+    trigger: CommonEventTrigger = "call",
+    switch: int | None = None,
+    raw: bool = False,
+) -> Callable[[Callable[[], None]], CommonEventFunction]:
+    """A common event of the database.  Leave out the id for a new one.
+
+    Args:
+        trigger: call (run with common_events[id]()), autorun or parallel.
+        switch: condition switch of an autorun/parallel common event.
+        raw: the body is raw cmd(...) lines (set by rpgsync).
+    """
+    return lambda fn: fn
+
+
+def troop(id: int, name: str = "") -> Callable[[Callable[[], None]], Callable[[], None]]:
+    """The battle events of a troop (monster group), in database/troop_events.py:
+    its @page functions, in order.
+
+    Args:
+        id: the troop's id (its slot in database/troops.py, where troops are added).
+        name: the troop's name, as a label: rename the troop in database/troops.py.
+    """
+    return lambda fn: fn
+
+
+def route(*steps: MoveStep, repeat: bool = True, skippable: bool = False) -> Route:
+    """Custom move route: ``route(move_up * 2, move_down * 2, repeat=True)``."""
+    return Route()
+
+
+# ==========================================================================
+# Messages
+# ==========================================================================
+
+
+def text(*lines: str, split: bool = True) -> None:
+    """Show Message: one argument per line, up to 4 lines per box ("\\n" in an
+    argument starts a new line; with split=False each argument is exactly one
+    line, line breaks included).
+
+    Message codes: \\c[n] colour (0-19, from the System graphic), \\s[n] text
+    speed (1 fastest - 20 slowest), \\v[n] variable value, \\n[n] hero name,
+    \\$ gold window, \\. short pause, \\| long pause, \\! wait for a key,
+    \\^ close automatically, \\> \\< show instantly.  Use raw strings
+    (r"...") so backslashes stay as typed."""
+
+
+def comment(*lines: str, split: bool = True) -> None:
+    """An editor comment, kept in the game data.  A full-line ``# text`` in a
+    script does the same; DynRPG plugin calls are written ``dyn.function(...)``."""
+
+
+def face(faceset: str | None, index: Fixed | None = None, right: bool | None = None, flip: bool | None = None) -> None:
+    """Set the face shown in messages (it narrows the text area).
+
+    Args:
+        faceset: FaceSet image name, or None to remove the face.
+        index: face in the image (0-15).
+        right: show the face on the right side.
+        flip: mirror the face.
+    """
+
+
+def message_options(
+    transparent: bool = False,
+    position: MessagePosition = "bottom",
+    avoid_hero: bool = False,
+    continue_events: bool = False,
+) -> None:
+    """Message window settings.
+
+    Args:
+        transparent: no window background.
+        position: top, middle or bottom of the screen.
+        avoid_hero: move the window so it never hides the hero (overrides position).
+        continue_events: let other events run while a message is shown.
+    """
+
+
+def show_choices(*options: str, cancel: CancelOption | Dynamic | None = None, summary: str | None = None) -> str:
+    """Show Choices (up to 4), written as a match statement::
+
+        match show_choices("Yes", "No"):
+            case "Yes": ...
+            case "No": ...
+            case _: ...      # optional: separate cancel branch
+
+    When two options have the same text, the cases are the option
+    numbers (``case 0:``, ``case 1:``).
+
+    Args:
+        options: the texts of the choices.
+        cancel: the option (1-4) chosen with the cancel key; None forbids
+            cancelling, a ``case _:`` adds a separate cancel branch.
+        summary: editor summary of the options, when it differs from the texts.
+    """
+    return ""
+
+
+# ==========================================================================
+# Party, heroes, items
+# ==========================================================================
+
+ActorTarget = Actor | Party
+"""``party`` (every hero of the party), ``actors[id]`` or ``actors[variables[id]]``."""
+
+
+def change_exp(actor: ActorTarget, amount: Number, message: bool = False) -> None:
+    """Change Experience: ``change_exp(actors[1], 500)``, ``change_exp(party, -variables[3])``.
+
+    Args:
+        message: show the level-up message.
+    """
+
+
+def change_level(actor: ActorTarget, amount: Number, message: bool = False) -> None:
+    """Change Level: ``change_level(party, 1, message=True)`` (negative lowers it)."""
+
+
+def change_stat(actor: ActorTarget, stat: Stat, amount: Number, *, extra: Extra = ()) -> None:
+    """Permanently change a base stat: ``change_stat(actors[1], "attack", 5)``."""
+
+
+def change_hp(actor: ActorTarget, amount: Number, lethal: bool | None = None, *, extra: Extra = ()) -> None:
+    """Change HP (negative = damage).  Damage stops at 1 HP unless ``lethal=True``."""
+
+
+def change_sp(actor: ActorTarget, amount: Number, *, extra: Extra = ()) -> None:
+    """Change SP (negative = lose)."""
+
+
+def full_heal(actor: ActorTarget) -> None:
+    """Restore all HP and SP and cure all states."""
+
+
+def learn_skill(actor: ActorTarget, skill: Number, *, extra: Extra = ()) -> None:
+    """Teach a skill."""
+
+
+def forget_skill(actor: ActorTarget, skill: Number, *, extra: Extra = ()) -> None:
+    """Remove a skill."""
+
+
+def equip(actor: ActorTarget, item: Number, *, extra: Extra = ()) -> None:
+    """Equip an item (taken from the inventory)."""
+
+
+def unequip(actor: ActorTarget, slot: EquipSlot, p4: Fixed | None = None, *, extra: Extra = ()) -> None:
+    """Remove equipment from one slot or all of them."""
+
+
+def add_state(actor: ActorTarget, state: Fixed, *, extra: Extra = ()) -> None:
+    """Inflict a state (dead, poison, sleep...)."""
+
+
+def remove_state(actor: ActorTarget, state: Fixed, *, extra: Extra = ()) -> None:
+    """Cure a state."""
+
+
+def simulate_attack(
+    actor: ActorTarget,
+    attack: Fixed | None = None,
+    defense: Fixed | None = None,
+    spirit: Fixed | None = None,
+    variance: Fixed | None = None,
+    store_damage: Variable | None = None,
+    use_store_damage: bool | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Simulated Attack: deal damage as if attacked by an invisible enemy
+    (can cause a game over).
+
+    Args:
+        attack, defense, spirit: weights of the damage formula.
+        variance: random variation (0-10).
+        store_damage: also store the damage in this variable.
+    """
+
+
+def change_class(
+    actor: ActorTarget,
+    class_id: Fixed,
+    reset_level: bool | None = None,
+    skills: SkillMode | None = None,
+    stats: StatMode | None = None,
+    message: bool | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Change Class (2003): also changes base stats and battle commands.
+
+    Args:
+        class_id: new class (0 = none).
+        reset_level: back to level 1.
+        skills: keep, replace with the class skills, or add them.
+        stats: keep, halve, as at level 1, or as at the current level.
+        message: show the learned-skills message.
+    """
+
+
+def add_battle_command(actor: ActorTarget, command: Fixed, *, extra: Extra = ()) -> None:
+    """Add a battle command to the hero's menu (2003)."""
+
+
+def remove_battle_command(actor: ActorTarget, command: Fixed, *, extra: Extra = ()) -> None:
+    """Remove a battle command (2003); command 0 removes all."""
+
+
+def enter_hero_name(
+    actor: Fixed | None, charset: Fixed | None = None, use_current_name: bool | None = None, *, extra: Extra = ()
+) -> None:
+    """Open the name entry screen.
+
+    Args:
+        actor: hero id.
+        charset: letter set of the entry screen.
+        use_current_name: start from the current name instead of an empty one.
+    """
+
+
+# ==========================================================================
+# System
+# ==========================================================================
+
+
+def set_system_bgm(
+    context: BgmContext,
+    name: str,
+    fade: Fixed | None = None,
+    volume: Fixed | None = None,
+    tempo: Fixed | None = None,
+    balance: Fixed | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Change a system music (battle, victory, inn, vehicles, game over)."""
+
+
+def set_system_se(
+    context: SeContext,
+    name: str,
+    volume: Fixed | None = None,
+    tempo: Fixed | None = None,
+    balance: Fixed | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Change a system sound effect (cursor, decision, ...)."""
+
+
+def set_system_graphics(
+    name: str,
+    stretch: Literal["stretch", "tile"] | None = None,
+    font: Literal["gothic", "mincho"] | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Change the System graphic (windows, cursor, text colours)."""
+
+
+def set_transition(kind: TransitionKind, transition: Transition, *, extra: Extra = ()) -> None:
+    """Change a default screen transition (teleport, battle start/end)."""
+
+
+# ==========================================================================
+# Map and movement
+# ==========================================================================
+
+
+def teleport(map: Fixed, x: Fixed, y: Fixed, direction: TeleportDirection = "retain") -> None:
+    """Teleport the party to another map position."""
+
+
+def memorize_location(map: Variable, x: Variable, y: Variable, *, extra: Extra = ()) -> None:
+    """Store the party's map id and position in three variables."""
+
+
+def recall_location(map: Variable, x: Variable, y: Variable, *, extra: Extra = ()) -> None:
+    """Teleport the party to a position stored with memorize_location()."""
+
+
+def toggle_vehicle(*, extra: Extra = ()) -> None:
+    """Get on / off the vehicle the hero faces."""
+
+
+def set_vehicle_location(
+    vehicle: Literal["party", "boat", "ship", "airship"] | Fixed,  # int: a value the editor cannot set
+    map: Number,
+    x: Number,
+    y: Number,
+    direction: TeleportDirection | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Place a vehicle on a map (map, x and y: all numbers or all variables[id])."""
+
+
+def swap_events(first: Character, second: Character, *, extra: Extra = ()) -> None:
+    """Swap the positions of two events of the map."""
+
+
+def set_tileset(chipset: Fixed, *, extra: Extra = ()) -> None:
+    """Change the map's chipset (tileset)."""
+
+
+def set_panorama(
+    name: str,
+    scroll_x: bool | None = None,
+    scroll_y: bool | None = None,
+    auto_scroll_x: bool | None = None,
+    speed_x: Fixed | None = None,
+    auto_scroll_y: bool | None = None,
+    speed_y: Fixed | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Change the panorama (parallax background) of the map."""
+
+
+def set_encounter_rate(steps: Fixed, *, extra: Extra = ()) -> None:
+    """Average number of steps between random battles (0 = none)."""
+
+
+def replace_tile(layer: Literal["lower", "upper"], old: Fixed, new: Fixed, *, extra: Extra = ()) -> None:
+    """Replace every tile `old` by tile `new` on a layer of the map."""
+
+
+def add_teleport_target(
+    map: Fixed, x: Fixed, y: Fixed, switch: Fixed | None = None, use_switch: bool | None = None, *, extra: Extra = ()
+) -> None:
+    """Add a destination for teleport skills (optionally turning a switch ON)."""
+
+
+def remove_teleport_target(
+    map: Fixed,
+    x: Fixed | None = None,
+    y: Fixed | None = None,
+    switch: Fixed | None = None,
+    use_switch: bool | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Remove a teleport skill destination."""
+
+
+def set_escape_target(
+    map: Fixed, x: Fixed, y: Fixed, switch: Fixed | None = None, use_switch: bool | None = None, *, extra: Extra = ()
+) -> None:
+    """Set where escape skills lead (optionally turning a switch ON)."""
+
+
+def wait_for_movement() -> None:
+    """Wait until all moving events finished their routes (except repeating ones)."""
+
+
+def halt_all_movement() -> None:
+    """Stop every event's movement."""
+
+
+# ==========================================================================
+# Screen
+# ==========================================================================
+
+
+def erase_screen(transition: Transition = "default") -> None:
+    """Erase Screen: hide the map with a transition (effects done before
+    show_screen() appear with it)."""
+
+
+def show_screen(transition: Transition = "default") -> None:
+    """Show Screen after erase_screen()."""
+
+
+def tint_screen(
+    red: Fixed | None = None,
+    green: Fixed | None = None,
+    blue: Fixed | None = None,
+    saturation: Fixed | None = None,
+    duration: float | None = None,
+    wait: bool | None = None,
+    extra: Extra = (),
+) -> None:
+    """Tint Screen: colour 0-200 per channel (100 = normal), over `duration` seconds."""
+
+
+def flash_screen(
+    red: Fixed | None = None,
+    green: Fixed | None = None,
+    blue: Fixed | None = None,
+    strength: Fixed | None = None,
+    duration: float | None = None,
+    wait: bool | None = None,
+    mode: FlashMode | None = None,
+    extra: Extra = (),
+) -> None:
+    """Flash Screen: colour 0-31 per channel; mode begin/end repeats (2003)."""
+
+
+def shake_screen(
+    strength: Fixed | None = None,
+    speed: Fixed | None = None,
+    duration: float | None = None,
+    wait: bool | None = None,
+    mode: FlashMode | None = None,
+    extra: Extra = (),
+) -> None:
+    """Shake Screen (strength and speed 1-9); mode begin/end shakes until stopped (2003)."""
+
+
+def pan_screen(direction: Direction, distance: Fixed, speed: Fixed = 3, wait: bool = False) -> None:
+    """Scroll the view by `distance` tiles away from the hero."""
+
+
+def reset_screen_pan(speed: Fixed = 3, wait: bool = False, direction: Direction = "up", distance: Fixed = 0) -> None:
+    """Scroll the view back to the hero."""
+
+
+def lock_screen(direction: Direction = "up", distance: Fixed = 0, speed: Fixed = 0, wait: bool = False) -> None:
+    """Lock the view: it stops following the hero."""
+
+
+def unlock_screen(direction: Direction = "up", distance: Fixed = 0, speed: Fixed = 0, wait: bool = False) -> None:
+    """Unlock the view: it follows the hero again."""
+
+
+def weather(kind: WeatherKind, strength: Strength = "weak") -> None:
+    """Weather effect: rain, snow, fog or sandstorm (2003), or none."""
+
+
+# ==========================================================================
+# Audio and video
+# ==========================================================================
+
+
+def play_bgm(name: str, fade: Fixed = 0, volume: Fixed = 100, tempo: Fixed = 100, balance: Fixed = 50) -> None:
+    """Play a music of the Music folder (MIDI, WAV, MP3, OGG).
+
+    Args:
+        fade: fade-in in milliseconds.
+        volume: 0-100.
+        tempo: 50-150 (100 = normal speed).
+        balance: 0 (left) - 100 (right), 50 = centre.
+    """
+
+
+def play_se(name: str, volume: Fixed = 100, tempo: Fixed = 100, balance: Fixed = 50) -> MoveStep:
+    """Play a sound effect of the Sound folder ("(OFF)" stops all sounds).
+    RPG_RT plays at most 4 sounds at once.  Also usable as a move step."""
+    return MoveStep()
+
+
+def fade_out_bgm(seconds: float) -> None:
+    """Fade the music out."""
+
+
+def memorize_bgm() -> None:
+    """Remember the current music."""
+
+
+def play_memorized_bgm() -> None:
+    """Play the music remembered with memorize_bgm()."""
+
+
+def play_movie(
+    name: str,
+    *,
+    x: Number = 0,
+    y: Number = 0,
+    width: Fixed | None = None,
+    height: Fixed | None = None,
+    extra: Extra = (),
+) -> None:
+    """Play a movie (.avi) of the Movie folder at a position and size."""
+
+
+# ==========================================================================
+# Flow and menus
+# ==========================================================================
+
+
+def wait(seconds: float = 0, key: bool = False) -> None:
+    """Wait in steps of 0.1 s.  ``wait(0.0)`` still pauses for a moment;
+    ``wait(key=True)`` waits for a key press (2003)."""
+
+
+def label(id: Fixed) -> None:
+    """A jump target for goto(id); with duplicates only the first counts."""
+
+
+def goto(id: Fixed) -> None:
+    """Jump to label(id)."""
+
+
+def break_loop() -> None:
+    """Break Loop outside a while loop (inside one, write ``break``)."""
+
+
+def game_over() -> None:
+    """Show the game over screen."""
+
+
+def return_to_title() -> None:
+    """Go back to the title screen."""
+
+
+def open_save_menu() -> None:
+    """Open the save screen."""
+
+
+def open_main_menu() -> None:
+    """Open the main menu."""
+
+
+def open_load_menu(*, extra: Extra = ()) -> None:
+    """Open the load screen (2003)."""
+
+
+def exit_game(*, extra: Extra = ()) -> None:
+    """Close the game (2003)."""
+
+
+def toggle_fullscreen(*, extra: Extra = ()) -> None:
+    """Switch between window and fullscreen (2003)."""
+
+
+def toggle_atb_mode(*, extra: Extra = ()) -> None:
+    """Switch the battle gauge between active and wait modes (2003)."""
+
+
+def open_video_options(*, extra: Extra = ()) -> None:
+    """Open the video / settings menu (2003; EasyRPG settings menu)."""
+
+
+# ==========================================================================
+# Battles, shops, inns
+# ==========================================================================
+
+
+def start_battle(
+    troop: Number,
+    *,
+    background: Literal["map", "image", "terrain"] | None = None,
+    escape: Literal["disallow", "end_event", "branch"] | None = None,
+    defeat: Literal["game_over", "branch"] | None = None,
+    first_strike: bool | None = None,
+    condition: Literal["none", "initiative", "back_attack", "surround", "pincer"] | None = None,
+    formation: Literal["terrain", "loose", "tight"] | None = None,
+    terrain: Fixed | None = None,
+    image: str | None = None,
+    extra: Extra = (),
+) -> str:
+    """Start a battle.  With branches, write it as a match::
+
+        match start_battle(3, escape="branch", defeat="branch"):
+            case "victory": ...
+            case "escape": ...
+            case "defeat": ...
+
+    Args:
+        troop: troop id.
+        background: from the map, an image (``image=``), or a terrain (``terrain=``).
+        escape: forbid escaping, end the event on escape, or an "escape" branch.
+        defeat: game over, or a "defeat" branch.
+        first_strike: the party attacks first.
+        condition, formation: battle start condition and formation (2003).
+    """
+    return ""
+
+
+def open_shop(
+    items: list[int],
+    *,
+    mode: Literal["buy_sell", "buy", "sell"] | None = None,
+    style: Fixed | None = None,
+    branches: bool | None = None,
+    p3: Fixed | None = None,
+    extra: Extra = (),
+) -> str:
+    """Open a shop selling `items`.  For branches use
+    ``match open_shop([...]):`` with ``case "bought":`` / ``case "not_bought":``.
+
+    Args:
+        mode: buy and sell, buy only or sell only.
+        style: shop message set (0-2).
+    """
+    return ""
+
+
+def inn(price: Fixed, *, style: Fixed | None = None, branches: bool | None = None, extra: Extra = ()) -> str:
+    """Offer a night at the inn.  For branches use ``match inn(50):`` with
+    ``case "stayed":`` / ``case "declined":``.
+
+    Args:
+        price: price in gold.
+        style: inn message set (0-1).
+    """
+    return ""
+
+
+def set_battle_background(name: str, *, extra: Extra = ()) -> None:
+    """Change the battle background (in battle)."""
+
+
+def show_battle_animation(
+    animation: Fixed, target: Fixed, wait: bool | None = None, allies: bool | None = None, *, extra: Extra = ()
+) -> None:
+    """Show a battle animation on an enemy (in battle; 2003 can target allies)."""
+
+
+def end_battle(*, extra: Extra = ()) -> None:
+    """End the current battle."""
+
+
+def battle_call_common_event(common_event: Fixed, *, extra: Extra = ()) -> None:
+    """Call a common event from a battle (2003)."""
+
+
+def force_flee(
+    who: Literal["party", "all_enemies", "enemy"],
+    enemy: Fixed | None = None,
+    ignore_conditions: bool | None = None,
+    *,
+    extra: Extra = (),
+) -> None:
+    """Make the party or enemies flee (2003)."""
+
+
+def enable_combo(actor: Fixed, command: Fixed, times: Fixed, *, extra: Extra = ()) -> None:
+    """Let a hero use a battle command several times per turn (2003)."""
+
+
+# ==========================================================================
+# Generic command
+# ==========================================================================
+
+
+def cmd(
+    code: int | CommandName, *params: int, text: str = "", indent: int | None = None
+) -> AbstractContextManager[None]:
+    """Any event command by code or name with its raw parameters, e.g.
+    ``cmd("TintScreen", 100, 100, 100, 100, 20, 1)``.  ``with cmd(...):``
+    opens a block for commands that have one.  rpgsync uses it only for
+    patch commands (Maniac, EasyRPG) and unusual data."""
+    return nullcontext()
+
+
+# What `from rpgsync.dsl import *` gives the scripts (tests/test_scaffold.py keeps it
+# complete).  Left out: CommonEvents, which database/common_events.py defines, and
+# the typing helpers.
+__all__ = [
+    "Actor",
+    "ActorTarget",
+    "Actors",
+    "AnimationType",
+    "BgmContext",
+    "CancelOption",
+    "Character",
+    "CommandName",
+    "CommonEvent",
+    "CommonEventFunction",
+    "CommonEventTable",
+    "CommonEventTrigger",
+    "Condition",
+    "Counter",
+    "Digits",
+    "Direction",
+    "DynArg",
+    "DynNumber",
+    "DynRPG",
+    "DynString",
+    "DynToken",
+    "Enemies",
+    "Enemy",
+    "EquipSlot",
+    "Event",
+    "Events",
+    "Extra",
+    "FaceIndex",
+    "FlashMode",
+    "Frequency",
+    "GameState",
+    "Item",
+    "Items",
+    "Layer",
+    "ManiacPatch",
+    "ManiacValue",
+    "MessagePosition",
+    "MoveStep",
+    "MoveType",
+    "N",
+    "NV",
+    "NVV",
+    "Number",
+    "Party",
+    "Pattern",
+    "Percent",
+    "Picture",
+    "PictureEffect",
+    "Pictures",
+    "PlayerCharacter",
+    "Route",
+    "SeContext",
+    "SkillMode",
+    "Speed",
+    "SpriteIndex",
+    "Stat",
+    "StatMode",
+    "Strength",
+    "Switch",
+    "SwitchRange",
+    "Switches",
+    "TeleportDirection",
+    "ThisEvent",
+    "Timer",
+    "Transition",
+    "TransitionKind",
+    "Trigger",
+    "TroopEventTable",
+    "V",
+    "VV",
+    "VVV",
+    "Value",
+    "Variable",
+    "VariableRange",
+    "Variables",
+    "Vehicle",
+    "VehicleCharacter",
+    "WeatherKind",
+    "Word",
+    "actors",
+    "add_battle_command",
+    "add_state",
+    "add_teleport_target",
+    "airship",
+    "battle_call_common_event",
+    "battle_condition",
+    "bgm_looped",
+    "boat",
+    "break_loop",
+    "change_class",
+    "change_exp",
+    "change_graphic",
+    "change_hp",
+    "change_level",
+    "change_sp",
+    "change_stat",
+    "cmd",
+    "comment",
+    "common_event",
+    "cond",
+    "dyn",
+    "enable_combo",
+    "end_battle",
+    "enemies",
+    "enter_hero_name",
+    "equip",
+    "erase_screen",
+    "event",
+    "event_id_at",
+    "events",
+    "exit_game",
+    "face",
+    "face_away_from_player",
+    "face_down",
+    "face_left",
+    "face_player",
+    "face_random",
+    "face_right",
+    "face_up",
+    "fade_out_bgm",
+    "fatigue",
+    "flash_screen",
+    "force_flee",
+    "forget_skill",
+    "frequency_down",
+    "frequency_up",
+    "full_heal",
+    "game",
+    "game_over",
+    "goto",
+    "halt_all_movement",
+    "inn",
+    "input_number",
+    "items",
+    "jump_end",
+    "jump_start",
+    "key_input",
+    "label",
+    "learn_skill",
+    "lock_facing",
+    "lock_screen",
+    "maniac",
+    "memorize_bgm",
+    "memorize_location",
+    "message_options",
+    "move",
+    "move_away_from_player",
+    "move_down",
+    "move_down_left",
+    "move_down_right",
+    "move_forward",
+    "move_left",
+    "move_random",
+    "move_right",
+    "move_toward_player",
+    "move_up",
+    "move_up_left",
+    "move_up_right",
+    "n",
+    "nv",
+    "nvv",
+    "open_load_menu",
+    "open_main_menu",
+    "open_save_menu",
+    "open_shop",
+    "open_video_options",
+    "page",
+    "pan_screen",
+    "party",
+    "pause",
+    "percent",
+    "phasing_off",
+    "phasing_on",
+    "pictures",
+    "play_bgm",
+    "play_memorized_bgm",
+    "play_movie",
+    "play_se",
+    "player",
+    "randint",
+    "recall_location",
+    "remove_battle_command",
+    "remove_state",
+    "remove_teleport_target",
+    "replace_tile",
+    "reset_screen_pan",
+    "return_to_title",
+    "route",
+    "set_battle_background",
+    "set_encounter_rate",
+    "set_escape_target",
+    "set_panorama",
+    "set_system_bgm",
+    "set_system_graphics",
+    "set_system_se",
+    "set_tileset",
+    "set_transition",
+    "set_vehicle_location",
+    "shake_screen",
+    "ship",
+    "show_battle_animation",
+    "show_choices",
+    "show_screen",
+    "simulate_attack",
+    "speed_down",
+    "speed_up",
+    "start_animation",
+    "start_battle",
+    "started_by_action_key",
+    "stop_animation",
+    "swap_events",
+    "switch_off",
+    "switch_on",
+    "teleport",
+    "terrain_id",
+    "text",
+    "this",
+    "timer1",
+    "timer2",
+    "tint_screen",
+    "toggle_atb_mode",
+    "toggle_fullscreen",
+    "toggle_vehicle",
+    "transparency_down",
+    "transparency_up",
+    "troop",
+    "turn",
+    "turn_around",
+    "turn_left",
+    "turn_random",
+    "turn_right",
+    "unequip",
+    "unlock_facing",
+    "unlock_screen",
+    "v",
+    "vv",
+    "vvv",
+    "wait",
+    "wait_for_movement",
+    "weather",
+    "word",
+]