API reference

Functions live under nexSys.api, grouped by area. Questions and actions for an area sit together: nexSys.api.affs.have() and nexSys.api.affs.setPriority() are neighbours. Data lives separately under nexSys.state.

nexSys.api.affs.have("asthma"); // ask a question
nexSys.api.defs.defup(); // do something
nexSys.api.queue.free.add("touch tree"); // use a queue

Namespace	Area
`api.affs`	Afflictions: checks, timing, priorities
`api.defs`	Defences: checks, priorities, defup
`api.balances`	Balances and cooldowns
`api.trackables`	Tracked effects such as snap
`api.limbs`	Limb damage
`api.room`	Room walls, frozen ground, and items
`api.target`	Your target
`api.class`	Your class
`api.command`	Sending commands
`api.queue`	Command queues
`api.control`	Pausing, settings, and diagnostics
`api.ss`	Server-side curing extras and the curing set
`api.rules`	Rules
`api.prompt`	The custom prompt
`api.observe`	Telling nexSys about things it can't see
`api.ui`	The configuration window
`api.line`	Changing game lines from triggers

Questions return true or false. Timing and lookup functions return null for names nexSys doesn't know. Most actions return true when they changed something. An action that talks to the game returns as soon as the command is sent, not when the game confirms it. Use state and events to see the confirmed result.

`api.affs`

Function	Returns
`have(name)`	Whether you have the affliction
`haveAll(names)` / `haveAny(names)`	Whether you have every one, or any one. Takes an array or a single name.
`elapsedMs(name)` / `elapsedSeconds(name)`	Time since the affliction was gained or lost
`remainingMs(name)` / `remainingSeconds(name)`	Time until a timed affliction wears off, or `0`
`timing(name)`	`{ have, sinceMs, lastChangeAtMs, elapsedMs, timedDurationMs, remainingMs, ... }`
`setPriority(name, priority)`	Set the priority for this session.
`setDefaultPriority(name, priority)`	Change your default priority.
`resetPriority(name)`	Return a session priority to your default.
`resetAllPriorities()`	Return every affliction to its default.

Priorities run from 1 (most urgent) to 25. 0 or 26 ignores the affliction. Changes apply to server-side curing at the next prompt.

setDefaultPriority() changes the default straight away, but it's stored the next time your configuration is saved, for example with Save in the configuration window or with nexSys.api.control.applySettings(). Until then, it lasts for the session.

`api.defs`

Function	Returns
`have(name)` / `haveAll(names)` / `haveAny(names)`	Whether the defence (or defences) are up
`setPriority(name, priority)`	Set the priority for this session. `0` stops nexSys raising it.
`setDefaultPriority(name, priority)`	Change your default priority. Stored when your configuration is next saved, as for afflictions.
`setStatic(name, isDefup)`	Mark a defence Defup (`true`) or keep-up (`false`).
`setCommand(name, command)`	Change the command used to raise a defence for this session, such as `"block n"`.
`resetPriority(name)` / `resetAllPriorities()`	Return session priorities to your defaults.
`defup()`	Raise your defences, as the `defup` alias does.
`defoff()`	Lower your defences, as the `defoff` alias does.
`parry(limb)`	Parry (or guard) a limb and keep parrying it. Takes a code such as `"rl"` or a name such as `"right leg"`.

`api.balances`

Balance names include balance, equilibrium, herb, salve, smoke, focus, tree, sip, moss, and class cooldowns. See state.balances.

Function	Returns
`have(name)` / `haveAll(names)` / `haveAny(names)`	Whether the balance (or balances) are available
`elapsedMs(name)` / `elapsedSeconds(name)`	Time since the balance was used or recovered
`remainingMs(name)` / `remainingSeconds(name)`	Time until a used balance is expected back, or `0`
`timing(name)`	Full timing, including whether the game reported the length (`activeDurationReported`)

`api.trackables`

Function	Returns
`get(name)`	The record, or `null`
`list()`	Every trackable name, such as `["snapTrack"]`
`have(name)`	Whether it's active
`elapsedMs(name)`	Time since it started, or `Infinity` when inactive
`remainingMs(name)`	Time until it ends, or `0` when inactive
`timing(name)`	Full timing

To start or end one, use api.observe.trackables.

`api.limbs`

Function	Returns
`get(limb)`	A limb record by id (`"leftleg"`) or name (`"left leg"`), or `null`
`list()`	`["head", "torso", "leftarm", "rightarm", "leftleg", "rightleg"]`

`api.room`

