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
| Kind | What it is | How you listen |
|---|---|---|
| Local event | Fired 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 event | Sent 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 bag | A 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
| Page | What |
|---|---|
| Server events | Character loaded, spawned, unloaded; money, jobs, duty, gangs, metadata; item used; player died; job and gang definitions; inventory changed. |
| Client events | The local character loaded or unloaded, down state, cached values, HUD visibility, world sync, key hints, seat belt. |
| Net events | The player data channel a client may listen to, and ai-core's own traffic you must not trigger. |
| ai-lib UI events | Answers of menus, input dialogs, prompts and the progress bar, for scripts that call ai-lib's exports themselves. |
| State bags | PLAYER_BAGS, VEHICLE_BAGS and every GlobalState key ai-core writes. |
| Framework bridge events | The 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:
| Constant | Events |
|---|---|
CORE | ai-core's server and client events (CORE.playerLoadedEvent, CORE.clientDeadEvent...) and GlobalState keys (CORE.pvpStateKey...). |
KEY_HINTS | KEY_HINTS.changedEvent. |
MENU_EVENTS, LIB_UI | ai-lib's UI answers. |
VEHICLES_EVENTS | ai-vehicles' owner feed. |
VRP | VRP.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
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.