Function Reference
Every function a script can call. A function marked
waits pauses the script until the game has an answer; the
rest return at once. A function that can fail returns false
and a reason, which expect() turns into a stop.
Information
These answer at once from what your client knows. Each call returns a fresh snapshot; a table you kept from an earlier call does not update.
| Function | Returns |
|---|---|
me() | You — fields below. |
pets() | Your pet list, in order — fields below. |
items() | Your bag — fields below. |
itemCount(name[, creator]) | How many of that item
you carry, across every stack. With creator, only items
made by that character. |
skills() | Your kungfu — fields below. |
team() | Your team, or nil:
leader (id), size, isLeader,
members (list of ids). |
npcs() | Every NPC on your map: id,
name, type, x, y,
monster (true for a monster you can fight). |
players() | The other characters in view:
id, name, level, x,
y, spouse. |
dialogue() | The open NPC dialogue, or
nil — fields below. |
inBattle() | true during a fight. |
mapName(id) | A map's name. |
recentChat([n]) | The last n system
lines (default 10), oldest first. |
now() | Milliseconds since the game started — subtract two readings to time something. |
localTime() | Your computer's date and time:
year, month, day,
hour, min, sec and
wday (1 is Sunday). For anything that starts over at
midnight. The server keeps its own clock, which matches only when
you share its time zone. |
me()
| Field | Meaning |
|---|---|
id, name | Your character. |
map, x, y | Where you stand. |
level, rank, reborns |
Level, rank and times reborn. |
life, maxLife, mana,
maxMana | Current and full. |
money | Cash carried. |
thievery, kungfuExp,
petRaisingExp, wuxingExp,
reputation, virtue |
Your experience figures. kungfuExp is the Kungfu
stat. |
pk | true while you are in the
Martial Circle. |
petCount | Pets in your list (five at most). |
inTeam, isLeader | Team membership. |
spouse | Your spouse's name, or "". |
outOfMedicine | true once after a
fight needed medicine you did not have. Reading it clears it. |
pets()
For a pet's attack, defence and dexterity, whether it can evolve, and its element, see Pet stats.
Each pet: id, name, species,
level, exp, loyalty,
growth, life, maxLife, and
marching (true for the marching pet).
growth is what the pet has actually gained per level so far,
as the Pet window shows it — 0 for a pet still at level 1. The growth
rate a pet was born or awarded with is not sent to the game client, so a
script cannot read it.
items()
Each stack: id (this item, for the functions below),
name, count, creator,
sort (its kind — 700 is medicine), life and
mana (what it restores), cost and
level.
skills()
Each kungfu: id, name, inventor,
level, exp, mana (its cost),
coef (its destructive index), and slot — its
place in the battle loadout, or 0 when it is not carried.
Dialogues
A dialogue table, from dialogue(), talk(),
waitDialogue(), fight() or an answer's outcome,
has text (what the NPC said, a list of lines),
options (the answers on offer, a list of strings),
npc (the NPC the script last talked to) and gen,
which is different for every dialogue that opens — even two with the
same words.
Your stats and attribute points
| Function | Waits | What it does |
|---|---|---|
playerStats() | Your attack, defence and dexterity, and the points you have put into each attribute — fields below. | |
freePoints() | How many attribute points you have not spent yet. | |
spendPoints{...} | waits | Spends free points, all in one go, the way the Character window's
Apply does. Name the attributes and how many points each gets:
life, mana, attack,
defence, dexterity; any you leave out get
none. Returns true, or false and a reason:
more points than you have, a negative amount (points never come back
out), or nothing to spend. A misspelt attribute, such as
atk, stops the script with an error rather than spend
nothing quietly. |
playerStats()
| Field | Meaning |
|---|---|
attack, defence, dexterity |
What you fight with: your points in that attribute plus everything you are wearing. These are the figures the Character window shows. |
points |
What you have put into each attribute, without equipment:
points.life, points.mana,
points.attack, points.defence,
points.dexterity. |
-- Spend every free point: two into attack for each one into defence.
local free = freePoints()
if free > 0 then
local defence = free // 3
expect(spendPoints{ attack = free - defence, defence = defence })
end
local s = playerStats()
log("attack " .. s.attack .. " (" .. s.points.attack .. " from points)")
Pet stats, evolution and element
Each takes a pet's id from pets(), and returns
false, "no such pet" for a pet that is not in your list.
| Function | Returns |
|---|---|
petStats(petId) |
The pet's attack, defence and
dexterity, and its medals: how many it holds
of each, 0 to 5 (medals.attack,
medals.defence, medals.dexterity). |
petEvolution(petId) |
What the pet can still become — one of three answers, below. |
petElement(petId) |
"Water", "Fire", "Metal",
"Wood" or "Earth". |
A fight uses the pet's own attack, defence and dexterity — the three
figures petStats gives. Its medals and its accessory are not
added to them in a fight; the accessory matters when the pet is
composed.
petEvolution()
| Answer | Means |
|---|---|
"evolving", stage |
An evolving pet, with a second value for how far along its line it is: 0 for the base form, 1 for stage 1, 2 for stage 2. A stage-2 pet's next evolution is its final one, to the super form, which not every line has. |
"super" |
A super form: the last form of its line. It evolves no further. |
"none" |
A pet that never evolves: the wild pets, the mutant bats and lizards, and a few unusual breeds such as the Seahorse Pawn and the Snow Wolf. |
for _, p in ipairs(pets()) do
local kind, stage = petEvolution(p.id)
if kind == "evolving" and stage < 2 and petElement(p.id) == "Water" then
log(p.name .. " can evolve to stage " .. (stage + 1))
end
end
Output and control
| Function | What it does |
|---|---|
log(...) | Writes a line to chat and the Script
window's log. print does the same. |
status(...) | Sets the status line in the Script
window and /script status. |
stop([reason]) | Ends the script. |
expect(ok, why, ...) | When ok is
true, returns all its arguments unchanged. Otherwise ends the script
with why. Wrapped round a call that returns
false, reason, the reason becomes the message. |
Moving
| Function | Waits | What it does |
|---|---|---|
travel(map[, x, y]) | waits | Goes anywhere Auto-travel can reach, paying fares and talking to
the NPCs on the way. Returns true, or
false and a reason — "dialogue"
when an NPC spoke up on the way; read it with
dialogue(). |
walk(x, y) | waits | Walks to a tile on this map. |
NPCs
| Function | Waits | What it does |
|---|---|---|
talk(npc) | waits | Talks to an NPC on this map, by id or name, walking closer first if
it is more than six tiles away. Returns the dialogue, or
{shop = true}, {battle = true} or
{map = id} when the NPC does that instead. Fails with
"refused", or "no answer" after five
seconds. |
answer(choice) | waits | Picks an answer by its text or its number (1 is the first). Returns what happened — see Talking to NPCs for the fields. Fails, listing the answers on offer, when nothing matches or more than one does. |
closeDialogue() | Takes the dialogue off your screen without telling the NPC anything. | |
closeShop() | Closes any shop window. |
Waiting
Times are in milliseconds. These clocks stop while a fight is on.
| Function | Returns |
|---|---|
sleep(ms) | true when the time is
up. |
waitDialogue([ms]) | The open dialogue, or the next one to open. Default limit 5 seconds. |
waitChat(pattern[, ms]) | The next system line that matches a Lua pattern. Default limit 5 seconds. |
waitMap([map][, ms]) | true once you
stand on that map (at once if you already do), or with no map, at the
next map change. Default limit 10 seconds. |
Each returns false, "timeout" when its limit runs out.
Fighting
| Function | Waits | What it does |
|---|---|---|
fight() | waits | Waits for the fight that is starting, or already on, to end.
Returns "won", "lost" or
"fled" — or "unknown" if the fight
vanished, as on a disconnect — then the dialogue the NPC
opened afterwards, or nil. Fails with
"no battle started" when none starts within 8
seconds. |
battlePolicy{...} | Changes how the script's fights are played, for the rest of the run.
Every field is optional:
| |
grind{battles = n} | waits | Fights wild monsters where you stand, by the battle plan, until
n fights are done. Restocks and returns like
Battlemation. Returns true and
{battles = , catches = }, or false and why
it stopped early. |
grind{capture = {...}} | waits | The same, catching instead: name (the species, exactly),
level, maxLevel (leave it out to accept only
level) and count (how many to catch,
default 1). Needs room in your pet list. |
follow{...} | For a team member who is not the leader: fights the leader's fights
by the battle plan and heals between them, while the script carries
on with other things. leavePartyWhenDry = true leaves the
team when the medicine runs out. Returns true, or
false and a reason. | |
unfollow(), following() | Stop following; whether following is on. |
Items and pets
An item can be named by its id from items(), or by
its name, which uses the first stack of that name.
| Function | Waits | What it does |
|---|---|---|
useItem(item) | waits | Uses it on yourself: a potion, a scroll, equipment. |
feedPet(petId, item) | waits | Uses it on a pet. |
dropItem(item[, count]) | waits | Drops it,
the whole stack unless count says otherwise. |
buy(map, itemName[, qty]) | waits | Goes to that map, finds the shop that sells the item, and buys up
to qty (default 1) — fewer if money or the stack
limit runs short. Something that does not stack is bought one at a
time. Returns how many arrived. A shopkeeper who opens
his shop from his dialogue (Seer Wang) is bought from once that
window is open: answer him first, then call buy. |
sell(item[, count]) | waits | Sells to the
shop you last visited. Visit one first with buy or
talk. |
setMarching(petId) | waits | Makes that pet the marching one. Whenever nothing is marching, the game marches the previous pet again, or failing that your highest-level pet, on its own. |
stablePet(petId[, map]) | waits | Takes the pet to a pet stable and leaves it there — by default the stable set in Battlemation. Not the marching pet. |
stabledPets([map]) | waits | Goes to that
pet stable and returns what it holds: a list of pets, each with
id, name, species and
level, and the stable's size as a second result. |
withdrawPet(petId[, map]) | waits | Takes that pet out of the stable and back into your pet list. Free, but the list needs a free place. |
sellPet(petId[, map]) | waits | Sells the
pet to a Pet Breeder for the price the pet shop quotes, and returns
true and the taels paid. Uses the breeder on the map you
are on if there is one, otherwise goes to map — by
default the stable set in Battlemation. Not the marching pet. |
dropPet(petId) | waits | Lets the pet go for good, as Drop in the pet list does. Anything it wears goes with it. Not the marching pet. |
Each returns true (or a count) when it worked, and
false and a reason when it did not. Every pet shop keeps its
own stable: a pet left at the Water Pet Shop is only listed there. The
stables are at the Water, Tree, Mountain and Sand Pet Shops; the Snow Pet
Shop has none.
Pawnshop deposit box
Each pawnshop clerk keeps a deposit box for you of 64 items: in the Water,
Tree, Mountain and Sand Pawnshops. These go to the pawnshop on
map and walk up to the clerk first.
| Function | Waits | What it does |
|---|---|---|
pawnshopItems(map) | waits | Returns what
your box there holds: a list of items, each with id,
name, creator and count, and the
box's size as a second result. |
depositItem(itemId, map) | waits | Leaves
that bag item in the box. It costs the item's price divided by 100,
never less than 1,000 taels or more than 10,000. Quest items, the ones
with a * in their name, cannot be stored. |
withdrawItem(itemId, map) | waits | Takes that item out of the box into your bag, which needs a free slot. Returns the item's id in the bag: a new id, not the one the box listed. |
A refusal returns false and the pawnshop's own words, for
example the pawnshop refused: This deposit box is full.
Kungfu
| Function | Waits | What it does |
|---|---|---|
createKungfu{...} | waits | Attempts a new move: name (1–15 characters,
English letters, digits, spaces and punctuation), look 0–7, trace
0–18, blast 0–19, coef
0.01–2.00 and mana, with coef ×
mana no more than 2,000. Needs full mana and a free slot.
Returns "created" and the new move's id,
"failed" when the attempt came to nothing, or
false and the server's reason. |
forgetKungfu(id) | waits | Forgets a move for good. |
selectSkill(id[, on]) | waits | Puts a move
into the battle loadout (five at most), or takes it out with
on = false. Only loadout moves can be cast. |
Teams
| Function | Waits | What it does |
|---|---|---|
createTeam() | waits | Makes a team led by you; succeeds at once if you lead one already. |
joinTeam(name) | waits | Joins the team that character leads. They must be in view. Joining is immediate unless the leader has locked the team. |
leaveTeam() | waits | Leaves the team, or breaks it up if you lead it. |
waitTeam(n[, ms]) | waits | Until your team
has at least n members. Default limit one minute. |
The script itself
| Name | What it is |
|---|---|
script{...} | The header: name,
description, settings. See
Writing a Script. |
main(cfg) | Your function. Called once with the settings; the script ends when it returns. |
import(name) | One of the game's helper modules,
common or passes. |
load(text) | Lua's own load, for
source text only. |
remember(key, value) | Keeps a value for the
next time this script runs, for this character. Keys are letters,
digits, _ and .; values one line of up to 256
characters. remember(key, nil) forgets. |
recall(key) | What was remembered under that key,
as a string, or nil. Use tonumber on a
number. |