Verbs

How every verb behaves

Actions take game time; the script pauses until the action is done and then carries on in the same tick. Sensing answers at once and costs nothing. Control words shape the script itself.

Every action returns ok, why, n:

• ok is true when everything asked was done.
• why is nil on success, or one word from the list below.
• n is how many were done: gathered, made, moved, bought, sold. For verbs that aren't counted it's 1 on success and 0 on failure.

The full failure text (fail gather stone: every stone patch is spent; ... and its need: line) goes into the reply too, so the agent reads the detail when it wakes. Scripts branch on why.

A world reason never raises an error. Errors are only for programming mistakes, and they end the script with a line number: see Replies and errors.

Names match loosely against what the character knows: "stone", "Waking Hall", "custodian". A name you haven't learned and one that doesn't exist read the same: false, "unknown".

Walking is part of every action that happens somewhere: 2 tiles a tick on open ground, 4 on a road. Nobody needs go before gather, make, stash, buy or talk.

Counts, never conditions

The second argument of gather, make, buy, stash, take and sell is always a count: a whole number of 1 or more, or "all". gather, make and buy default to 1; stash, take and sell default to all.

To stop on a condition, loop:

while me.have.stone < 8 do must(gather("stone")) end

A condition in the count position is an error with the fix in it:

gather("stone", me.have.stone < 8)
-- => error run line 1: gather's second argument is a count: a number or "all".
-- => To stop on a condition, loop: while not me.full do must(gather("stone")) end

"all" succeeds whenever it stopped for its own reason, even when n is 0: a full pack for gather, take and buy, ingredients running out for make, nothing left for stash and sell. So stash("stone") with no stone is true, nil, 0, and make("stonecutter", "all") with no ingredients is true, nil, 0 plus a line saying what's missing. It fails only for other reasons, such as spent, tool, money or way. A counted call still fails when it falls short: stash("stone", 2) with none is false, "none", 0.

local ok, why, made = make("stonecutter", "all")
print("made", made, why)

Actions

go("Waking Hall")
gather("stone", 2)
gather("rustheap", "all")
make("stonecutter", 3)
stash("stone")
stash("all")
take("stone", 2)
buy("charcoal", 1, 20)
sell("scrap", "all", 1)
talk("custodian")
talk("custodian", "skills")
use("stonepickaxe")
rest(10)
wait(5)
say("anyone selling oak?")
fit("woodenlimb", "left leg")
remove("woodenlimb")
repair()

Combat and spells (fight, cast, flee_at) are deferred: see Known gaps.

Sensing

Free and instant. Only what the character knows: anything unknown reads nil, or 0 for a count.

me is a live, read-only view: each read answers from the world now.

print(me.energy, me.motes, me.place, me.full)
print(me.have.stone, me.locker.stone, me.level.mining)
for item, n in pairs(pack()) do print(item, n) end
local p = patches("stone")
if p and p.left == 0 then print("stone regrows in", p.next, "s") end
local here_now = here()
print(here_now.place, #here_now.npcs)
print(info("stonepickaxe").tool)
local b = body()
print(b.power.name, b.parts.torso.hp, b.parts.torso.max, me.hurt)
local t = time()
print("day", t.day, t.hour .. ":" .. t.minute)

Control

on(function() return me.full end, function()
  must(stash("all"))
end)
for i = 1, 3 do
  local ok, why = gather("stone", 10)
  if why == "spent" then alert("stone ran out") wait(30) end
end
mem.runs = (mem.runs or 0) + 1
return mem.runs