asterobot:gamedata

asterobot:gamedata reads the texts and the data of the game version the bot uses: items, monsters, maps, spells and everything else Asterobot extracts from the game files. It only reads. Game data overview, Lookups and SQL show how to use it.

import { text, record, table, find, search, query } from "asterobot:gamedata";

These are the module's only exports. There's no gamedata object to import.

What the data is

The data comes from the game version the bot is set to. text() and search() answer in the language the script was started with, session.language, which is fr for every start made from Asteroboard today.

Asterobot looks for the data when the script starts. When that game version has no extracted game data at that moment, record() returns undefined, and table(), find(), search() and query() resolve with undefined rather than an array, until the script starts again after the data is extracted. When Asterobot can't load the game's texts in that language, text() returns undefined for every key. Extract game data explains how to get the data.

Table and column names, such as monsters or name_id, are the ones of the extracted data, and they can change between game versions. Browse them on the Game page's game data (see Game data), and try queries in the SQL tab.

In the rows these functions return, numbers are regular JavaScript numbers, not BigInt. A packed column arrives as an array of objects, and a JSON column as the value it holds. record(), table() and find() leave empty columns out of their objects.

table(), find(), search() and query() share these rules:

• They reject after 30 seconds, and there's no option to change that.
• Each call counts as one of the 32 operations a script can have pending at once, along with send() and request(). Past that, the promise rejects with behavior resource limit exceeded: maximum pending operations reached.
• limit defaults to 200 rows and can't go above 5000. A limit or offset that isn't a whole number greater than 0 is ignored.

text()

text(key) returns a string, or undefined.

It returns the text in the script's language, or undefined when no text has that id or key.

When the game's texts are loaded, text() throws a TypeError with gamedata.text key must be a string or integer for any other key: a fraction, a number outside the 32-bit range, a BigInt, undefined or an object. Check a value exists before passing it.

record()

record(table, id) returns an object, or undefined.

It returns the row with that id, or undefined when there's none.

const monster = record("monsters", 31);
if (monster) botInfo("Monster 31 is", text(monster.name_id));

table()

table(name, options?) returns Promise<object[]>.

It resolves with the rows, in the order of their ids. A call without options returns the first 200 rows, not the whole table.

The promise rejects with gamedata.table name must be a non-empty string when name isn't a non-empty string, and with datacenter: no such table: "<name>" for a table this game version doesn't have.

const page = await table("items", { limit: 50, offset: 100 });

find()

find(name, filter, options?) returns Promise<object[]>.

const spots = await find("maps__interactive_elements", { gfx_id: 1018 });

search()

search(query, options?) returns Promise<Match[]>.

Each word of query matches the beginning of a word, so a partial name works. Shorter names come first. Without options.table, the results take one match from each table in turn, so the first results show every kind of thing that has that name. A query made only of spaces resolves with an empty array.

const [hit] = await search("Bouftou Royal", { table: "monsters" });
if (hit) botInfo(hit.name, "is monster", hit.id);

query()

query(sql, params?, options?) returns Promise<QueryResult>.

The game data is opened read-only, so any statement that writes fails, and attaching another database is refused. Every statement in sql runs, and the result is the last one's: "SELECT 1; SELECT 2" answers 2. A query runs for at most 10 seconds, and its text can't be longer than 65,536 bytes.

Pass values through params instead of writing them into the SQL: a number written into the text arrives as text, and doesn't equal the number stored in a column.

In rows, an empty value is null.

The promise also rejects when the query runs for more than 10 seconds.

const { columns, rows, truncated } = await query(
  "SELECT _id, name_id FROM monsters WHERE _id = ?",
  [31],
);

Types