Function	Returns
`get()`	The current room. The same as `state.room`.
`isGroundFrozen()`	Whether the ground is known to be frozen
`walls.get(direction)`	The walls at an exit, such as `[{ type: "icewall" }]`. Takes `"n"` or `"north"`.
`walls.list()`	Every wall, as `{ direction, type }`
`walls.have(direction, type?)`	Whether there's a wall at an exit, optionally of a given type
`items.have(name)`	Whether an item with exactly this name is in the room
`items.isKnown()`	Whether nexSys has a complete, current list of the room's items

items.have() returns false when the room's items aren't known yet, so check items.isKnown() when that matters.

`api.target`

Function	Returns
`get()`	Your target: `{ id, text, isPlayer, hp }`
`set(name)`	Sends `SETTARGET <name>`. Returns `{ target, dispatched, dispatchResult }`. `state.target` updates when the game confirms.
`is(name)`	Whether this is your current target

`api.class`

Function	Returns
`get()`	Your class, such as `"Occultist"`
`is(classes)`	Whether you're in this class, or in any class of an array, such as `is(["Dragon", "Magi"])`
`check(name)`	Whether you're in this one class

Class names aren't case-sensitive, and any colour of dragon counts as "Dragon".

`api.command`

Function	Does
`send(command, raw?)`	Send a command now. Pass `true` as the second argument to skip Nexus alias expansion.
`sendInline(commands, context?)`	Send several commands together in one batch.
`addOutput(commands)`	Add commands to nexSys's next output batch.
`evaluateNow()`	Run nexSys's output cycle now instead of waiting for the next prompt.

nexSys.api.command.send("stand");
nexSys.api.command.send("block n", true); // don't expand as an alias

`api.queue`

Each queue has a handle under its name and its id: queue.free and queue.freeQueue are the same. The queues are class, free, full, shield, ship, bloodcloak, battlerage, and stun. See Queues.

Handle method	Does
`add(commands, options?)`	Add commands to the end. Commands already queued are skipped unless `{ allowDuplicate: true }`.
`prepend(commands, options?)`	Add commands to the front.
`addClear(commands, options?)`	Replace your queued commands, keeping the front ones.
`clear()`	Empty nexSys's copy of the queue only.
`clearQueue()`	Empty nexSys's copy and the game's queue.
`flush(options?)`	Send the queue to the game now. `{ force: true }` sends even if nothing changed.
`isQueued(command)`	Whether a command is in the queue
`inspect()`	The queue's current contents

commands is a string or an array of strings. Adding sends the queue to the game straight away unless you pass { autoFlush: false }.

The same methods are available at the top level with the queue as the first argument, such as queue.add("free", "touch tree"). The top level also has list() for the queue ids, get(queue) for a handle, and flushAll().

`api.control`

Function	Does
`pause()` / `unpause()` / `pauseToggle()`	Pause or resume nexSys, as `pp` does.
`setSlowMode(on)` / `slowOn()` / `slowOff()`	Turn slow mode on or off. Aeon turns it on by itself.
`applySettings(changes)`	Change settings, save your configuration, and apply it.
`setDebug(on)` / `debugOn()` / `debugOff()`	Turn diagnostic logging on or off.
`debug()`	A diagnostic snapshot for bug reports
`start()` / `stop()`	Start or stop the runtime. Normal loading does this for you.
`updateNxs()`	Download and apply the latest nexSys4 package now. This also happens at every load.

applySettings() merges your changes into the current settings. Setting names are listed in the State reference:

nexSys.api.control.applySettings({
  queueWhilePaused: true,
  ss: { sipHealthAt: 70, batch: false },
});

It saves your whole configuration, including priorities and precache amounts changed by scripts.

`api.ss`

Function	Does
`predictions.add(aff)` / `predictions.remove(aff)`	Ask for, or cancel, a `CURING PREDICT`.
`prioAff.set(aff)` / `prioAff.reset()`	Set or clear `CURING PRIOAFF`.
`queue.add(cure)` / `queue.insert(index, cure)` / `queue.remove(cure)` / `queue.clear()`	Manage the manual curing queue (`CURING QUEUE`).
`precache.set(amounts)`	Change and save precache amounts, such as `{ kelp: 5, aurum: 3 }`.
`syncSnapshots()`	Read curing status and priorities from the game again.
`startupStatus()`	Which startup readings have arrived.
`unload(options?)`	Leave nexSys's curing set: switch back to your previous set and delete `nexsys4-default`. Pass `{ remove: false }` to keep the set.

The game uses up a prioaff and queued cures without telling nexSys, so clear them when you're done. See Curing and priorities.

