add_hotspot_interaction
Add an interaction event handler to a hotspot
LABSCO SUMMARY
It closes the last manual step of AI-assisted AGS work.
An agent can write door_Look() perfectly well; what it could not do was attach that function to the door inside a compiled room file. Every write tool takes an outputFile, so the safe pattern is built into the parameters instead of left to your discipline — and the batch tools exist because hotspot edits come in sets, not singles.
What it is
An editor for Adventure Game Studio compiled room files (.crm). AI tools already write AGS script text; this reads and writes the binary room data that connects those functions to hotspots, so the hookup step no longer has to happen by hand in the editor.
What you get
- read_room_data parses a .crm file into structured room data; list_room_blocks lists the blocks inside it
- export_room_block writes a block out to a file and import_room_block replaces one from a file
- get_room_hotspots extracts hotspot information; list_hotspot_interactions lists what is attached to one hotspot
- add_hotspot_interaction attaches an event handler function to a hotspot event; remove_hotspot_interaction takes one off
- modify_hotspot_properties changes name, script name and walk-to coordinates; update_hotspot_walkto_coordinates does it across several hotspots at once; batch_modify_hotspots applies multiple operations in a single call
- Hotspot handlers follow the AGS naming convention hotspot{id}_{event}, so a generated function like hotspot1_Look resolves at runtime
Requirements
Node.js 18 or newer; run it with npx ags-mcp-server over stdio. Windows, macOS and Linux. No credentials. It needs .crm files on paths it can read, and the editing tools take an outputFile rather than writing over the original in place. Reads and writes are pure Node with no external AGS binaries. Hotspots and blocks are what it edits today — room objects, walkable areas, regions and character spawn points are on the roadmap, not in the tool list.
Setup effort
One command — npx ags-mcp-server
USE CASES
01
Wiring a generated script function to a hotspot
Find the hotspot, then attach the handler for the event you want it to answer.
02
Auditing a room for missing interactions
Parse the room, list its hotspots, and see which events already have handlers.
03
Fixing walk-to coordinates across a whole room
Update them for several hotspots at once instead of one call per hotspot.
04
Working on a block outside the room file
Export the block, edit it elsewhere, and import it back into a new output file.
11 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
batch_modify_hotspots
Batch modify multiple hotspots in a single operation
export_room_block
Export a specific block from a .crm file
get_room_hotspots
Extract hotspot information from a room
import_room_block
Import/replace a block in a .crm file
list_hotspot_interactions
List all interactions for a specific hotspot
list_room_blocks
List all blocks in a .crm file
modify_hotspot_properties
Modify hotspot properties (name, script name, walk-to coordinates, etc.)
read_room_data
Parse a .crm file and return structured room data
remove_hotspot_interaction
Remove an interaction event handler from a hotspot
update_hotspot_walkto_coordinates
Update walk-to coordinates for multiple hotspots
BEFORE YOU INSTALL
What to know first
Tools you get
11 tools when we connected. Five hotspot tools, including remove_hotspot_interaction and modify_hotspot_properties, are available but missing from the documented tool list.
Requires
- Node.js 18+
- npm 7+
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 11 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx ags-mcp-serverMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"ags-server": {
"command": "npx",
"args": [
"ags-mcp-server"
]
}
}
}Cline
CLINE · JSON
{
"mcpServers": {
"ags-mcp-server": {
"command": "npx",
"args": [
"ags-mcp-server"
],
"type": "stdio"
}
}
}
