Personnages et joueurs

Un joueur est une personne connectée avec un id serveur (source). Un personnage est l’une des personnes que ce joueur incarne ; il a un id en base de données (charId) et un citizen id (citizenid, un court texte comme ABC12345). Un joueur a un personnage chargé après en avoir choisi un sur l’écran des personnages. La plupart des exports ici répondent null avant cela.

Les appels d’export copient leur réponse : lisez donc ce dont vous avez besoin une fois et suivez les événements d’ai-core (ai-core:playerLoaded, ai-core:playerUnloaded) au lieu de redemander. Voir Événements et état.

GetPlayerDataCopy Anchor Link

Tout ce qu’ai-core garde pour un joueur chargé dans un seul objet : personnage, argent, métiers, service, gangs et métadonnées. Utilisez-le quand une ressource démarre tard et a besoin une fois de l’état complet d’un joueur ; pour des valeurs isolées, utilisez les exports plus petits ci-dessous.

Côté : Serveur · Attend : non · Lib : aucune côté serveur (getPlayerData de la lib client lit les mêmes données dans le jeu du joueur)

GetPlayerData(src: number): AiPlayerData | null

local data = exports['ai-core']:GetPlayerData(source) -- table ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

AiPlayerData | null : une copie des données du joueur (AiPlayerData). null quand personne avec cet id serveur n’a de personnage chargé (pas connecté, ou encore sur l’écran des personnages). La copie ne change plus ensuite : rappelez ou suivez les événements pour les nouvelles valeurs.

ExempleCopy Anchor Link

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");

addCommand("whoami", { help: "Shows your character", restricted: true }, (source) => {
  const data = core.GetPlayerData(source);
  if (!data?.character) return;
  const { firstname, lastname } = data.character;
  console.log(`${firstname} ${lastname}: job ${data.job.job} (grade ${data.job.grade}), cash ${data.money.cash ?? 0}`);
});

GetCharacterCopy Anchor Link

Le personnage chargé d’un joueur : id en base, citizen id, emplacement, noms, date de naissance, sexe et nationalité. Utilisez-le pour afficher un nom ou pour stocker quelque chose par id de personnage.

Côté : Serveur · Attend : non · Lib : aucune (online.character(source) lit la même chose depuis le miroir de la lib sans appel d’export)

GetCharacter(src: number): CharacterInfo | null

local character = exports['ai-core']:GetCharacter(source) -- table ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

CharacterInfo | null : le personnage (CharacterInfo). null quand le joueur n’a pas de personnage chargé.

ExempleCopy Anchor Link

import { onClientCallback, resourceExport } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const core = resourceExport("ai-core");

onClientCallback("myscript:profile", (source) => {
  const character = core.GetCharacter(source);
  if (!character) return fail("NO_CHARACTER");
  return { ok: true, name: `${character.firstname} ${character.lastname}`, citizenid: character.citizenid };
});

GetSourceByCharIdCopy Anchor Link

L’id serveur du joueur qui incarne un personnage en ce moment. Utilisez-le quand vous avez stocké un id de personnage (un propriétaire, un contact) et devez joindre cette personne dans le jeu.

Côté : Serveur · Attend : non · Lib : aucune

GetSourceByCharId(charId: number): number | null

local src = exports['ai-core']:GetSourceByCharId(charId) -- number ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number | null : l’id serveur du joueur. null quand personne n’incarne ce personnage maintenant (hors ligne, ou un autre personnage est chargé).

ExempleCopy Anchor Link

import { notify, resourceExport } from "@aicore-fivem/lib/server";
import { Locale } from "common";

const core = resourceExport("ai-core");

/** Tells a house owner that someone rang, when the owner is online. */
export function ringOwner(ownerCharId: number): void {
  const owner = core.GetSourceByCharId(ownerCharId);
  if (owner !== null) notify(owner, Locale("NOTIFY_DOORBELL"), "info");
}

GetSourceByCitizenIdCopy Anchor Link

Identique à GetSourceByCharId, par citizen id. Utilisez-le avec des données qui stockent des citizen ids (c’est le cas de la plupart des tables de style ESX / QB).

Côté : Serveur · Attend : non · Lib : aucune

GetSourceByCitizenId(citizenid: string): number | null

