AI Core
Справочник APILib: сервер

Персонажи, загруженные или нет

Модуль characters: найдите, прочитайте и измените любого персонажа через ai-core - деньги, работы, банды, метаданные, имя, время игры - с Promise в TypeScript и простым ожиданием в Lua.

TypeScript
import { characters } from "@aicore8/lib/server";
Lua
-- 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>
Lua
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>
Lua
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[]>
Lua
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>
Lua
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>
Lua
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>
Lua
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>
Lua
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>
Lua
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>
Lua
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>
Lua
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>
Lua
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>
Lua
local seconds = aiLib.characters.playTime(target)

Параметры

Prop

Type

Возвращает

Секунды или null при неизвестном персонаже (либо серверном id без загруженного персонажа).

characters.save

Записывает сейчас позицию и метаданные подключённого игрока и ждёт его отложенные записи.

Сторона: Сервер · Ждёт: да

Сигнатура
characters.save(source: number): Promise<boolean>
Lua
local ok = aiLib.characters.save(source)

Возвращает

true, когда всё записано, false, когда у игрока нет загруженного персонажа. ai-core сохраняет сам (периодически, при выгрузке, при остановке): берите это только тогда, когда запись должна случиться до вашего следующего шага.

В других местах библиотеки

Вам нужноГде
Точка спавна сохранённого персонажаcharacters.setOfflinePosition
Кто сейчас подключён, имена, работы и сменаonline
Работы и банды загруженного игрокаjobs
Деньги загруженного игрокаmoney
Журнал персонажаmoney.history

На этой странице