# Admin panel (/docs/admin-panel) Every setting a server owner tunes lives in one in-game panel: framework settings, jobs and gangs, money accounts, and a tab group for each `ai-*` script. Nothing has to be edited in a config file. Open it with **F10** (or `/aiadmin`). Only admins can open it (ACE `ai.admin`, see `permission.cfg`). ## How it works [#how-it-works] - **Live save.** Every change is checked by the server and saved at once; players see it without a restart. - **No wrong values.** Numbers have their limits and units, items, jobs, gangs and accounts are picked from lists, and the panel refuses what the server would refuse, with a plain message. - **Places are set in the world.** A point field offers *Use my position*, *Teleport* and a free camera pick (fly, aim at the floor, scroll for the heading). Areas are drawn corner by corner and shown in the world while you edit them. - **Pickers for game things.** Vehicle, ped and object models with search and pictures, map blips from a picture grid, colours with presets, doors and props picked with the camera. - **Copy and import.** Records tabs (shops, garages, jobs...) copy every record as JSON and import pasted records. - **Files you can read.** Each script keeps its settings in `data/*.json` with a JSON Schema next to it, so an editor explains and checks a hand edit too. ## What is in it [#what-is-in-it] | Section | What you set | | --- | --- | | Dashboard | Players online, updates of your scripts, recommended free scripts. | | Players | Online and offline characters: money, jobs, gangs, name, metadata, kill and revive. | | General | Server brand, character screen scene, spawn points and the spawn chooser, interaction style (prompt or target), PvP, which inventory / key system / dispatch / clothing script AI Core uses. | | Jobs, gangs, accounts | Grades, salaries, boss grades, duty rules, prime time, money accounts. | | Commands, keybinds | Every command with its access, every keybind's default key and its HUD hint. | | Logs | Console, Discord, Fivemanage and FiveM Stats providers, levels, webhooks. | | Each `ai-*` script | Its own tabs: places, prices, rules, items. | ## Setup guide [#setup-guide] On a new server the panel opens on a setup guide: the brand, the first spawn point, the character screen and the scripts to keep. Until it is finished, players see a welcome card after spawning, and admins can open the guide from it. # Compatibility (/docs/compatibility) Almost every FiveM script is written for ESX, QBCore, Qbox or vRP, so running them is a main goal. AI Core ships no third-party scripts and favours no vendor: you install your own. ## Three layers [#three-layers] ### Framework bridge [#framework-bridge] AI Core provides `es_extended`, `qb-core` and `qbx_core` and answers their exports, core objects, player objects, callbacks, events and file includes (`@qb-core/shared/locale.lua`, `@es_extended/imports.lua`, `@qbx_core/modules/playerdata.lua`), so scripts written for ESX, QBCore or Qbox see AI Core as their framework and run unchanged. AI Core also provides `vrp` for vRP scripts (see **vRP scripts** below). Their menus, text prompts, progress bars and input dialogs are drawn with AI Core's own UI. ### Integration layers [#integration-layers] AI Core and the `ai-*` scripts need things other scripts provide. Each category has one interface and each supported script is one adapter. AI Core detects the installed script at start and when scripts start or stop; the admin panel can override the choice. | Category | Examples | | --- | --- | | Inventory | ai-inventory, ox_inventory, qb-inventory, tgiann-inventory and more | | Vehicle keys | ai-vehiclekeys, qbx_vehiclekeys and others | | Dispatch (police alerts) | ai-policealert and alert scripts | | Phone | tgiann-phone, lb-phone | | Clothing | ai-appearance, tgiann-clothing | | Death | ai-death, qbx_medical, qb-ambulancejob, esx_ambulancejob, ars_ambulancejob | | Weather and time | ai-weathersync, qb-weathersync, Renewed-Weathersync, cd_easytime | | Prison | ai-prison, qb-prison | | Radial menu | ai-radialmenu, qb-radialmenu, ox_lib | ### Stand-ins [#stand-ins] Several `ai-*` scripts answer the API of the script they replace, so third-party scripts work with them without an adapter: ai-mysql stands in for oxmysql (also mysql-async and ghmattimysql), ai-inventory for ox_inventory and qb-inventory, ai-target for ox_target, ai-voice for pma-voice, ai-chat for chat, ai-vehicles and ai-vehiclekeys for the Qbox vehicle scripts. See the [compatible scripts](/scripts) list for what AI Core integrates with today. ## vRP scripts [#vrp-scripts] AI Core also provides `vrp`, so scripts written for the vRP framework find it and run on AI Core's characters, money, jobs, gangs and inventory. There is no setting: every version below is answered at the same time, and AI Core tells them apart by the way they call it. | vRP version | What runs | | --- | --- | | vRP 1.0 | Scripts that use `Proxy` / `Tunnel` with `vRP.*` and `vRPclient.*`: users, money, groups and permissions, inventory and chests, identity, hunger and thirst, menus, prompts, notifications, blips and markers. | | vRPex, Zirix, Dunko | The same, plus the extra functions these vRP 1 forks add (`format`, `hasPermissions`, `tryBankPayment` and others). | | The old vRP 0.5 call style | Calls that pass their arguments in a table with a callback, like `vRP.getUserId({source})`. | | vRP 2 and vRP 3 | Extensions a script loads with `vRP.loadScript`. Each one runs in its own sandbox inside AI Core: its globals never touch another script, and everything it registered is removed when its resource stops. | The menus, text prompts and yes / no requests of vRP scripts are drawn with AI Core's own menu and dialogs. When a script adds entries to vRP's main menu, players open it with **F7**; you can change the key in the admin panel's **Keybinds**. AI Core was tested on a running server with seven public vRP scripts: vrp_basic_mission, vrp_chests, vrp_blips, self_storages, vrp_drugfarms, vrp_worlditems and party_system. ## Installing a vRP script [#installing-a-vrp-script] ### Remove the original vRP [#remove-the-original-vrp] AI Core is your `vrp` resource now, so the original one must go. If your server has a `vrp` folder or a vRP database driver (`vrp_mysql`, `vrp_oxmysql`, `vrp_ghmattimysql`, `vRP-db-drivers`), delete the folder and its `ensure` line in `server.cfg`. While one of them is still there, AI Core refuses joins and names the folder to delete. ### Add the script [#add-the-script] Put the script's folder in `resources/[standalone]/` and add `ensure ` to `server.cfg` below the `ensure ai-*` lines, like any other script. Do not edit the script: its `vrp` dependency and its `@vrp/lib/utils.lua` include reach AI Core on their own. ### Start it and give out its permissions [#start-it-and-give-out-its-permissions] Restart the server and try the script's features in game. Then open the admin panel (**F10**) and AI Core's **vRP scripts** tab: **Asked permissions** lists every permission name the script asked for. Decide who gets each one, as the next section explains. ## The vRP scripts tab [#the-vrp-scripts-tab] vRP scripts do not ask "is this player a police officer?". They ask for permission names (`police.service`), group names (`police`, `vip`) and item ids (`edible|tacos`). The **vRP scripts** tab, in AI Core's part of the admin panel, decides what those names mean on your server. Every change is saved at once, without a restart. The tab has five cards: ### Built-in rules [#built-in-rules] These three switches answer every permission name that no rule mentions, so many scripts work before you add a single rule: - **Job permissions go to the job**: a permission that starts with a job's name, like `police.service`, goes to the members of that job. With **Only while on duty** on, they have it only while they are on duty. - **admin. permissions go to admins**: a permission that starts with `admin.`, like `admin.tickets`, goes to players with admin rights (ACE `ai.admin`). - **player. permissions go to everyone**: a permission that starts with `player.`, like `player.phone`, goes to every player. ### Asked permissions [#asked-permissions] Every permission name your scripts have asked for, with a search box. Press **Add rule** next to a name and a rule for it appears at the top of **Permission rules**. A new rule gives the permission to admins only, until you pick who should have it. ### Permission rules [#permission-rules] One row per rule. In **Permission name**, write the permission (`police.service`), or a name ending in `*` (`police.*`) to cover every permission that starts with it. In **Who has it**, pick one: - **Members of a job**: pick the job and the **Lowest grade** (that grade and every grade above it). Turn on **Only on duty** if they should have it only while on duty. - **Members of a gang**: pick the gang and the lowest grade. - **Characters in a group**: write a group name that scripts give (see **Group names**). - **Admins** or **Everyone**. Several rules may name the same permission: whoever matches any of them has it. Once a rule names a permission, the built-in rules no longer count for it. The panel refuses a grade the job or gang does not have. ### Group names [#group-names] vRP scripts give and check groups by name. A job's or a gang's own name (`police`, `ballas`) works without a row. For any other name a script uses (`Coronel`, `sheriff`), add a row: write it in **Group name** and pick what it **Means**: - **A job grade** or **A gang grade**: when a script gives this group, the character gets that job or gang at that grade; when a script checks it, the answer is yes for that grade and every grade above it. - **Admins**: the check answers yes for players with admin rights. A script can never make someone an admin: giving this group is refused. A name without a row stays a group of its own, saved with the character. ### Item names [#item-names] Link an item id a script uses (**Name scripts use**, like `edible|tacos`) to an item of your inventory (**Inventory item**, picked from the list). An id that is already the name of one of your items needs no row. Without a row, `wbody|WEAPON_X` means the weapon item and any other `a|b` id means `b`. Example: a police script asks for `police.service`, but your police job is called `lspd`. Add a permission rule with the name `police.service`, **Members of a job**, the job `lspd`, lowest grade 0 and **Only on duty** on. Every officer on duty now has the permission. ## What does not work with vRP [#what-does-not-work-with-vrp] - **Creative v5.** Its API (PascalCase names, `@vrp/lib/Utils.lua`, `@vrp/config/*.lua`) is different and is not answered. - **SQL on vRP's own tables.** AI Core keeps its own data, so a script that reads or writes `vrp_users`, `vrp_user_identities`, `vrp_user_data`, `vrp_srv_data` or similar tables with its own queries finds nothing. - **vRP modules AI Core does not have:** phone directory, homes, businesses, owned vehicles and garages, aptitudes, police records and jail, shops, item transformers, ATMs, audio and radio, progress bars, bans and whitelist, and the missions of vRP 1 (vRP 2 / 3 missions work). A script that uses them loses that part. - **Menus have no left / right.** Options that change a value with the arrow keys only take a plain pick. - **`vRP:playerSpawn` fires once per character load**, not after a respawn: respawns belong to the death script. - **`vrp` always reads as started.** A script that supports several frameworks and checks vRP first takes its vRP code. If you want its ESX or QBCore code, choose that framework in the script's own config. - **A vRP 2 / 3 extension runs inside AI Core**, so its CPU time shows under `ai-core` in `resmon`. If it fails, the console prints one line with its file and AI Core keeps running. ## Replacing an ai-* script [#replacing-an-ai--script] If you install a paid script that replaces an `ai-*` one (for example another inventory), AI Core tells you which folder to delete and refuses joins while both run, so two scripts never fight over the same job. ## Adding a script [#adding-a-script] Supporting a new script is one small, repeatable job: copy the category's adapter template, fill in its calls, add one line to the registry. You can ask your AI to do it. # Credits (/docs/credits) AI Core stands on the work of the open-source FiveM community. Its framework bridge answers the ESX, QBCore, Qbox and vRP APIs, its lib covers what ox_lib offers, and many `ai-*` scripts were written by reading the open-source scripts below: their features, default places (counters, NPCs, spots, cameras), configuration values and, where the license allows, their code. Thank you to everyone who built and shared them. AI Core is released under the GNU GPL v3 (`LICENSE` in every repository), which keeps it compatible with the GPL and LGPL projects it learned from. Every project keeps its own copyright; the names below are trademarks of their owners and are used only to describe compatibility. ## Frameworks [#frameworks] | Project | Authors | License | What AI Core takes from it | | --- | --- | --- | --- | | [ESX Legacy](https://github.com/esx-framework/esx_core) | ESX Framework | GPL-3.0 | API of the `es_extended` bridge (xPlayer, events, callbacks), job and account model | | [QBCore](https://github.com/qbcore-framework/qb-core) | QBCore Framework | GPL-3.0 | API of the `qb-core` bridge (Player object, metadata, events, commands), shared items, jobs, gangs, default places | | [Qbox](https://github.com/Qbox-project/qbx_core) | Qbox Project | GPL-3.0 | API of the `qbx_core` bridge, multi-job and group ideas, many qbx_* scripts listed below | | [ox_core](https://github.com/overextended/ox_core) | Overextended | LGPL-3.0 | Data model and server-authoritative design ideas | | [ND Core](https://github.com/ND-Framework/ND_Core) | ND Framework | GPL-3.0 | Framework comparison | | [vRP](https://github.com/ImagicTheCat/vRP) | ImagicTheCat | MIT | API of the `vrp` bridge (vRP 1, 2 and 3) | ## Libraries and tooling [#libraries-and-tooling] | Project | Authors | License | What AI Core takes from it | | --- | --- | --- | --- | | [ox_lib](https://github.com/overextended/ox_lib) | Overextended | LGPL-3.0 | The shape of `@aicore8/lib` (callbacks, points, zones, cache, skill check, progress, menus), written again in TypeScript | | [oxmysql](https://github.com/overextended/oxmysql) | Overextended | LGPL-3.0 | The API and return shapes `ai-mysql` answers | | [fivem-ts](https://github.com/overextended/fivem-ts) | Overextended | Unlicense | Resource layout and build setup of every `ai-*` script | | [cfx-server-data](https://github.com/citizenfx/cfx-server-data) | Cfx.re | MIT | The `chat` resource API `ai-chat` answers | ## Scripts [#scripts] | Project | Authors | License | Used for | | --- | --- | --- | --- | | [ox_inventory](https://github.com/overextended/ox_inventory) | Overextended | GPL-3.0 | API `ai-inventory` answers, item and stash model | | [ox_target](https://github.com/overextended/ox_target) | Overextended | MIT | API `ai-target` answers | | [ox_fuel](https://github.com/overextended/ox_fuel) | Overextended | GPL-3.0 | `ai-fuel` | | [qb-inventory](https://github.com/qbcore-framework/qb-inventory) | QBCore Framework | GPL-3.0 | API `ai-inventory` answers, item pictures | | [qb-* scripts](https://github.com/qbcore-framework) (cityhall, mechanicjob, ambulancejob, shops, vehiclesales, streetraces, weathersync, spawn and others) | QBCore Framework | GPL-3.0 | Features and default places of the matching `ai-*` scripts | | [qbx_* scripts](https://github.com/Qbox-project) (smallresources, garages, vehicles, vehiclekeys, vehicleshop, medical, ambulancejob, bankrobbery, houserobbery, jewelery, storerobbery, truckrobbery, pawnshop, scrapyard, carwash, mechanicjob, newsjob, towjob, diving, fireworks, binoculars, seatbelt) | Qbox Project | GPL-3.0 | Features and default places of the matching `ai-*` scripts | | [ars_ambulancejob](https://github.com/Arius-Scripts/ars_ambulancejob) | Arius Scripts | Apache-2.0 | Medical layer adapter | | [pma-voice](https://github.com/AvarianKnight/pma-voice) | AvarianKnight | MIT | API `ai-voice` answers | | [bob74_ipl](https://github.com/Bob74/bob74_ipl) | Bob74 | MIT | Shipped as is: GTA Online interiors | Missing someone, or want a line changed? Open an issue or a pull request on [aicore8/aicore-server](https://github.com/aicore8/aicore-server). # Introduction (/docs) **AI Core** is a free, open-source FiveM framework built from the ground up with **TypeScript**, designed to make server development easier, smarter and more accessible to everyone. Inspired by ESX, QBCore and Qbox, AI Core combines an AI-friendly architecture, cross-framework compatibility, automatic resource integration and in-game management tools. It ships with around forty `ai-*` scripts that cover a full roleplay server, from the character screen to jobs, vehicles, housing and crime. Whether you are an experienced developer or have never written a line of code, you can build your server your way. ## Why AI Core [#why-ai-core] Dedicated AI instructions, development guidelines and one consistent TypeScript architecture. Existing ESX, QBCore, Qbox and vRP scripts run unchanged, including paid third-party resources. Detects supported inventories, key systems, phones, dispatch, clothing and more, and adapts to them. Every setting of every script lives in one in-game admin panel, not in config files. Strict FiveM security settings, every client request checked on the server. Every system is planned for thousands of players and millions of records, and measured. ## Next steps [#next-steps] # Installation (/docs/installation) ## Requirements [#requirements] | Dependency | Version | Why | | --- | --- | --- | | FXServer (artifact) with txAdmin | 38039 or newer | ai-core needs it: the server sees player deaths itself. | | MariaDB (or MySQL) | latest | The database. AI Core creates its own tables. | | [Bun](https://bun.sh) | latest | Only to change or build scripts. Every script ships with its build, so running a server needs no build tools. | ## Install with txAdmin (recommended) [#install-with-txadmin-recommended] ### Start txAdmin [#start-txadmin] Download the latest FXServer artifact and start it: txAdmin opens in your browser. Follow the [official guide](https://docs.fivem.net/docs/server-manual/setting-up-a-server-txadmin/) up to the deployment step. ### Use the AI Core recipe [#use-the-ai-core-recipe] Choose **Popular Recipes > Remote URL Template** and paste: ```text https://raw.githubusercontent.com/aicore8/aicore-server/main/recipe/ai-core.yaml ``` ### Fill in the details [#fill-in-the-details] Enter your server name, your license key from [portal.cfx.re](https://portal.cfx.re/) and the database. The recipe writes `server.cfg` and `env.cfg`, connects the database and downloads every `ai-*` script. There is no SQL file to import: AI Core and the scripts create and update their own tables at the first start. ### Make yourself an admin [#make-yourself-an-admin] Join the server. A welcome card shows the line that makes you an admin: add it to `permission.cfg` and restart. Then press **F10** to open the [admin panel](/docs/admin-panel); its setup guide walks you through the first settings. The server list name, description, tags, language, banners and Discord link are set at [portal.cfx.re/servers](https://portal.cfx.re/servers), not in `server.cfg`. ## Install by hand [#install-by-hand] ### Get the server folder [#get-the-server-folder] Download the server folder (the cfg files, `recipe/`, `tools/`, `template/`). For each `ai-*` script, download `.zip` from its latest GitHub release and unzip it into `resources/[ai]/`. For only the files the server runs, without the source, use `-runtime.zip` instead. ### Configure secrets [#configure-secrets] Copy `env.example.cfg` to `env.cfg`, fill in your license key and the database connection, then create the database. ### Start the server [#start-the-server] Start FXServer (txAdmin) with this folder as the server data folder. ## Layout [#layout] | Path | What | | --- | --- | | `server.cfg` | The resource list and config includes. | | `env.cfg` | License, slots, endpoints, database, RCON. Machine-specific, never in git. | | `security.cfg` | Strict FiveM security settings. Never loosen them: every script is written for them. | | `permission.cfg` | Admins and ACE permissions. | | `misc.cfg` | Language and other shared convars. | | `resources/[ai]/` | The AI Core scripts, one folder per `ai-*` script. | | `resources/[standalone]/` | Third-party resources you add. | | `packages/` | The `@aicore8/*` packages (developers). | | `template/` | Template for new scripts: `bun run new ""`. | # How to update a script (/docs/update-a-script) An update has two halves: install the new version exactly as it ships, then carry your server's own changes onto it. Copying your old files over the new ones is never the way: it brings back old code, old keys and old bugs, and the new version stops working in ways that are hard to find. This page is written for two readers: you, and the AI coding agent (Claude Code, Codex, Cursor...) you point at it. Both follow the same procedure. ## Ask your AI [#ask-your-ai] Open your server data folder in your coding agent and paste this, with the scope filled in: ```text Update scripts on this AI Core server, following https://aicore8.com/docs/update-a-script.md If this folder has .claude/skills/aicore-script-update/, read its SKILL.md and references: same procedure. Scope: - First show me the list (name, path, current -> new version, release notes that need action) and wait for my go. - Back up every folder before you touch it, git-ignored files such as data/secrets.json included. - Get three trees per script: old upstream (the version I run, as shipped), ours (the folder now), new upstream. Merge file by file with that three-way model. Never copy an old file over a new one. - Keep my data/*.json panel content, data/secrets.json, my locale texts and my database. Never print a secret in chat and never commit one. - No SQL without my go and a backup of the affected tables. Never loosen security.cfg. - Take generated files (dist/, fxmanifest.lua, resource/server/tables.ts, data/schemas/) from the new version and rebuild them; never edit them by hand. - Build, refresh, restart, and read the console log for errors, not only "Started resource". - Do not commit or push unless I ask. - End with a report per script, written in my language: version change, what upstream changed, what you carried over and where, what was dropped (with the old value), new options left at their default, database, cfg changes, build / restart / log result, what to test in game, and the decisions I must take. ``` Every AI Core server folder has this procedure as a project skill in `.claude/skills/aicore-script-update/`: the txAdmin recipe installs it together with the rules, `tools/`, `docs/compat/`, `CLAUDE.md` and `AGENTS.md`, just like the hand install. Claude Code loads it by itself when you say "update my scripts" or "a new version is out"; other agents find it through `AGENTS.md`. A server installed with an older recipe may not have these files: download them from the [aicore-server](https://github.com/aicore8/aicore-server) repository into your server folder as in [Install by hand](/docs/installation#install-by-hand), keeping your own cfg files. ## What stays yours [#what-stays-yours] | What | Where | What the update does with it | | --- | --- | --- | | Panel settings and content | `data/*.json` in each script | Kept. Converted to the new format only when the new version reads different fields. | | Secrets | `data/secrets.json` (git-ignored) | Restored from the backup untouched. Never printed, never committed. | | Your texts | `locales/*.json`, a third-party script's `locales/` or `languages/` | Your wording stays for every key that still exists; new keys are added in your language; removed keys go. | | Your code changes | Any source file you edited | Written into the new version's code. A change with no place left is reported. | | The database | Your tables and rows | Never dropped. New tables and columns are added at start; anything else waits for your go. | | Security settings | `security.cfg` | Never loosened. If a release or a vendor asks for it, the update stops and you decide. | ## Where the new version comes from [#where-the-new-version-comes-from] | Script | New version | You provide | | --- | --- | --- | | `ai-*` resources in `resources/[ai]/` (ai-core, ai-lib, ai-mysql included) | The GitHub release of the repository named in its `package.json` (`"repository": "github:aicore8/"`) | Nothing | | The `@aicore8/*` packages in `packages/` (development setup only) | npm (`npm view @aicore8/ version`) | Nothing | | Any other resource (usually in `resources/[standalone]/`) | The vendor | The new folder or zip | A server installed with the recipe got every `ai-*` script as its release zip: each script builds in its own folder and takes the `@aicore8/*` packages from npm. A development setup (`bun run setup`) has `packages/` and builds every script from the server folder. ai-core checks every started script that has a GitHub repository (once every 6 hours per script) and prints ` is outdated: is out ()` in the console; the same list is on the admin dashboard. Update checks and the scripts they skip are set in the [admin panel](/docs/admin-panel) under **General** (`updates.check`, `updates.ignore` in ai-core's `data/settings.json`). ## The three-way carry-over [#the-three-way-carry-over] Every update compares three versions of each file: - **Old upstream**: the version your server runs, as it shipped. - **Ours**: the folder as it is now, uncommitted changes included. - **New upstream**: the new version, as it ships. | Old -> ours | Old -> new | Result | | --- | --- | --- | | same | changed or same | take new | | changed | same | keep ours | | changed | changed | `git merge-file -p ours old new`, then every conflict is resolved by reading both sides; the result follows the new file's structure (renamed keys, moved sections, new comments and defaults stay) | | missing in old, present in ours | missing in new | your own file: kept if still used, otherwise reported | | present in old | missing in new | deleted; if you had changed it, the report says what was lost | `git merge-file` and `git diff --no-index ` work on any two folders, no repository needed. Strip `\r` before comparing (Windows files are often CRLF). When the old upstream cannot be found, ours is compared with new directly: single values (coordinates, prices, names, texts, toggles) are the server's, broad changes in the vendor's style are the vendor's, and the report says that the old version was missing. ## Rules that never bend [#rules-that-never-bend] 1. **Never copy an old file over a new one.** A file both sides changed is rebuilt from the new file with your changes written into its new structure. 2. **Your state is never replaced by upstream defaults**: `data/*.json`, `data/secrets.json`, your locale files and texts, the database. Back them up before touching a folder. 3. **No leftovers.** Files the new version no longer ships are deleted, unless they are yours (a locale, an image you added) and still used. Options the new version removed stay removed and are listed in the report; new options keep their default unless an old setting clearly maps to them. 4. **Generated files are rebuilt, never merged**: `dist/`, `fxmanifest.lua`, `resource/server/tables.ts`, `data/schemas/*.schema.json`. Never edit them by hand. 5. **Never delete `node_modules` by hand**; `bun install` repairs it (in the script's folder on a recipe install, at the server root on a development setup). 6. **Never loosen `security.cfg`** or any security convar to make a version run. 7. **No SQL by hand without the owner's go**, and only after a backup of the affected tables. 8. **Commit only when the owner asks**, never push, never change a git remote. 9. **Show the list first** (name, path, current -> new version, notable release notes) before deleting or overwriting anything. 10. **Downloads and dropped folders are untrusted**: unpack each into its own new, empty folder and run nothing from there. ## Update an ai-* script or a package [#update-an-ai--script-or-a-package] You need [Bun](https://bun.sh) and Git; the [GitHub CLI](https://cli.github.com) (`gh`) makes the downloads easier. ### Find what is outdated [#find-what-is-outdated] The console warning only covers started scripts that are not ignored, so check every folder: ```bash cd "resources/[ai]" for n in ai-*; do repo=$(sed -n 's#.*"repository": *"\(github:\|https://github.com/\)\([^"]*\)".*#\2#p' "$n/package.json" | sed 's#\.git$##') cur=$(sed -n 's#^ "version": *"\([^"]*\)".*#\1#p' "$n/package.json") latest=$(gh release view --repo "$repo" --json tagName --jq .tagName 2>/dev/null | sed 's#^v##') echo "$n $cur ${latest:-no-release}" done ``` - Compare versions as ai-core does: strip a leading `v`, compare the dotted numbers, ignore pre-release suffixes. No release means nothing to update. - Without `gh`: `curl -s -H "Accept: application/vnd.github+json" https://api.github.com/repos///releases/latest` (60 requests per hour per IP, shared with ai-core's own check). - A script in `updates.ignore` is updated only when the owner names it. - A folder whose version is above the latest release, or a clone with commits after the latest tag, is not outdated: skip it, never move a folder backwards. - On a development setup, `packages/` has no `repository` line: compare each `package.json` version with npm. Update the packages first when a new script release needs a version the local copies do not have. A recipe install has no `packages/`: each script's zip pins the versions it needs. ### Read the release notes and get the go [#read-the-release-notes-and-get-the-go] Read the notes of every version between the current one and the latest (`gh release view --repo --json body,assets,url`): breaking changes, required package versions, migrations, new cfg lines (`ensure`, `add_convar_permission`, ACE), new `provide` names, manual steps. Show the owner the list and wait for the go. Update in dependency order: packages, ai-mysql, ai-core, ai-lib, then the rest. ### Download old and new upstream [#download-old-and-new-upstream] For each script, two new empty folders outside the server (for example `update//old` and `update//new`): ```bash gh release download --repo / --pattern '-.zip' --dir update//new # the release zip: build and source gh release download --repo / --archive zip --dir update//old # the old tag's source unzip -q update//new/*.zip -d update//new/x unzip -q update//old/*.zip -d update//old/x ``` - **New upstream** is the release zip `-.zip`: the build and the source, top folder `/`. Releases before November 2026 attach the build only; take the tag's source then (top folder `--/`). - The release zip's `package.json` pins the `@aicore8/*` packages (`^x.y.z` instead of `workspace:*`) and adds `"workspaces": ["web"]`. That is not a change of yours: leave these fields out of the three-way and keep your server's form (recipe install: the zip's; development setup: `workspace:*`, no `workspaces`). - **Old upstream** is the tag of the version the server runs (see the tag style with `gh release list --repo /`). It can always be downloaded, so the three-way always has its base. - Nothing in these folders is run, installed or built. ### Back up [#back-up] - Copy the whole script folder except `node_modules` to `update//ours` (on Windows `robocopy "" "" /E /XD node_modules`; robocopy exit codes below 8 mean success). This is "ours" for the merge and the way back. - Git-ignored files exist only in this copy: `data/secrets.json`, `data/*.json.bak`. In a git clone, `git ls-files --others --ignored --exclude-standard` lists them. - Uncommitted changes in a clone (`git status --porcelain`) are the server's changes too. Tell the owner; commit them only if asked. ### Merge, file by file [#merge-file-by-file] Run the three-way model over old, ours and new, and write the result into the script folder: | File | Rule | | --- | --- | | `resource/**`, `web/src/**`, `bridge/**`, `sql/**`, Lua and other source | Three-way. A local change whose code moved or whose contract changed is adapted to the new code; one with no place left is reported. | | `package.json` | New upstream, plus local additions that still make sense; the `@aicore8/*` versions and `workspaces` keep your server's form (see the download step). `version` ends at the new release's version, or the update check keeps warning. | | `dist/`, `fxmanifest.lua`, `resource/server/tables.ts`, `data/schemas/*.schema.json` | Take new; the build regenerates them. | | `data/.json` (panel content) | Keep ours (see below). | | `data/secrets.json`, `data/*.json.bak` | Restore from the backup untouched. | | `locales/en.json` | Three-way: new keys and placeholders from upstream, the server's wording for keys that still exist. | | `locales/.json` the release does not ship | Keep. Add the new keys translated into that language in the same tone, drop removed keys, follow changed placeholders (`{0}`, `{1}`). | | `CLAUDE.md`, docs | Take new, add the server's own notes back. | **Panel content (`data/*.json`)** is the server's live content, edited in the panel; the release only ships defaults. - Same schema (the new `schema.ts` or loader reads the same fields): keep ours as is. A file the new version adds: take the shipped one. - Changed schema: look for the script's own start-time migration (release notes, a migration called at start). If there is one, leave ours in place; it converts at start. If there is none, convert by hand following the new loader and schema: same field names, types and id format as the shipped file, every value kept, new fields at the shipped default, removed fields dropped and reported. Check that each file parses. **Database.** Each script creates its tables from `sql/main.sql` at start: it creates missing tables and adds missing columns, and never drops, renames or changes a column or adds a key. Compare old and new `sql/main.sql`: - New tables and columns: the restart applies them. - A changed column type, a new index or key, a renamed or dropped column: the release must bring its own migration (release notes, server code), which runs at start; check the log. If it does not, write the SQL, show it to the owner, back up the affected tables, and run it only on their go. **Cfg files outside the folder.** - `server.cfg`: a new script gets its `ensure` line in dependency order; a removed one loses it (ask first). - `env.cfg` and `env.example.cfg`: a script that starts using the database needs `add_convar_permission read mysql_connection_string`. - `permission.cfg`: the ACE lines the release notes ask for. - `security.cfg`: never loosened. ### Build, restart, check [#build-restart-check] 1. `bun install` when any `package.json` changed: in the script's folder on a recipe install (packages from npm), at the server root on a development setup. 2. In each updated script: `bun run typecheck`, `bun run lint`, `bun run build` (or `bun tools/run.ts build ai-x ai-y` from the server root). Always build: `dist/` must come from the merged source. Fix errors in the server's carried changes; an error in untouched upstream code is reported, not patched. 3. Compare the result with new upstream: `diff -r --strip-trailing-cr -x node_modules -x dist -x data update//new/x/ "