Персонажи, загруженные или нет
Модуль characters: найдите, прочитайте и измените любого персонажа через ai-core - деньги, работы, банды, метаданные, имя, время игры - с Promise в TypeScript и простым ожиданием в Lua.
import { characters } from "@aicore8/lib/server";-- aiLib.characters, после shared_script '@ai-lib/init.lua'characters - это дверь библиотеки к экспортам сохранённых персонажей ai-core. Он существует потому, что те экспорты отвечают через колбэк: библиотека превращает каждый в Promise в TypeScript и в простое ожидание в Lua, так что код читается сверху вниз.
- Персонаж называется своим id персонажа (
charId, число). Из citizenid:characters.idOf. - Загруженный персонаж отвечает из памяти (актуальные деньги и принадлежности); сохранённый читается из базы, пока ai-core его держит, поэтому он не загрузится посреди записи.
- Каждая запись отвечает ActionResult:
{ ok: true }или{ ok: false, error }с языковым ключом ai-core. - Каждая функция здесь ждёт. В Lua это значит вызывать её из потока; см. Функции, которые ждут.
Для игрока, о котором идёт речь, короче путь напрямую через ai-core: GetCharacter, money, jobs. Берите characters, когда цель может быть офлайн или когда нужен весь персонаж сразу.
characters
characters.idOf
Id персонажа за citizenid.
Сторона: Сервер · Ждёт: да
characters.idOf(citizenid: string): Promise<number | null>Двойника в Lua нет: вызовите экспорт GetCharIdByCitizenId у ai-core и дождитесь его колбэка.
Параметры
Prop
Type
Возвращает
Promise<number | null>: id персонажа или null, если ни у одного персонажа нет такого citizenid либо он удалён.
Пример
import { characters } from "@aicore8/lib/server";
/** Штраф, который работает, онлайн водитель или нет. */
export async function fine(citizenid: string, amount: number): Promise<boolean> {
const charId = await characters.idOf(citizenid);
if (charId === null) return false;
return (await characters.removeMoney(charId, "bank", amount, "Штраф")).ok;
}characters.get
Один персонаж со всем, что ai-core о нём хранит: данные, деньги по счетам, работы, банды, метаданные, сохранённая позиция, последнее сохранение и серверный id, когда он загружен.
Сторона: Сервер · Ждёт: да
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- таблица или nilПараметры
Prop
Type
Возвращает
OfflineCharacter или null / nil, если id неизвестен либо персонаж удалён.
Пример
import { characters } from "@aicore8/lib/server";
export async function bankOf(charId: number): Promise<number> {
const c = await characters.get(charId);
return c?.money.bank ?? 0;
}characters.search
Персонажи по набранному тексту, загруженные или нет: начала имён ("jane doe" тоже), citizenid, id fivem / license / discord. 25 на страницу, самые новые первыми.
Сторона: Сервер · Ждёт: да
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>local page = aiLib.characters.search(text, cursor)Параметры
Prop
Type
Возвращает
CharacterSearchPage: characters (до 25) и next (null на последней странице). При ошибке отвечает пустой страницей, а не null.
Пример
import { characters, onClientCallback } from "@aicore8/lib/server";
import { oneArg, readText } from "@aicore8/lib/shared";
onClientCallback(
"myscript:people",
{ args: oneArg((v) => readText(v, 64)), rate: { count: 10, windowMs: 10_000 } },
async (_source, text) => ({ ok: true, ...(await characters.search(text)) }),
);characters.ofUser
Все персонажи одного аккаунта, по слотам.
Сторона: Сервер · Ждёт: да
characters.ofUser(user: number | string): Promise<StoredCharacter[]>local list = aiLib.characters.ofUser(user)Параметры
Prop
Type
Возвращает
Массив StoredCharacter, по порядку слотов. Пустой для неизвестного аккаунта.
characters.jobMembers and characters.gangMembers
Все, у кого есть работа или кто в банде, загруженные или нет - страница за страницей, с грейдом и с серверным id, когда они подключены.
Сторона: Сервер · Ждёт: да
characters.jobMembers(job: string, after?: number, limit?: number): Promise<MembersPage>
characters.gangMembers(gang: string, after?: number, limit?: number): Promise<MembersPage>local page = aiLib.characters.jobMembers(job, after, limit)
local page = aiLib.characters.gangMembers(gang, after, limit)Параметры
Prop
Type
Возвращает
MembersPage: members и next (null на последней странице).
Пример
import { characters } from "@aicore8/lib/server";
/** Весь состав работы, страница за страницей. */
export async function roster(job: string) {
const all = [];
let after: number | undefined;
do {
const page = await characters.jobMembers(job, after);
all.push(...page.members);
after = page.next ?? undefined;
} while (after !== undefined);
return all;
}Считать подключённых игроков работы - это не здесь: это зеркало библиотеки, online.jobMembers (без вызова экспорта и без чтения из базы).
characters.hasJobMember
Есть ли вообще кто-нибудь с этой работой, загруженный или нет. Читается одна строка, так что это достаточно дёшево для проверки при запуске («есть ли на этом сервере полиция?»).
Сторона: Сервер · Ждёт: да
characters.hasJobMember(job: string): Promise<boolean>local anyone = aiLib.characters.hasJobMember(job)Возвращает
true, когда работу держит хотя бы один персонаж.
characters.addMoney, characters.removeMoney and characters.setMoney
Деньги персонажа, загруженного или нет, со строкой журнала. Загруженный персонаж идёт через свой живой кошелёк, поэтому игрок видит изменение сразу.
Сторона: Сервер · Ждёт: да
characters.addMoney(charId: number, account: string, amount: number, reason?: string): Promise<CharacterResult>
characters.removeMoney(charId: number, account: string, amount: number, reason?: string): Promise<CharacterResult>
characters.setMoney(charId: number, account: string, amount: number, reason?: string): Promise<CharacterResult>local result = aiLib.characters.addMoney(charId, account, amount, reason)
local result = aiLib.characters.removeMoney(charId, account, amount, reason)
local result = aiLib.characters.setMoney(charId, account, amount, reason)Параметры
Prop
Type
Возвращает
{ ok: true } или { ok: false, error } с языковым ключом: неизвестный персонаж, неизвестный счёт, дробная или отрицательная сумма, либо баланс, которым нельзя заплатить (removeMoney, если тип счёта не разрешает уходить ниже нуля).
Пример
import { characters } from "@aicore8/lib/server";
export async function payOut(charId: number, amount: number): Promise<boolean> {
const result = await characters.addMoney(charId, "bank", amount, "Машина продана");
if (!result.ok) console.log(`выплата отклонена: ${result.error}`);
return result.ok;
}Переместить деньги между двумя счетами - это один вызов и одна транзакция: money.transfer. Журнал сохранённого персонажа - это money.history с { owner: "character", id, account }.
characters.setJob and characters.removeJob
Принимает персонажа на работу, меняет грейд или увольняет, онлайн он или нет. Действуют правила работ из панели, а работа безработного никогда не сохраняется: снять последнюю работу - и персонаж безработный.
Сторона: Сервер · Ждёт: да
characters.setJob(charId: number, job: string, grade: number): Promise<CharacterResult>
characters.removeJob(charId: number, job: string): Promise<CharacterResult>local result = aiLib.characters.setJob(charId, job, grade)
local result = aiLib.characters.removeJob(charId, job)Параметры
Prop
Type
Возвращает
{ ok: true } или { ok: false, error }: неизвестный персонаж, неизвестная работа, неизвестный грейд либо лимит панели на число работ.
Пример
import { characters } from "@aicore8/lib/server";
/** Уволить участника, онлайн он или нет. */
export async function fire(charId: number, job: string): Promise<boolean> {
return (await characters.removeJob(charId, job)).ok;
}characters.setGang and characters.removeGang
То же для банд.
Сторона: Сервер · Ждёт: да
characters.setGang(charId: number, gang: string, grade: number): Promise<CharacterResult>
characters.removeGang(charId: number, gang: string): Promise<CharacterResult>local result = aiLib.characters.setGang(charId, gang, grade)
local result = aiLib.characters.removeGang(charId, gang)Возвращает
{ ok: true } или { ok: false, error }, как с работами.
characters.setMeta
Одно значение метаданных персонажа, загруженного или нет. Загруженный персонаж получает его дельтой на своей игре.
Сторона: Сервер · Ждёт: да
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>local result = aiLib.characters.setMeta(charId, key, value)Параметры
Prop
Type
Возвращает
{ ok: true } или { ok: false, error } при неизвестном персонаже либо значении, которое JSON не умещает. Чтение метаданных - часть characters.get; для подключённого игрока берите GetMeta.
characters.setInfo
Имя, дата рождения, национальность, пол и рост - каждое проверяется так, как это делает форма создания персонажа.
Сторона: Сервер · Ждёт: да
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>local result = aiLib.characters.setInfo(charId, patch)Параметры
Prop
Type
Возвращает
{ ok: true } или { ok: false, error } с языковым ключом (имя, которое создание отклонило бы, дата не в формате YYYY-MM-DD, sex у загруженного персонажа).
characters.remove
Удаляет персонажа (мягкое удаление: строка остаётся для логов).
Сторона: Сервер · Ждёт: да
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>local result = aiLib.characters.remove(charId, by)Параметры
Prop
Type
Возвращает
{ ok: true } или { ok: false, error } при неизвестном персонаже либо персонаже, загруженном прямо сейчас.
characters.playTime
Секунды игры персонажа: сохранённая сумма плюс текущая сессия.
Сторона: Сервер · Ждёт: да
characters.playTime(target: number | { charId: number }): Promise<number | null>local seconds = aiLib.characters.playTime(target)Параметры
Prop
Type
Возвращает
Секунды или null при неизвестном персонаже (либо серверном id без загруженного персонажа).
characters.save
Записывает сейчас позицию и метаданные подключённого игрока и ждёт его отложенные записи.
Сторона: Сервер · Ждёт: да
characters.save(source: number): Promise<boolean>local ok = aiLib.characters.save(source)Возвращает
true, когда всё записано, false, когда у игрока нет загруженного персонажа. ai-core сохраняет сам (периодически, при выгрузке, при остановке): берите это только тогда, когда запись должна случиться до вашего следующего шага.
В других местах библиотеки
| Вам нужно | Где |
|---|---|
| Точка спавна сохранённого персонажа | characters.setOfflinePosition |
| Кто сейчас подключён, имена, работы и смена | online |
| Работы и банды загруженного игрока | jobs |
| Деньги загруженного игрока | money |
| Журнал персонажа | money.history |
Игроки и персонажи
online, onCharacter, notify, игроки рядом, позиции и хранилища для каждого игрока: PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.
Предметы
inventory: выдача, изъятие и подсчёт предметов, хранилища, магазины и используемые предметы через тот инвентарь, который запущен на сервере.