local src = exports['ai-core']:GetSourceByCitizenId(citizenid) -- number ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number | null : l’id serveur du joueur qui incarne ce personnage. null quand le personnage n’est pas chargé.

ExempleCopy Anchor Link

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");

addCommand("findcid", {
  help: "Finds the player of a citizen id",
  params: [{ name: "citizenid", type: "string" }],
  restricted: true,
}, (source, args) => {
  const target = core.GetSourceByCitizenId(args.citizenid);
  console.log(target === null ? "not online" : `server id ${target}`);
});

GetLoadedSourcesCopy Anchor Link

Les ids serveur de chaque joueur qui a un personnage chargé. Utilisez-le pour un travail rare sur tout le serveur (un avertissement de redémarrage, une liste d’admin).

Côté : Serveur · Attend : non · Lib : online.sources() lit la même chose depuis le miroir de la lib

GetLoadedSources(): number[]

local sources = exports['ai-core']:GetLoadedSources() -- liste de nombres

ParamètresCopy Anchor Link

Aucun.

RetourCopy Anchor Link

number[] : un id serveur par joueur chargé, sans ordre fixe. Une liste vide quand personne n’a de personnage chargé. Les joueurs encore sur l’écran des personnages n’y sont pas.

ExempleCopy Anchor Link

import { addCommand, notify, resourceExport } from "@aicore-fivem/lib/server";
import { Locale } from "common";

const core = resourceExport("ai-core");

addCommand("announce", {
  help: "Sends a notification to every player",
  params: [{ name: "text", type: "longString" }],
  restricted: true,
}, (_source, args) => {
  for (const target of core.GetLoadedSources())
    notify(target, Locale("NOTIFY_ANNOUNCEMENT", args.text), "warning");
});

GetUserIdCopy Anchor Link

L’id de compte d’un joueur connecté : la ligne de ai_core_users, qui contient le compte FiveM du joueur et tous ses personnages. Contrairement à la plupart des exports, il répond aussi pendant que le joueur est encore sur l’écran des personnages.

Côté : Serveur · Attend : non · Lib : aucune

GetUserId(src: number): number | null

local userId = exports['ai-core']:GetUserId(source) -- number ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number | null : l’id de compte. null quand le joueur n’est pas connecté ou n’a pas encore atteint l’écran des personnages.

ExempleCopy Anchor Link

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");

addCommand("account", {
  help: "Shows a player account id",
  params: [{ name: "id", type: "playerId" }],
  restricted: true,
}, (_source, args) => {
  console.log(`account ${core.GetUserId(args.id) ?? "unknown"}`);
});

GetFivemIdCopy Anchor Link

L’id de compte FiveM (Cfx.re) du joueur. ai-core l’utilise comme clé du compte du joueur : un joueur qui n’en a pas ne peut pas se connecter.

Côté : Serveur · Attend : non · Lib : aucune

GetFivemId(src: number): string | null

local fivemId = exports['ai-core']:GetFivemId(source) -- string ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

string | null : l’id sans le préfixe fivem: (par exemple 1234567). null quand le joueur n’a pas de personnage chargé.

ExempleCopy Anchor Link

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");

addCommand("fivemid", {
  help: "Prints the add_principal line for a player",
  params: [{ name: "id", type: "playerId" }],
  restricted: true,
}, (_source, args) => {
  const id = core.GetFivemId(args.id);
  if (id) console.log(`add_principal identifier.fivem:${id} group.admin`);
});

GetCharacterInfoCopy Anchor Link

Un personnage par id en base, chargé ou non, avec l’id du compte auquel il appartient. Utilisez-le pour montrer à qui appartient quelque chose quand cette personne peut être hors ligne.

Côté : Serveur · Attend : non (répond via done) · Lib : aucune

GetCharacterInfo(
  charId: number,
  done: (info: (CharacterInfo & { userId: number }) | null) => void,
): void

exports['ai-core']:GetCharacterInfo(charId, function(info) end) -- info : table ou nil

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Rien. done reçoit un CharacterInfo avec un champ de plus, userId (l’id de compte), ou null pour un personnage inconnu ou supprimé, un id erroné ou une lecture échouée. Sans fonction comme done, l’appel ne fait rien.

