Monster & Me

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.

FunctionReturns
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()

FieldMeaning
id, nameYour character.
map, x, yWhere you stand.
level, rank, reborns Level, rank and times reborn.
life, maxLife, mana, maxManaCurrent and full.
moneyCash carried.
thievery, kungfuExp, petRaisingExp, wuxingExp, reputation, virtue Your experience figures. kungfuExp is the Kungfu stat.
pktrue while you are in the Martial Circle.
petCountPets in your list (five at most).
inTeam, isLeaderTeam membership.
spouseYour spouse's name, or "".
outOfMedicinetrue 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

FunctionWaitsWhat 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()

FieldMeaning
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.

FunctionReturns
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()

AnswerMeans
"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

FunctionWhat 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

FunctionWaitsWhat 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)waitsWalks to a tile on this map.

NPCs

FunctionWaitsWhat 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.

FunctionReturns
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

FunctionWaitsWhat 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:
  • player — "attack", "defend" or "kungfu";
  • pet — "attack" or "defend";
  • skill — the kungfu id to cast; 0 means the first in your battle loadout;
  • healPlayer, healPet — heal below this percentage of life;
  • levelAtFull — keep a pet that this fight will level at full life, so it levels at full health;
  • medicine — the item type number of the preferred medicine.
Returns the plan now in force, as a table with the same fields.
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.

FunctionWaitsWhat it does
useItem(item)waitsUses it on yourself: a potion, a scroll, equipment.
feedPet(petId, item)waitsUses it on a pet.
dropItem(item[, count])waitsDrops 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])waitsSells to the shop you last visited. Visit one first with buy or talk.
setMarching(petId)waitsMakes 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])waitsTakes the pet to a pet stable and leaves it there — by default the stable set in Battlemation. Not the marching pet.
stabledPets([map])waitsGoes 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])waitsTakes that pet out of the stable and back into your pet list. Free, but the list needs a free place.
sellPet(petId[, map])waitsSells 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)waitsLets 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.

FunctionWaitsWhat it does
pawnshopItems(map)waitsReturns 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)waitsLeaves 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)waitsTakes 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

FunctionWaitsWhat 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)waitsForgets a move for good.
selectSkill(id[, on])waitsPuts a move into the battle loadout (five at most), or takes it out with on = false. Only loadout moves can be cast.

Teams

FunctionWaitsWhat it does
createTeam()waitsMakes a team led by you; succeeds at once if you lead one already.
joinTeam(name)waitsJoins the team that character leads. They must be in view. Joining is immediate unless the leader has locked the team.
leaveTeam()waitsLeaves the team, or breaks it up if you lead it.
waitTeam(n[, ms])waitsUntil your team has at least n members. Default limit one minute.

The script itself

NameWhat 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.