Overview
How AI Core is built - repositories, the build, the rules every script follows.
AI Core is TypeScript end to end. Each resource follows the overextended/fivem-ts layout; Lua is used only for the ESX / QB / Qbox bridge inside ai-core and for the Lua side of ai-lib.
Repositories
| Repository | What |
|---|---|
| Server folder | server.cfg and the other cfg files, recipe/ (txAdmin), tools/, template/, the rules and docs for AI tools. It is also the bun workspace root. |
ai-core and each ai-* | One repository per script. The build (dist/, fxmanifest.lua) is committed, so servers run without build tools. |
packages | The npm packages: @aicore-fivem/lib (helpers), @aicore-fivem/mysql (database engine), @aicore-fivem/shared (contracts between resources), @aicore-fivem/build (build steps). |
Build
bun install # in the server folder: links the packages and every resource
bun run build # every resource (about 40 s), or: bun run build ai-core ai-fuel
bun run typecheck
bun run lintIn a resource the same scripts run for that resource only; bun run dev watches. fxmanifest.lua is generated from package.json: never edit it by hand. After a build, restart the resource (bun tools/rcon.ts "ensure ai-fuel") or everything after ai-core (bun tools/restart.ts).
Rules every script follows
- The server decides. Every client request goes through the lib's gate (
onClientEvent/onClientCallback): real player check, rate limit, guards (admin, has a character, near a point), an argument parser. Money, items and permissions never change on the client. - Snapshot and delta. Live data goes to clients as one snapshot, then only the changes, only to who needs them. No polling, no "changed, refetch" signals.
- The lib first. Interaction points, blips, zones, keybinds, commands, menus, progress, vehicles, state bags and periodic work come from
@aicore-fivem/lib; a second hand-written copy is a defect. - Everything in the panel. Settings a server owner tunes live in the admin panel (
schema.ts+data/*.json), never in a config file. - Through AI Core. Items, vehicle keys, alerts, phone, weather, prison, clothing and deaths go through AI Core's layers, never a specific script's exports.
- Scale first. Collections are planned for millions of records and measured with benchmarks.
The full rules are in the server folder: CLAUDE.md and .claude/rules/.