How to update a script

Find what is outdatedCopy Anchor Link

The console warning only covers started scripts that are not ignored, so check every folder:

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/<owner>/<name>/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.
• 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.

Read the release notes and get the goCopy Anchor Link

Read the notes of every version between the current one and the latest (gh release view <tag> --repo <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 upstreamCopy Anchor Link

For each script, two new empty folders outside the server (for example update/<name>/old and update/<name>/new):

gh release download <tag> --repo <owner>/<name> --archive zip --dir update/<name>/new     # the tag's source
gh release download <tag> --repo <owner>/<name> --pattern '*.zip' --dir update/<name>/new # a release asset, when there is one
unzip -q update/<name>/new/*.zip -d update/<name>/new/x

• Prefer a release asset when the release has one; otherwise the tag's source (it includes the committed dist/ and fxmanifest.lua). The source zip's top folder is <owner>-<name>-<sha>/.
• Old upstream is the tag of the version the server runs (see the tag style with gh release list --repo <owner>/<name>). It can always be downloaded, so the three-way always has its base.
• Nothing in these folders is run, installed or built.

Back upCopy Anchor Link

• Copy the whole script folder except node_modules to update/<name>/ours (on Windows robocopy "<src>" "<dst>" /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 fileCopy Anchor Link

Run the three-way model over old, ours and new, and write the result into the script folder:

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 <resource> read mysql_connection_string.
• permission.cfg: the ACE lines the release notes ask for.
• security.cfg: never loosened.

Build, restart, checkCopy Anchor Link

1. bun install at the server root when any package.json changed.

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/<name>/new/x/<top> "<script folder>". Every remaining difference must be one of the server's changes.

4. Refresh and restart:

   Copy Text

   bun tools/rcon.ts --log ../default/logs/fxserver.log --wait 3 "refresh"
   bun tools/restart.ts --from ai-inventory   # one script
   bun tools/restart.ts                       # after ai-core, ai-lib, ai-mysql or a packages update

   bun tools/restart.ts restarts ai-core, ensures every ai-* after it and checks that each one started. Third-party scripts that depend on ai-mysql stop with it: ensure them again by name. A new provide line needs a full server start: bun tools/rcon.ts "quit \"<reason>\"".

5. Read the console log for SCRIPT ERROR, Failed to load script, [client error], panel load or validation errors and database errors, not only Started resource. The is outdated warning must be gone after the script's next check.

Match the drop to what is installedCopy Anchor Link

• Each top-level folder with an fxmanifest.lua (or __resource.lua) is a resource; a [category] folder holds several. Unpack zips into a new, empty folder and run nothing from it.
• Find the installed copy by folder name inside resources/ (for example find resources -maxdepth 3 -type d -name <name>). Keep the installed location, not the drop's category. No match or several matches: ask the owner. A script that is not installed yet is installed only when the owner says so.
• An ai-* folder in the drop is not this flow: ai-* scripts update from GitHub (above). Ask the owner what the folder is.
• Read both manifests: version, files, scripts, dependencies, provide, escrow_ignore, ai_replaces. A version that goes down, or a drop that misses files the installed copy has, may be an older build: compare and report instead of installing.
• New dependencies: oxmysql is answered by ai-mysql (never install oxmysql next to it); ox_lib and other libraries are the owner's to install; a dependency on something ai-core stands in for (es_extended, qb-core, qbx_core, pma-voice, ox_inventory...) is already met.
• Show the matched list (name, path, current -> new version) and wait for the go.

Back upCopy Anchor Link

• Copy the whole installed folder to a backup folder outside the server (robocopy "<src>" "<dst>" /E). For a folder no git repository tracks, this backup is the only copy of the server's version.
• If git tracks the folder: git status --porcelain -- <path> shows uncommitted changes (they count as ours; tell the owner) and git ls-files --others --ignored --exclude-standard -- <path> shows git-ignored runtime files (saved JSON, caches), which are in the backup.

Find the server's changesCopy Anchor Link

Get the old upstream, in this order:

1. The owner still has the old vendor zip or folder.
2. An open-source script on GitHub: the release or tag of the installed version.
3. Git history, when the folder is tracked: the commit that set the installed version (git log -S"version '<old>'" -- <path>/fxmanifest.lua). If that commit also re-applied earlier customizations, its config files count as ours and the pure stock is one commit earlier.
4. None: compare ours with the new version directly, and say so in the report.

Then read every difference old -> ours (the server's edits: configs, locales/* or languages/*, editable files, data/*.json, fxmanifest.lua, SQL, images, sounds, streamed files, code patches) and old -> new (the vendor's changes: added and removed files, renamed keys, moved sections, changed editable functions). In an escrowed script (.fxap present) only the files in escrow_ignore can be read and edited; an edit in a file the new version escrows cannot be carried and is reported.

Install the new versionCopy Anchor Link

Delete the installed folder completely, then copy the new folder to the same path, hidden files (.fxap) included. Old leftovers are bugs; the old version stays in the backup. Restore backed-up runtime files only if the new version still uses them in the same format; otherwise convert or drop them and report.

Re-apply the server's changesCopy Anchor Link

For each edit, find where that setting lives in the new version and write the value there, in the new format:

• Same key, same file: set the value in the new file; keep its comments and layout.
• Renamed or moved key: find the new key by reading the code that uses it (search for the old name, its comment, its default, its text key) and convert the value to the new shape.
• Config moved to a data file (JSON edited by the script's own panel): read the new loader and the shipped file, write the old values in that exact schema (field names, types, id format, indentation), check that it parses. Do not rely on a converter the script may run.
• The server's existing data files: carry them over, convert field by field if the schema changed, never replace them with the vendor's sample.
• Removed option: no code reads it any more (a search confirms): drop it and report it with the old value.
• Editable files (client/editable.lua, server/editable.lua...): start from the new file and re-apply each changed function body, adapted to a changed signature or return value; new functions keep their default.
• Languages: keep the server's wording for every key that still exists; add new keys to every language file the server uses, translated in the tone of the existing texts; drop removed keys; follow changed placeholders.
• fxmanifest: the new one, plus only the server's own additions that still make sense. Never change version.
• SQL (*.sql, install folders): compare old and new; new tables, columns and indexes go into the report as SQL for the owner to run. Nothing runs without the owner's go.
• Credentials (bot tokens, API keys, webhook URLs in configs): never print them. Carry them from the backup; if that is not possible, leave the new default and list the file and key for the owner.
• Assets (stream/, images, sounds): the vendor's, plus files the server added that are still used.
• Coordinates, items, prices, texts and behaviour are carried exactly; nothing beyond the server's own edits changes.

Check ai-core compatibilityCopy Anchor Link

The script may be one ai-core talks to. Find every place that names it:

grep -rln "<name>" "resources/[ai]/ai-core/resource" "resources/[ai]/ai-core/bridge" docs/compat

• For every export, event and callback an adapter uses, check the new version: still there, same arguments, same return shape, same timing. In escrowed code, check the readable files and the vendor's docs, and list what cannot be verified.
• A mismatch is fixed in the adapter file only (a thin translation), with its tested version raised; then typecheck, lint and build ai-core and restart it (bun tools/restart.ts).
• A new ai_replaces or provide line can make ai-core refuse joins while an ai-* stand-in still runs (see Replacing an ai-* script): name the folder the owner must remove.
• Update docs/compat/<script>.md (tested version, status, exact config or patch, known limits); a supported script without a note gets one.

Verify and restartCopy Anchor Link

• Compare the installed result with the new version: every difference is one of the server's changes, and no old file remains that the new version does not ship (restored runtime files aside).
• Edited Lua parses, JSON parses, every config key that was set exists in the new code.
• Unless SQL is waiting for the owner: bun tools/rcon.ts --log ../default/logs/fxserver.log --wait 3 "refresh", then the same with "ensure <name>", and read the log for SCRIPT ERROR, Failed to load script and the script's own errors. Scripts that depend on it and were stopped are ensured again.