AI Core

Events and state

How ai-core tells other scripts that something changed - local events, net events, state bags - and how to listen in TypeScript and Lua.

ai-core tells other scripts when something changes: a character loaded, money moved, a job changed, the player went down, the HUD hid. Your script listens instead of asking again and again. This section lists every event and shared state value other resources use.

The three kinds

KindWhat it isHow you listen
Local eventFired on one side (server or one client) for every resource on that side. Never crosses the network. Most ai-core events are local.TS: on(name, handler). Lua: AddEventHandler(name, handler).
Net eventSent from the server to one player's client (or the other way).TS client: onServerEvent(name, ...) from the lib. Lua client: aiLib.onServerEvent(name, handler).
State bagA value stored on GlobalState, a player or an entity. Everyone can read it; only the owning resource writes it.The lib's GlobalKey, PlayerState, EntityState, GlobalGroup, or GlobalState[...], Player(src).state[...], Entity(e).state[...] in Lua.

Pages

PageWhat
Server eventsCharacter loaded, spawned, unloaded; money, jobs, duty, gangs, metadata; item used; player died; job and gang definitions; inventory changed.
Client eventsThe local character loaded or unloaded, down state, cached values, HUD visibility, world sync, key hints, seat belt.
Net eventsThe player data channel a client may listen to, and ai-core's own traffic you must not trigger.
ai-lib UI eventsAnswers of menus, input dialogs, prompts and the progress bar, for scripts that call ai-lib's exports themselves.
State bagsPLAYER_BAGS, VEHICLE_BAGS and every GlobalState key ai-core writes.
Framework bridge eventsThe ESX, QB / Qbox and vRP events ai-core fires for scripts written for those frameworks, and the framework events it answers.

Names come from constants

In TypeScript, never type an event name by hand. They are constants in @aifivem/shared:

ConstantEvents
COREai-core's server and client events (CORE.playerLoadedEvent, CORE.clientDeadEvent...) and GlobalState keys (CORE.pvpStateKey...).
KEY_HINTSKEY_HINTS.changedEvent.
MENU_EVENTS, LIB_UIai-lib's UI answers.
VEHICLES_EVENTSai-vehicles' owner feed.
VRPVRP.configEvent.
PLAYER_BAGS, VEHICLE_BAGS, INVENTORY_STATE_KEY, APPEARANCE_STATE_KEY, dutyCountKey(job)...State bag keys.

Lua has no constants: use the string shown next to each event.

A first listener

resource/server/index.ts
import { CORE, type CharacterInfo } from "@aifivem/shared";

on(CORE.playerLoadedEvent, (src: number, character: CharacterInfo) => {
  console.log(`${character.firstname} ${character.lastname} joined as ${src}`);
});

For a character's whole life on the server (loaded, unloaded, and the characters already in the world when your resource restarts), use the lib's onCharacter({ loaded, unloaded }) (aiLib.onCharacter in Lua) instead of the two events by hand. A resource that starts late misses events fired before it started; onCharacter replays those characters for you.

ai-core's local events are local on purpose. Never RegisterNetEvent (or onNet) one of their names: that would let any player's client fire a fake ai-core:moneyChanged or ai-core:playerLoaded into your handler. Plain AddEventHandler / on only hears events fired on the same side.

On this page