manage_map_event
Create, modify, or remove events on a map. Use presets for NPCs, chests, shops, doors, teleports, inns, bosses, and puzzle switches to quickly build interactive gameplay elements.
Instructions
Create, modify or remove events on a map; the map file is written immediately. action "create" without preset makes a low-level event at x/y (empty page unless pages given; add behavior later with add_command). action "create" WITH preset builds a complete, ready-to-play event: "npc" (2-page dialogue NPC: {name, dialogues[], characterName?, characterIndex?}), "chest" (one-time loot: {items: [{type: item|weapon|armor, id, amount}]} — IDs not validated, confirm with query_database), "teleport" (one-way walk-on transfer zone: {destMapId, destX, destY, trigger?} — destination not validated), "door" (action-button warp into another map, e.g. a house entrance: {destMapId, destX, destY, characterName?, characterIndex?, trigger?, lockedSwitchId?, lockedMessage?}; with lockedSwitchId it shows a "locked" message until that game switch is ON), "shop" ({goods: [[type 0=item/1=weapon/2=armor, id, priceType 0=standard/1=custom, price]]}), "inn" ({cost?} full-recovery flow with gold check), "boss" ({troopId} one-time battle, game over on loss), "puzzle_switch" ({switchX, switchY, doorX, doorY, gameSwitchId, switchName?, doorName?} creates TWO linked events). action "update" overwrites only fields on an event; action "convert" RE-PURPOSES an existing event in place — keeping its id, position, name and sprite but replacing its behaviour — via kind: "merchant" (a working shop; pass options.goods [[type,id,priceType,price]] or the friendly options.items [{type,id}], plus optional options.greeting), "inn" (options.cost? full-recovery flow with gold check), "sign" (options.text string or string[] read-only message); ideal for "turn this NPC into a merchant" without re-placing it; "delete" removes it permanently (DESTRUCTIVE); "add_command" appends one command before a page's terminator; "populate" scatters N events of a kind (npc/chest/boss) at random positions (walkability not checked — validate with query_map "ascii"). Returns the created/updated event(s) with ids. Fails with an error if the map (or event, for update/delete) does not exist.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Tile X position (0-based; create/presets except puzzle_switch) | |
| y | No | Tile Y position (0-based) | |
| cost | No | preset "inn": gold charged for a full recovery (default 50) | |
| kind | No | action "convert": what to turn the existing event into | |
| name | No | Event name shown in the editor | |
| opts | No | action "populate": overrides {name, troopId, x, y} | |
| count | No | action "populate": how many events (default 3) | |
| destX | No | preset "teleport"/"door": destination tile X (should be walkable) | |
| destY | No | preset "teleport"/"door": destination tile Y | |
| doorX | No | preset "puzzle_switch": door tile X | |
| doorY | No | preset "puzzle_switch": door tile Y | |
| goods | No | preset "shop": wares [[type, id, priceType, price]] — priceType 1 uses the custom price, 0 the database price | |
| items | No | preset "chest": loot [{type: "item"|"weapon"|"armor", id, amount}] | |
| mapId | Yes | Map the event lives on (always required) | |
| pages | No | action "create" without preset: full event page objects (optional) | |
| action | Yes | What to do; see the tool description. Default "create" | |
| fields | No | action "update": properties to overwrite, e.g. {"x": 5, "y": 9} or {"pages": [...]} (replaces all pages) | |
| preset | No | action "create" only: ready-made event recipe; omit for a low-level empty event | |
| command | No | action "add_command": event command {code, indent, parameters}; e.g. 201=Transfer Player [0, mapId, x, y, dir, fade] | |
| eventId | No | Existing event ID (update/delete/add_command); find it with query_map view "events" | |
| options | No | action "convert": kind-specific settings — merchant {goods|items, greeting?}, inn {cost?}, sign {text} | |
| switchX | No | preset "puzzle_switch": floor-switch tile X | |
| switchY | No | preset "puzzle_switch": floor-switch tile Y | |
| trigger | No | How the event activates: 0=action button, 1=player touch, 2=event touch, 3=autorun, 4=parallel | |
| troopId | No | preset "boss" / populate boss: troop to battle (create it first via create_database_entry preset encounter_troop) | |
| doorName | No | preset "puzzle_switch": editor name for the door event (default "Door") | |
| destMapId | No | preset "teleport"/"door": destination map ID | |
| dialogues | No | preset "npc": dialogue lines, each becomes one text box | |
| eventType | No | action "populate": kind of events to scatter — "npc", "chest" or "boss" | |
| pageIndex | No | action "add_command": which page receives the command (0-based, default 0) | |
| switchName | No | preset "puzzle_switch": editor name for the switch event (default "Switch") | |
| gameSwitchId | No | preset "puzzle_switch": game switch linking switch and door — pick an unused ID via manage_system get switches | |
| characterName | No | Sprite sheet from img/characters/ without extension; list options with get_project_context | |
| lockedMessage | No | preset "door": message shown while locked (default "It's locked.") | |
| characterIndex | No | Which of the 8 characters in the sheet (0-7) | |
| lockedSwitchId | No | preset "door": if set, the door shows lockedMessage until this game switch is ON, then warps |