`api.rules`

Function	Does
`add(rule, options?)`	Add a rule. `{ index }` puts it at a position. Returns `false` if the id is taken.
`remove(id)`	Remove a rule.
`enable(id)` / `disable(id)`	Switch a rule on or off.
`enablePack(packId)` / `disablePack(packId)`	Switch every rule in a pack on or off.
`load(packId, rules)` / `unload(packId)`	Add or remove a pack of rules.
`reorder(ids)`	Set the order of every rule.
`list()`	Every rule: `{ id, ruleOrder, enabled, terminal, isActive, suspendsCuring, pack, tags, meta }`
`bindTransition(id, { onActivate, onDeactivate })`	Run code when a rule switches on or off. Returns a function that stops listening.

The rule format and the helpers a rule can use are described in Rules.

`api.prompt`

Member	Does
`set(layout)`	Replace the prompt layout with your own function.
`reset()`	Go back to the standard layout.
`updateAffs(changes)`	Change affliction abbreviations and colors. `null` removes an entry.
`updateCureColors(changes)`	Change the cure color palette.
`updateVars(changes)`	Change prompt values' colors, or add your own values.
`vars` / `affs` / `cureColors`	The current values
`enabled`	Read or set the Custom Prompt setting.
`colorGradation(percent)`	The green-to-red color nexSys uses for a percentage

See Custom prompt.

`api.observe`

Tells nexSys about things it can't see for itself, such as an affliction message it doesn't recognize. Calls go through the same path as nexSys's own triggers, so state, events, and curing all update.

Function	Does
`affs.<name>.got()` / `affs.<name>.lost()`	You gained, or were cured of, an affliction.
`defs.<name>.got()` / `defs.<name>.lost()`	A defence went up or down.
`balances.<name>.got()` / `balances.<name>.lost()`	A balance came back or was used.
`balances.<name>.used(seconds)`	A balance was used for a known number of seconds.
`limbs.hit(limb, amount)` / `limbs.reset(limb)` / `limbs.setStage(limb, stage)`	Limb damage changed. Each limb also has its own handle, such as `limbs.torso.hit(amount)`.
`trackables.got(name, options?)` / `trackables.lost(name)`	Start or end a tracked effect. New names need `{ durationMs }`.
`mount.set({ name, id })` / `mount.reset()`	You mounted or dismounted.
`room.walls.got(direction, type)` / `room.walls.lost(direction, type)`	A wall appeared or disappeared.
`room.frozenGround.got()` / `room.frozenGround.lost()`	The ground froze or thawed.

For example, in a trigger on an affliction line nexSys misses:

nexSys.api.observe.affs.asthma.got();

Each function returns true if it changed anything.

`api.ui`

Function	Does
`openConfig()`	Open the configuration window, as `ns config` does.
`closeConfig()`	Close it.
`setConfigOpen(open)`	Open (`true`) or close (`false`) it.

`api.line`

Helpers for Nexus trigger scripts that change the current line of game output:

Function	Does
`replace(text, fg, bg, ...)`	Replace the line with colored text. Repeat the three arguments for more chunks.
`replaceHTML(html)`	Replace the line with HTML you trust.
`replaceWord(word, replacement, fg?, bg?)`	Replace a word in the line.
`replaceWordHTML(word, html)`	Replace a word with HTML you trust.
`prevLine(pattern)` / `nextLine(pattern)`	Whether the line before or after matches a string or regular expression
`checkLine(pattern, offset)`	Whether the line `offset` lines away matches
`prependNotice(text, fg, bg, ...)`	Add a line before the current block.
`say(text)`	Speak text aloud with the browser's speech synthesis.

`nexSys.events`

nexSys.events is nexSys's own event bus. It carries the EventStream events plus some JavaScript-only ones, which are listed in All event topics.

Member	Does
`on(topic, listener)`	Listen to a topic. Returns a function that stops listening.
`off(topic, listener)`	Stop listening.
`topics`	Every topic name, keyed in capitals, such as `topics.AFF_GOT` for `"nexsys4.aff.got"`.

const stop = nexSys.events.on("nexsys4.system.settings.changed", (payload) => {
  // settings changed
});

Packages should normally listen through the Nexus eventStream instead. See Events.

api.affs​

api.defs​

api.balances​

api.trackables​

api.limbs​

api.room​

api.target​

api.class​

api.command​

api.queue​

api.control​

api.ss​

api.rules​

api.prompt​

api.observe​

api.ui​

api.line​

nexSys.events​