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.
import { characters } from "@aicore8/lib/server";-- 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, usecharacters.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
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
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- table or nilParameters
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
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>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
characters.ofUser(user: number | string): Promise<StoredCharacter[]>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
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)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
characters.hasJobMember(job: string): Promise<boolean>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
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)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
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)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
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)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
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>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
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>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
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>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
characters.playTime(target: number | { charId: number }): Promise<number | null>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
characters.save(source: number): Promise<boolean>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 want | Where |
|---|---|
| A stored character's spawn point | characters.setOfflinePosition |
| Who is connected now, their names, jobs and duty | online |
| A loaded player's jobs and gangs | jobs |
| A loaded player's money | money |
| A character's ledger | money.history |