AI Core

Characters, loaded or not

The characters module: find, read and change any character through ai-core - money, jobs, gangs, metadata, name, play time - with a Promise in TypeScript and a plain wait in Lua.

TypeScript
import { characters } from "@aicore8/lib/server";
Lua
-- aiLib.characters, after shared_script '@ai-lib/init.lua'

characters is the lib's door to ai-core's stored-character exports. It exists because those exports answer through a callback: the lib turns each one into a Promise in TypeScript and into a plain wait in Lua, so your code reads top to bottom.

  • A character is named by its character id (charId, a number). From a citizenid, use characters.idOf.
  • A loaded character answers from memory (live money, live memberships); a stored one is read from the database while ai-core holds it, so it cannot load in the middle of a write.
  • Every write answers ActionResult: { ok: true }, or { ok: false, error } with an ai-core lang key.
  • Every function here waits. In Lua that means calling it from a thread; see Functions that wait.

For the player an action is about, the shorter path is often ai-core directly: GetCharacter, money, jobs. Use characters when the target may be offline, or when you need a whole character at once.

characters

characters.idOf

The character id behind a citizenid.

Side: Server · Waits: yes

Signature
characters.idOf(citizenid: string): Promise<number | null>

No Lua twin: call ai-core's export GetCharIdByCitizenId and wait for its callback.

Parameters

Prop

Type

Returns

Promise<number | null>: the character id, or null when no character has that citizenid or it was deleted.

Example

import { characters } from "@aicore8/lib/server";

/** A fine that works whether the driver is online or not. */
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, "Speeding fine")).ok;
}

characters.get

One character with everything ai-core keeps about it: info, money per account, jobs, gangs, metadata, stored position, last save, and the server id when it is loaded.

Side: Server · Waits: yes

Signature
characters.get(charId: number): Promise<OfflineCharacter | null>
Lua
local character = aiLib.characters.get(charId) -- table or nil

Parameters

Prop

Type

Returns

An OfflineCharacter, or null / nil when the id is unknown or the character was deleted.

Example

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

Characters by a typed text, loaded or not: name prefixes ("jane doe" too), citizenid, fivem / license / discord id. 25 a page, newest first.

Side: Server · Waits: yes

Signature
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>
Lua
local page = aiLib.characters.search(text, cursor)

Parameters

Prop

Type

Returns

A CharacterSearchPage: characters (up to 25) and next (null on the last page). On an error it answers an empty page, never null.

Example

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

Every character of one account, by slot.

Side: Server · Waits: yes

Signature
characters.ofUser(user: number | string): Promise<StoredCharacter[]>
Lua
local list = aiLib.characters.ofUser(user)

Parameters

Prop

Type

Returns

An array of StoredCharacter, ordered by slot. Empty for an unknown account.

characters.jobMembers and characters.gangMembers

Everyone who holds a job, or is in a gang, loaded or not - a page at a time, with their grade and their server id when they are connected.

Side: Server · Waits: yes

Signature
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)

Parameters

Prop

Type

Returns

A MembersPage: members and next (null on the last page).

Example

import { characters } from "@aicore8/lib/server";

/** The whole roster of a job, page by page. */
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;
}

Counting the players who are connected in a job is not this: that is the lib's mirror, online.jobMembers (no export call, no database read).

characters.hasJobMember

Whether anyone at all holds a job, loaded or not. One row is read, so it is cheap enough for a boot check ("does this server have a police force?").

Side: Server · Waits: yes

Signature
characters.hasJobMember(job: string): Promise<boolean>
Lua
local anyone = aiLib.characters.hasJobMember(job)

Returns

true when at least one character holds the job.

characters.addMoney, characters.removeMoney and characters.setMoney

Money of a character, loaded or not, with a ledger row. A loaded character goes through its live wallet, so the player sees the change at once.

Side: Server · Waits: yes

Signature
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)

Parameters

Prop

Type

Returns

{ ok: true }, or { ok: false, error } with a lang key: unknown character, unknown account, a fractional or negative amount, or a balance that cannot pay (removeMoney, unless the account type may go below zero).

Example

import { characters } from "@aicore8/lib/server";

export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Vehicle sold");
  if (!result.ok) console.log(`payout refused: ${result.error}`);
  return result.ok;
}

Moving money between two accounts is one call and one transaction: money.transfer. A stored character's ledger is money.history with { owner: "character", id, account }.

characters.setJob and characters.removeJob

Hires, regrades or fires a character, online or not. The panel's job rules apply, and the unemployed job is never stored: removing the last job is what makes a character unemployed.

Side: Server · Waits: yes

Signature
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)

Parameters

Prop

Type

Returns

{ ok: true }, or { ok: false, error }: unknown character, unknown job, unknown grade, or the panel's limit on how many jobs a character may hold.

Example

import { characters } from "@aicore8/lib/server";

/** Fire a member whether they are online or not. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

characters.setGang and characters.removeGang

The same for gangs.

Side: Server · Waits: yes

Signature
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)

Returns

{ ok: true } or { ok: false, error }, as with jobs.

characters.setMeta

One metadata value of a character, loaded or not. A loaded character gets it as a delta on their own game.

Side: Server · Waits: yes

Signature
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>
Lua
local result = aiLib.characters.setMeta(charId, key, value)

Parameters

Prop

Type

Returns

{ ok: true }, or { ok: false, error } for an unknown character or a value JSON cannot hold. Reading metadata is part of characters.get; for a connected player use GetMeta.

characters.setInfo

Name, birth date, nationality, sex and height, each checked the way the character creation form checks it.

Side: Server · Waits: yes

Signature
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>
Lua
local result = aiLib.characters.setInfo(charId, patch)

Parameters

Prop

Type

Returns

{ ok: true }, or { ok: false, error } with a lang key (a name the creator would refuse, a date that is not YYYY-MM-DD, sex on a loaded character).

characters.remove

Deletes a character (soft delete: the row stays for the logs).

Side: Server · Waits: yes

Signature
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>
Lua
local result = aiLib.characters.remove(charId, by)

Parameters

Prop

Type

Returns

{ ok: true }, or { ok: false, error } for an unknown character or one that is loaded right now.

characters.playTime

Seconds a character has been played: the saved total plus the running session.

Side: Server · Waits: yes

Signature
characters.playTime(target: number | { charId: number }): Promise<number | null>
Lua
local seconds = aiLib.characters.playTime(target)

Parameters

Prop

Type

Returns

The seconds, or null for an unknown character (or a server id without a loaded character).

characters.save

Writes a connected player's position and metadata now and waits for their queued writes.

Side: Server · Waits: yes

Signature
characters.save(source: number): Promise<boolean>
Lua
local ok = aiLib.characters.save(source)

Returns

true once everything is written, false when the player has no loaded character. ai-core saves by itself (periodically, on unload, on shutdown): use this only when the write must have happened before your next step.

Elsewhere in the lib

You wantWhere
A stored character's spawn pointcharacters.setOfflinePosition
Who is connected now, their names, jobs and dutyonline
A loaded player's jobs and gangsjobs
A loaded player's moneymoney
A character's ledgermoney.history

On this page