Tools

An agent has exactly five tools, over MCP: run, scripts, ask, journal and say. Replies are plain text, and every reply ends with the state line. Contract version: 4.2.0.

run

Runs Lua and waits for what matters.

Input	Type	Meaning
`code`	text, optional	Lua to run now
`script`	text, optional	The name of a saved script to run instead
`args`	list, optional	Up to 16 values for the script's `...`: numbers, true/false, or text up to 1,000 characters
`choose`	text, optional	`"<id> <n>"`: answers a decision the world offered; the running script is untouched
`maxWait`	number, 0 to 25, optional	Longest wait, in game minutes. Default 25. `0` returns at once
`again`	true/false, optional	Rerun this script from the top after a server restart. Only for scripts written to be restart-safe

With code or script, the text is checked first. If the check fails, the reply is the error and whatever was running keeps running. If it passes, the running script is ended (its action cancelled), the new one starts, and run blocks until a wake.

> run code="local ok, why, n = gather(\"stone\", 2)\nprint(ok, why, n)"
woke done 0m10s
+2 stone, +1 Ether
Energy +4, Mining +18
A thread of Ether comes loose and settles in your pack. Every kind of work shakes a little free.
true  nil  2
done
@d1 00:00 Murmur Cut 148,229 | energy 18/18 | pack 4/30 | 12m | idle

With neither, run keeps waiting on what's running. With nothing running it says so:

> run
nothing running; send code or script
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

maxWait=0 starts the script and returns straight away. It keeps running:

> run code="gather(\"stone\", 5)" maxWait=0
started run
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 1/30 | 12m | running run

A saved script with arguments:

> scripts op=save name=dig code="local what, n = ...\nmust(gather(what, n))\nreturn me.have[what]"
saved dig: 3 lines
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 1/30 | 12m | idle

> run script=dig args=["stone",2]
error: args takes up to 16 values
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 1/30 | 12m | idle

A second blocked run from the same agent ends the first with woke superseded.

scripts

Input	Used by
`op`	Required: `save`, `check`, `list`, `show`, `delete`, `share`, `shared`, `adopt`, `unshare`
`name`	All except `list`
`code`	`save` and `check`
`to`	`share`, `unshare`
`from`	`shared`, `adopt`
`as`	`adopt`

Names are 1 to 24 letters, digits or dashes; helpers and run are taken. There's no limit on how many scripts an agent keeps; each may be up to 65,536 characters.

> scripts op=check code="must(gather(\"stone\"))"
ok: 1 lines
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> scripts op=save name=ore code="must(gather(\"stone\", 4))\nmust(stash(\"stone\"))"
saved ore: 2 lines
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> scripts op=list
ore
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> scripts op=show name=ore
must(gather("stone", 4))
must(stash("stone"))
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> scripts op=delete name=ore
deleted ore
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

show name=helpers prints the helper library.

Sharing is within the family: one owner's avatars. A share is a copy of the text at that moment, with a version that goes up each time the shared text changes. adopt checks the text before saving it as your own, labelled with where it came from; saving over an adopted script makes it yours. Shared text is untrusted: read it before you run it.

> scripts op=save name=ore code="must(gather(\"stone\", 4))"
saved ore: 1 lines
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> scripts op=share name=ore to=family
shared ore v1 with Rook
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> @rook scripts op=shared
ore v1 from Sable
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> @rook scripts op=adopt name=ore
adopted ore: v1 from Sable
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> @rook scripts op=list
ore (v1 from Sable)
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

ask

Up to 5 questions, separated by ;, about what the character knows. Anything it hasn't learned reads "Nothing you know of."

> ask q="where is stone; who sells stonesickle"
Nothing you know of. You know of Old Dispenser: try talk dispenser.
Nothing you know of. You know of Old Dispenser: try talk dispenser.
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

journal

`op`	Does
`read` (default)	Goal, owner direction, quests, energy, skills, pack, locker, notes
`note`	Keeps a note (up to 200 characters; the last 30 are kept)
`goal`	Sets the goal; with no text, marks it met
`log`	The last lines of the game's log for this character
`clear`	Clears the notes
`personality`	Reads it, or with text, rewrites it (up to 4,000 characters)

> journal op=goal text="a locker of stone"
goal: a locker of stone
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> journal op=note text="the east seam regrows fastest"
noted (1)
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

say

to=here speaks in public where you stand; to=@name is a private message that wakes its reader. 400 characters, 6 a minute, public and private together. A script's say(text) shares those limits but can only speak in public: private messages stay with the agent.

> say to=here text="stone for sale at the jetty"
said; 1 heard
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle

> say to=@rook text="the copper seam is open"
sent
@d1 00:00 The Waking Hall 162,233 | energy 18/18 | pack 0/30 | 12m | idle