ExempleCopy Anchor Link

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");

addCommand("charinfo", {
  help: "Shows a character by id",
  params: [{ name: "charId", type: "number" }],
  restricted: true,
}, (_source, args) => {
  core.GetCharacterInfo(args.charId, (info) => {
    if (!info) return console.log("no such character");
    console.log(`${info.firstname} ${info.lastname} (${info.citizenid}), account ${info.userId}`);
  });
});

SwitchCharacterCopy Anchor Link

Renvoie un joueur à l’écran des personnages sans quitter le serveur, comme une déconnexion. ai-core enregistre et décharge d’abord le personnage, puis ouvre l’écran.

Côté : Serveur · Attend : non (le déchargement s’exécute après le retour de l’appel) · Lib : aucune

SwitchCharacter(src: number): boolean

local started = exports['ai-core']:SwitchCharacter(source) -- boolean

ParamètresCopy Anchor Link

RetourCopy Anchor Link

boolean : true quand le changement a commencé. false quand le joueur n’a pas de personnage chargé.

ExempleCopy Anchor Link

import { onClientCallback, resourceExport } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const core = resourceExport("ai-core");

// Un bouton « Changer de personnage » dans votre menu.
onClientCallback("myscript:logout", (source) =>
  core.SwitchCharacter(source) ? { ok: true } : fail("NO_CHARACTER"),
);

SetOfflinePositionCopy Anchor Link

Déplace le point d’apparition d’un personnage qui n’est pas chargé : la prochaine fois que ce personnage est choisi, il apparaît là. Utilisez-le quand quelque chose déplace un corps endormi ou un personnage hors ligne (un corps emporté, un joueur remorqué).

Côté : Serveur · Attend : non (l’écriture suit en arrière-plan) · Lib : characters.setOfflinePosition

SetOfflinePosition(
  charId: number,
  position: { x: number; y: number; z: number; heading?: number },
): boolean

local accepted = exports['ai-core']:SetOfflinePosition(charId, { x = x, y = y, z = z, heading = h })

ParamètresCopy Anchor Link

RetourCopy Anchor Link

boolean : true quand le déplacement est accepté ; l’écriture en base suit dès qu’aucun chargement ni enregistrement de ce personnage n’est en cours (elle attend jusqu’à 30 secondes). false quand le personnage est chargé maintenant, que charId n’est pas un nombre entier ou qu’une coordonnée manque ou n’est pas un nombre fini. Un heading absent est stocké comme 0.

ExempleCopy Anchor Link

import { resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");
const HOSPITAL = { x: 298.6, y: -584.5, z: 43.3, heading: 70 };

/** A body left in the world too long is moved to the hospital. */
export function sendBodyToHospital(charId: number): void {
  if (!core.SetOfflinePosition(charId, HOSPITAL))
    console.log(`character ${charId} is online, not moved`);
}

GetPlayersInScopeCopy Anchor Link

Les joueurs dans la portée OneSync d’un autre joueur : tous ceux dont le jeu diffuse actuellement ce joueur, environ 424 mètres autour. ai-core tient cette liste à partir des événements de portée de FiveM une seule fois pour toutes les ressources, si bien que les autres ressources n’écoutent jamais ces événements elles-mêmes.

Côté : Serveur · Attend : non · Lib : playersNear(source, radius) et playersNearEntity(entity, radius) reposent dessus et filtrent par distance

GetPlayersInScope(source: number): number[]

local nearby = exports['ai-core']:GetPlayersInScope(source) -- liste d’ids serveur

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number[] : les ids serveur des autres joueurs à portée (le joueur lui-même n’est pas dans la liste). Une liste vide pour un joueur seul, un id inconnu ou une valeur qui n’est pas un nombre.

ExempleCopy Anchor Link

import { coordsOf, resourceExport } from "@aicore-fivem/lib/server";
import { distance } from "@aicore-fivem/lib/shared";

const core = resourceExport("ai-core");

/** Plays a sound for everyone within 30 m of a player. */
export function playNear(source: number, sound: string): void {
  const at = coordsOf(source);
  for (const other of [source, ...core.GetPlayersInScope(source)])
    if (distance(coordsOf(other), at) <= 30) emitNet("myscript:sound", other, sound);
}