Script Config

The scriptConfig module provides a full configuration system for resources — JSON Schema-driven defaults, database persistence, admin UI, live watchers, change history, and optimistic concurrency.

For the React/NUI admin panel side of this system, see dirk-cfx-react → Script Config.

#Full Setup Guide

Setting up scriptConfig in a new resource requires files on three layers: schema, Lua, and React. This section covers the schema and Lua layers. The React layer is covered in the dirk-cfx-react docs.

#1. Create Your Schema

Create a schema.json in your resource root. This JSON Schema defines every configurable setting, its type, and default value.

json
{
  "type": "object",
  "properties": {
    "basic": {
      "type": "object",
      "properties": {
        "debug": { "type": "boolean", "default": false },
        "interactionType": { "type": "string", "default": "target" },
        "maxPlayers": { "type": "number", "default": 32 },
        "secretKey": {
          "type": "string",
          "default": "changeme",
          "x-serverOnly": true
        }
      }
    },
    "rewards": {
      "type": "array",
      "x-arrayKey": "name",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "label": { "type": "string" },
          "amount": { "type": "number", "default": 1 }
        }
      }
    }
  }
}

You can optionally create a defaults.json with initial default values. If omitted, defaults are derived from the "default" fields in the schema.

#2. Set Up Your fxmanifest.lua

lua
fx_version 'cerulean'
game 'gta5'

shared_scripts {
  '@dirk_lib/init.lua',
  'src/shared/*.lua',
}

client_scripts {
  'src/client/*.lua',
}

server_scripts {
  '@oxmysql/lib/MySQL.lua',
  'src/server/*.lua',
}

ui_page 'web/build/index.html'

files {
  'web/build/**',
  'schema.json',
  'defaults.json',
  'locales/*.json',
}

#3. Register on the Server

Create src/server/scriptConfig.lua:

lua
CreateThread(function()
  lib.scriptConfig(schema, function(src)
    return IsPlayerAceAllowed(src, 'admin')
  end)
end)

That single call handles everything:

1. Waits for MySQL to be ready
2. Creates the dirk_scriptConfig DB table if needed
3. Loads stored settings from the database
4. Smart-merges with schema defaults (schema is always source-of-truth)
5. Computes a content-hash version for cache invalidation
6. Fires all registered watchers with source = "initial"
7. Registers all NUI callbacks for the admin panel

#4. Set Up the Client

Create src/client/scriptConfig.lua:

lua
local _ = lib.scriptConfig  -- triggers lazy-load + KVP cache

The client:

1. Checks the resource KVP cache for a fast-path load
2. Calls the server with its cached version number
3. If the server has a newer version, receives the delta and merges locally
4. Caches updated settings to KVP for next startup
5. Fires any registered client-side watchers

#5. Add Watchers (Server)

Register watchers in your server files to react to settings changes in real-time:

lua
-- src/server/init.lua
lib.scriptConfig.on('rewards', function(rewards)
  registerRewardItems(rewards)
end)

lib.scriptConfig.on('basic', function(basic)
  if basic.debug then
    RegisterCommand('debugMyResource', function(src)
      -- debug command logic
    end, true)
  end
end)

-- Wildcard: react to ALL changes
lib.scriptConfig.on('*', function()
  regenerateConfigFiles()
end)

#6. Add Watchers (Client — Optional)

lua
-- src/client/controls.lua
lib.scriptConfig.on('basic', function(basic)
  local controls = basic.defaultControls or {}
  RegisterKeyMapping('+myAction', 'Do Something',
    controls.main?._type or 'keyboard',
    controls.main?._key or 'E')
end)

#7. Access Settings Anywhere

Read settings directly in any server or client file:

lua
-- Direct access (available after init)
local debug = scriptConfig?.basic?.debug
local rewards = scriptConfig?.rewards or {}

-- Via getter
local value = lib.scriptConfig.get('basic.maxPlayers')

lua
-- src/shared/utils.lua
function getLiveBasic()
  return scriptConfig?.basic or {}
end

#8. There is no step 8

You do not build an admin panel. Config Studio draws yours from schema.json — sections, controls, row editors, validation, history and the save bar all come out of the schema, and /<yourResource> opens the shared panel with your script selected.

So the work that used to be a React app is now schema work: see Schema Extensions for the vocabulary, and Your own control / Your own page for the two escape hatches when a screen is genuinely yours to draw.

createScriptConfig in dirk-cfx-react is still what your own UI reads settings through at runtime — that has not changed. It is only the admin surface that dirk_lib now owns.

#API Reference

#Client

#scriptConfig.get

Returns the current settings. Also callable via scriptConfig.().

lua
local settings = scriptConfig.get()
-- or
local settings = scriptConfig.()

#scriptConfig.on

Watch for settings changes. Returns an unsubscribe function.

lua
local unsubscribe = scriptConfig.on('basic', function(newValue, oldValue, meta)
    print('basic settings changed', meta.path)
end, { immediate = true })

-- Stop watching
unsubscribe()

immediate defaults to true — the callback fires immediately with the current value if settings are already loaded. once auto-unsubscribes after the first fire.

Path matching rules:

• Exact match: Watch "basic", triggered by "basic" change
• Parent match: Watch "basic", triggered by "basic.debug" change
• Child match: Watch "basic.skillSettings", triggered by "basic" change
• Wildcard: "*" catches all changes

Watcher meta table:

#scriptConfig.set

Update settings (admin only). Sends the change to the server.

lua
scriptConfig.set({ basic = { debug = true } }, expectedVersion)

#scriptConfig.getAll

Get the full unfiltered settings (admin only).

lua
local allSettings = scriptConfig.getAll(source)

#Server

#scriptConfig.(schema, canEditFn?, rules?)

Initialise the settings system. Call once during resource start. Creates the DB table, loads persisted data, and smart-merges with schema defaults.

lua
lib.scriptConfig(schema, function(src)
    return IsPlayerAceAllowed(src, 'admin')
end, {
    migrations = {
        ['1.2.0'] = function(data)
            data.basic.newField = data.basic.oldField
            data.basic.oldField = nil
            return data
        end,
    },
})

Save permission is gated by the master ACE list (dirk_lib_master_group convar), the access block your schema pushes, and the dirk_admins rows first. Your canEditFn only fires as a fallback when all of those deny. If you want to let a non-master role edit just your resource, add them on the Admins page in /dirk_config and scope the grant to your script — that survives in the database and needs no code change.

Access resolves in this order, and stops at the first true:

1. the master group — dirk_lib_master_group convar, default group.admin. Always edit, and can never be locked out.
2. the access block your schema pushes — predates levels, so it means edit. It is also folded into the Admins page the first time your resource registers, so a grant made in a file can afterwards be revoked from the panel.
3. rows on the Admins page (dirk_admins), which name either a player identifier or an ACE principal, at edit or view level, optionally scoped to particular scripts. An empty scope means every script.
4. your own canEditFn.

view may open your script and read its settings and nothing else — no server-only values, no saves, no give-item. The rows live in their own dirk_admins table rather than in dirk_scriptConfig: storing the access list inside the thing it guards means a bad write locks everyone out of the panel that would fix it.

#exports.dirk_lib:canEditScriptConfig(src, resourceName)

Authoritative server-side permission check. Returns true if the player can edit the named resource's scriptConfig (master ACE list + overrides + the consumer's own canEditFn). Useful when you want to gate a custom admin command or feature with the same access model dirk_lib uses internally.

lua
if exports.dirk_lib:canEditScriptConfig(source, GetCurrentResourceName()) then
    -- show admin-only menu, run admin command, etc.
end

#Rules

lua
rules = {
    migrations = {
        ['1.2.0'] = function(data) return data end,
    },
}

migrations is the only key. Version-keyed functions run once when the stored resource_version is older than the key.

#Schema Extensions

The schema is the single source of truth. It decides what a setting is, which control edits it, where it appears, when it applies, and whether it is valid — so a new resource ships a schema.json and gets a complete admin panel with no changes to dirk_lib.

Declare the shape

An array of objects should say what its rows contain:

json
"stores": {
  "type": "array",
  "x-arrayKey": "id",
  "items": {
    "type": "object",
    "properties": {
      "id":          { "type": "string" },
      "name":        { "type": "string" },
      "lvlRequired": { "type": "integer" }
    }
  },
  "default": [ ... ]
}

Without items.properties the panel works out the columns from the rows you ship, and that is a guess with two failure modes worth knowing about:

• A field only some rows carry. Columns come from the whole list, so a field one row uses does get a column — but its type is read from a row that has a value for it. Ship a level requirement on four stores out of eight and it is fine; ship it as "10" on one and 10 on another and the panel has to pick.
• An emptied list. Delete every row and the shipped defaults still describe it, but a list that ships empty describes nothing at all.

A declared items schema removes both. It also gives every field somewhere to hang its own annotations, rather than pushing them into x-rowControls and x-validateRows on the array.

An object whose keys are data is a map, not a record — say so, or the fields that happen to be in your defaults get read as the only ones allowed:

json
"perFishModifiers": {
  "type": "object",
  "description": "Per-species overrides, keyed by fish name.",
  "additionalProperties": {
    "type": "object",
    "properties": {
      "abundanceModifier": { "type": "number" },
      "weightModifier":    { "type": "number" }
    }
  }
}

Storage & migration

Items & installation

Weight is not optional in practice. A list gives its items a weight one of two ways:

• "weight": 500 — one value for every item in the list. Right for hooks, lines, bait.
• "weightField": "weight" — read it from each row. Right where the row already states it: a 50g sinker weighs 50, a fish weighs what its weightLimits say.

weightField wins when the row actually carries that field, and falls back to the fixed weight when it does not — so a list can set both and let the rows override.

Declare neither and every item is generated at weight 0, silently. dirk_fishing shipped 90 weightless rods, reels, hooks and bait that way: the generator was doing exactly what it was told, and nothing said otherwise until someone noticed the inventory column was empty.

Layout

How the panel is arranged. Without these a script still works — every top-level block becomes one section — but a block holding thirty unrelated settings becomes an endless scroll.

json
{
  "x-sections": [
    { "id": "general", "label": "General", "icon": "sliders-horizontal",
      "description": "Server-wide behaviour and units.",
      "paths": ["basic.debug", "basic.weightUnit", "basic.distanceUnit"] },
    { "id": "permits", "label": "Permits", "icon": "scroll-text",
      "paths": ["basic.permitItem", "basic.permitPrice", "basic.permitRevokers"] }
  ],
  "x-mapPaths": ["zones", "seaBoundary"],
  "properties": {
    "fish": {
      "type": "array",
      "x-arrayKey": "name",
      "x-rowTabs": [
        { "id": "general", "label": "General", "icon": "general", "keys": ["name", "label", "description"] },
        { "id": "stats",   "label": "Stats",   "icon": "stats",   "keys": ["biteChance", "weightLimits"] }
      ]
    }
  }
}

Conditions

x-enabledWhen and x-validate share one condition grammar, because "should this be editable?" and "is this valid?" are both statements about values. There is no need for a custom component to express a comparison.

x-enabledWhen

Greys a setting out, with the reason, while its condition is unmet. Put it on a block and every field inside inherits it — which is what a master switch means. The field a rule points at is never disabled by its own rule.

json
"theme": {
  "type": "object",
  "x-enabledWhen": { "path": "theme.useOverride", "equals": true },
  "properties": { "useOverride": { "type": "boolean", "default": false } }
}

A gated-off setting is also skipped by validation — demanding a webhook URL for logging that is switched off would block every save.

x-validate

Most validation needs no extension at all: minimum, maximum, minItems, enum and required are plain JSON Schema and are enforced. Use x-validate for the two things JSON Schema cannot say — a range that runs backwards, and "required, but only when".

json
"weightLimits": {
  "type": "array", "minItems": 2, "maxItems": 2,
  "x-validate": [{ "must": { "ascending": true }, "message": "ErrWeightMinMax" }]
},
"permitPrice": {
  "type": "number",
  "x-validate": [{
    "when": { "path": "self.permitRequired", "equals": true },
    "must": { "isSet": true },
    "message": "ErrPermitPriceRequired"
  }]
}

message is resolved through the resource's own locale bundle first, so a key like ErrMinMax is translated; anything unknown is shown verbatim. Failures show on the row, disable Save, and are summarised in the save bar with a jump to the offending section.

x-validateRows on an array carries rules for arrays that declare no items schema (their shape coming from the default rows). Keys may be dotted to reach a nested table:

json
"stores": {
  "type": "array",
  "x-validateRows": {
    "stock.variance": [{ "must": { "ascending": true }, "message": "ErrVarianceMinMax" }]
  }
}

Validation goes all the way down. A row is not flat, so neither is the check. required, x-validate and x-enabledWhen are applied at every depth, on save as well as while you type, through all three nested shapes:

Only the top level used to be checked, so a store with six nameless stock rows counted as valid: the inner table was non-empty, and nothing looked inside it.

required reaches a nested column too — list the field in the inner items.required array and it is enforced on every row of that inner table:

json
"stores": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "stock": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["item", "price"],
          "properties": {
            "item":  { "type": "string", "x-itemPicker": true },
            "price": { "type": "integer", "minimum": 0 }
          }
        }
      }
    }
  }
}

Messages say where, so a failure deep in a row is findable: Stock #4: Item is needed, joined with › for anything deeper. The row editor opens on the tab that holds the first problem rather than on whichever tab you were looking at — a row saves whole, so a problem hiding on another tab still blocks it.

Controls

The control is inferred from the schema — type, bounds, key name and value shape — so most fields need no annotation at all. Declare only what inference cannot know.

The three vector flags are one control with three shapes. The picker always produces four numbers — a player always has a height and a heading — and the field trims what it keeps, so a flat corner never grows a z and a w that nothing reads and every diff shows. Undeclared, the shape is counted from the field's own properties (or its default), so an existing {x,y,z,w} block needs no annotation.

Set is a real in-game flow, not a form: the panel hides, an instruction card appears, you walk to the spot and press E (Backspace cancels). It runs through lib.adminTool, which is gated on the panel actually being open — so neither Set nor Goto is reachable from CEF devtools with the panel shut.

When a field declares x-enumIcons / x-enumColors, the picker stops being a dropdown of words and becomes a grid of the real pins — for a place category the colour and icon are the setting. The same styling draws that row's marker on the map, so the admin map matches what players see.

Every control

x-control (and x-rowControls) accept any of these. Most fields need none of them — inference covers the common shapes — but nothing here can be guessed reliably, so declaring is always allowed and never wrong.

Text and numbers

Meters — a bounded number, drawn as the thing it actually means. Same value, different vocabulary, so the reader is told what "high" does:

Choices

Things in the game world

Blips

Appearance

Input

Structured

Discord — both read the bot configured in dirk_lib's own Discord settings:

Row-level controls

A row inside a list is still a field, but there is often nowhere to annotate it: several arrays describe themselves through their default rows rather than an items schema. These say it on the array instead.

"both" gives the picker a Lucide / Font Awesome switch and lets one field hold either. It is safe because the stored value already says which set it came from: Font Awesome writes fa-solid fa-fish, lucide writes a bare fish. Nothing has to be migrated, and no second field records the choice.

The catch is on your side, not the panel's. A field declared "both" can arrive at your UI in either spelling, so whatever draws it must read the value rather than assume a library — the way dirk_lib's own AnyIcon does. Declare "both" only where your renderer handles both; a renderer wired to one library draws a silent blank for every icon picked from the other. | x-action | object | A button beside the field that does something: { label, callback, icon?, sendSection? }. callback names a server callback on your own resource, without its <resource>: prefix. sendSection: true sends the whole section's staged values rather than just this field. See Actions below. |

Your own control or page

x-rowControls long form. A bare string names the control. An object says more, which matters when the array has no items schema and there is nowhere else to put it:

json
"x-rowControls": {
  "description": "text",

  "type": {
    "control": "enum",
    "options": [
      { "value": "equipment",  "label": "Equipment store" },
      { "value": "fishMarket", "label": "Fish market" }
    ]
  },

  "stock.category": {
    "control": "pickOne",
    "optionsFrom": { "path": "parent.categories", "key": "name" },
    "anyLabel": "Uncategorised"
  },

  "icon": { "control": "icon", "iconSet": "fontawesome" },

  "permitPrice": {
    "control": "integer",
    "enabledWhen": { "path": "self.permitRequired", "equals": true }
  }
}

Your own control

Built-in controls cover the shapes every script shares. When one genuinely does not fit, a resource can ship its own:

jsonc
"places": { "x-component": "web/build/studio/places-map.js" }

The panel imports it at runtime from nui://<resource>/<path> — the same scheme it already uses for item images — and renders it inline in the section, inside its own React tree. It therefore inherits the theme, the fonts, the scroll and the save bar; it is not an iframe and needs no message plumbing.

Author it as .tsx and build it to that path. React, Mantine, lucide, framer-motion and dirk-cfx-react must be external, mapped to window.__dirkStudio.* — two copies of React on one page breaks hooks, and it keeps the file at kilobytes instead of megabytes.

Anything holding a React context has to be shared for the same reason, not just React itself. That now includes React Query: a component bundling its own copy reads its own client, with no provider above it, and every hook throws.

js
// vite.config — build.lib, formats: ['es']
rollupOptions: {
  external: [
    'react', 'react/jsx-runtime', '@mantine/core', 'lucide-react',
    'framer-motion', 'dirk-cfx-react', 'react-leaflet', 'leaflet', 'react-dom',
    '@tanstack/react-query', '@tanstack/react-virtual',
  ],
  output: { globals: { react: 'window.__dirkStudio.React', /* ...etc */ } },
}

Default-export a component taking { value, onChange, canEdit } — the same props the map layers already take. onChange stages the value like any other edit: the save bar counts it, Undo steps through it, and nothing writes until Save.

A control standing in for a list is also handed openRow, addRow and deleteRow. Use them: the panel already builds a row editor from your schema, honours x-rowTabs, validates, and offers the item and coordinate pickers. Draw the list however your data deserves — a wall of fish with their images — and hand editing back. Re-implementing the form per script is the sprawl this whole design exists to stop.

Two more props come with it: t(key, fallback) resolves against your own locales/*.json, so your control has no untranslatable corner; and notify(kind, message) raises the panel's toast, which anything with an immediate effect needs or the button looks broken whether it worked or not.

Requirements and behaviour:

• the file must be under web/build/, and listed in your fxmanifest files{}
• Define process.env.NODE_ENV away at build time (define: { 'process.env.NODE_ENV': '"production"' }). A bundle that leaves the reference in dies on its first line in a browser. The panel shims a minimal process as a safety net, but relying on it is asking for trouble.
• window.__dirkStudio.version is the contract version (currently 6); check it if you want to fail loudly on a future React major rather than halfway through a render
• react-leaflet and leaflet are shared too, for the same reason React is: leaflet's hooks read a context that <Map> provides, so a component bundling its own copy gets a different one and useMap() returns null
• a component that fails to load, or throws while rendering, is caught and replaced with a message naming the resource, the file and the reason — it cannot take the panel down
• failures are not cached, so restarting the resource retries

The panel does not guess from field NAMES. There used to be a run of rules that picked a control from what a key was called — /account$/ meant an account picker, /model$/ a model picker. They were wrong in ways nothing in the schema could predict: maxBackupsPerAccount is a number and got an account picker. They are gone.

What is left derives mostly from the DATA, which is a fact rather than a guess: a hex string is a colour, a {_key} object is a keybind, rows with an x and a y are pins on a map, an enum is a select. Four name rules survive, listed below, because nothing in the value could say it. Anything else declares x-control.

What inference already handles, so you do not annotate it:

Four rules still read the field name, because the value cannot say it:

Actions

x-validateWith asks a passive question on every debounced keystroke. Some things are not questions: "Test webhook" posts a real message into a real Discord channel, and firing that while someone types a URL fills the channel with test messages.

So an action is a button, and it happens when asked:

json
"webhookUrl": {
  "type": "string",
  "x-control": "secret",
  "x-serverOnly": true,
  "x-action": {
    "label": "Test webhook",
    "callback": "admin:testWebhook",
    "icon": "send",
    "sendSection": true
  }
}

callback names a server callback on your own resource. dirk_lib prefixes it with your resource name and forwards it — a page can only ever reach the script that declared it, and your permission check still runs on the far side.

sendSection: true sends every setting in that top-level block, keyed as your script knows them (logging.webhookUrl arrives as webhookUrl), plus value. Testing a webhook posts a preview of the events that are switched on, so the URL alone does not say what to send. Values are the ones staged in the panel, not the saved ones — pressing Test checks what is in the box.

Return { success } or { ok }. Add message for what the panel should say — "Sent 3 of 4 event previews" beats "worked" — and error for why not.

lua
lib.callback.register('dirk_fishing:admin:testWebhook', function(src, data)
  if not lib.scriptConfig.hasPerm(src) then
    return { success = false, error = 'NoPermission' }
  end
  ...
end)

Lending the screen to your script

Some things a page wants to show are not a value: "play this intro", "run this scene". That is your script's own code, and the panel just has to get out of the way while it runs — otherwise it plays behind a full-screen panel that still holds the mouse, and closing the panel to watch throws away whatever was staged.

The handOff admin tool does exactly that. From your component:

ts
const begin = useAdminToolStore((s) => s.begin);
const done = begin({ id: 'handOff', title: 'Playing the intro', keys: [{ key: '⌫', action: 'Stop' }] });
fetchNui('ADMIN_TOOL_BEGIN', { id: 'handOff', instructions, timeoutMs: 300000 });
const reply = await fetchNui('STUDIO_REQUEST', { resource, callback: `${resource}:studio:playIntro`, payload });
if (!reply?.success) {                       // nothing will run, so nothing will hand back
  useAdminToolStore.getState().cancelActive();
  fetchNui('ADMIN_TOOL_INVOKE', { id: 'handOffCancel' });
}
await done;                                  // the panel is back

Arming the store is what hides the panel; ADMIN_TOOL_BEGIN hands the mouse to the game. Your server callback checks permission and tells your client what to do, and when it is over your client gives the screen back, from any resource:

lua
TriggerEvent('dirk_lib:studioHandBack', { played = true })

The panel returns exactly as it was left. A script that never hands back cannot strand anyone: after timeoutMs (default two minutes) the panel comes back on its own with { timedOut = true }. Add useAdminToolStore to your studio build's cfx-react name list. Reference: dirk_multichar's backstory cards.

Your own page

x-component covers a control standing in for one setting. Some screens are not settings at all: a players list reads live server data, pages through it and acts on it. There is nothing in the config for it to be, and inventing a fake entry just to have somewhere to mount it puts a setting in your schema that is not one.

json
"x-pages": [
  { "id": "players",
    "label": "Players",
    "icon": "users",
    "component": "web/build/studio/players.js",
    "description": "Everyone who has fished, and their pots and permits." }
]

It appears in the rail under your script, in your script's accent colour, below What's new and above every section — because a page is a place you go, not a setting you tune, and burying it under fourteen sections hides it. Pages are listed in the order you declare them, so the one you most want found goes first. dirk_lib supplies the frame, the theme, the loader and a React Query client; the component gets { resource, canEdit, t, notify, onBack }.

A page that wants the whole window

A settings pane is a column beside a rail. A canvas is not. Add "full": true and opening the page grows the Config Studio window itself to the screen, folds the rail away, and puts a back arrow in the header:

json
"x-pages": [
  { "id": "designs",
    "label": "Designs",
    "icon": "layout-template",
    "full": true,
    "component": "web/build/studio/designs.js" }
]

Closing it animates back to the panel at its normal size, on the page you came from. onBack is the same exit, for a button of your own. The player's own full-screen preference is untouched — this is taken off again when the page closes.

Do not portal a full-screen editor onto document.body yourself. It looks the same for one release and then drifts: it sits over the panel instead of being it, it misses the theme, and every product that copies you writes its own z-index. full is the supported way.

Reaching your own server from inside it needs the relay, because the page renders in dirk_lib's NUI frame — a plain fetchNui posts to dirk_lib, and your callbacks are never reached. Worse, fetchNui answers a failed fetch with its mock data, so that failure looks exactly like success:

ts
const reply = await fetchNui<{ success: boolean; data?: T; _error?: string }>(
  'STUDIO_REQUEST',
  { resource: 'dirk_fishing', callback: 'dirk_fishing:getPlayers', payload },
);
if (!reply?.success) throw new Error(reply?._error ?? 'NoAnswer');

The callback name must start with your own resource name; anything else is refused. Keep your mock data behind isEnvBrowser() so a real failure in game still looks like one.

The Designs tab

Every script whose look a server owner builds rather than configures — the character screen, the loading screen, the chat — surfaces that the same way, so one is learnt and the rest are recognised. This is that shape; copy it exactly rather than inventing a second one.

One page, declared first.

json
"x-pages": [
  { "id": "designs",
    "label": "Designs",
    "icon": "layout-template",
    "full": true,
    "component": "web/build/studio/designs.js",
    "description": "Every look this screen can wear." }
]

Declared first, it lands directly under What's new and above every settings section, in the script's accent colour — the same weight as the other places worth going, which is what it is.

Two modes behind one page.

Browse is a gallery: a card per design with a live thumbnail, an ACTIVE chip on the one players see, and per-card set-active, duplicate, rename, delete, plus + New. It is an ordinary full-window page.

Edit is the canvas. Opening a design swaps the page's contents for the editor; the window is already full screen, so nothing grows a second time and nothing floats over the panel. The page's own breadcrumb goes back to the gallery, and the header's back arrow (or onBack) leaves the page entirely.

What is stored where. The active design is the only one every player needs, so it lives in scriptConfig client and server; the rest are server-only, because admins edit them and players never read them. The gallery fetches metadata only — name, description, thumbnail — and the full element tree is loaded when a design is opened. A gallery that loads every tree is a gallery that stalls the panel.

What is shared. The gallery, the editor shell and the storage contract are written once in the studio package; a product supplies its own manifest and mounts them. If you are writing a second copy of the gallery, stop — that is the thing this section exists to prevent.

What a setting is called

Three things can name a setting, and they are tried in this order:

1. the resource's own locale bundle for the active language — settings.<path>.label
2. the same bundle in English, the fallback the whole chain leans on
3. the schema: a declared title, else the property key humanised (maxArtificialDepth → "Max Artificial Depth")

title works everywhere a name is drawn — a setting, a column inside a row, and the modal a list opens. Without it a column could only ever be called what its property is called, so channelId read as "Channel Id" and a list titled "Redirects" still opened a modal called "New Route".

title does not rename a section. A top-level block becomes a section named from its key; to call it something else, declare it in x-sections or translate sections.<id>.label.

Locales

Labels, descriptions and validation messages live in the resource's own locales/<lang>.json, not dirk_lib's, under a settings. namespace:

json
{
  "sections.permits.label": "Permits",
  "settings.basic.permitPrice.label": "Permit Price",
  "settings.basic.permitPrice.description": "Cost of a fishing licence.",
  "ErrPermitPriceRequired": "Needed when this fish requires a permit"
}

Anything untranslated falls through to the schema's English per string, so a part-translated resource is fine. Changing the language in Shared Settings re-renders immediately.

The words INSIDE a control are translatable too, and by the same derived keys — nothing in the schema needs annotating for it:

Inside a list row the path reaches the column, so a column called speciality on the scrapyards.locations list is settings.scrapyards.locations.speciality.enum.sports.

Bands are keyed by index, not by their English word: they are a ladder, and renaming a rung in English should not orphan its translation.

#scriptConfig.get

Get settings at a path.

lua
local val = scriptConfig.get('basic.maxPlayers')
local all = scriptConfig.get() -- returns everything

#scriptConfig.set

Apply a partial settings update. Merges changes, persists to DB, broadcasts to clients, and fires watchers.

lua
scriptConfig.set({ basic = { maxPlayers = 64 } })

#scriptConfig.on

Same watcher API as the client side.

lua
lib.scriptConfig.on('basic', function(newVal, oldVal, meta)
    print('basic changed, source:', meta.source)
end)

#scriptConfig.reset

Reset all settings to schema defaults.

lua
scriptConfig.reset()

#Server callbacks

These lib.callback handlers are registered on your resource automatically when you call lib.scriptConfig(). They are what the panel talks to — you never register them yourself, and every one of them re-checks permission on its own:

#Database

Settings are stored in the dirk_scriptConfig table (created automatically):

Change log entry format:

lua
{
  at_unix = 1710454800,
  at_utc = "2024-03-14T15:20:00Z",
  script = "my_resource",
  admin = { source = 5, name = "Admin", identifier = "license:abc123" },
  expected_version = 12345,
  applied_version = 67890,
  changes = {
    { path = "basic.debug", old = false, new = true },
    { path = "basic.maxPlayers", old = 32, new = 64 },
  },
}

#Version Conflict Detection

The system uses content-based hashing for optimistic concurrency:

1. When settings are saved, a 31-bit hash is computed from the canonical JSON
2. The admin panel sends expectedVersion with every update
3. If the server's current version doesn't match, the update is rejected
4. The server returns the latest data so the admin can review and re-save

This prevents two admins from silently overwriting each other's changes.

#Watcher Patterns

#Common server-side patterns

lua
-- Re-register useables when equipment config changes
lib.scriptConfig.on('equipment', function()
  registerEquipmentUseables()
end)

-- Conditionally register debug commands
lib.scriptConfig.on('basic', function(basic)
  if not basic.debug then return end
  RegisterCommand('debugInfo', function(src)
    -- debug logic
  end, true)
end)

-- React to ALL changes (e.g. regenerate config files)
lib.scriptConfig.on('*', function()
  regenerateExportFiles()
end)

#Common client-side patterns

lua
-- Register keybinds from settings
lib.scriptConfig.on('basic', function(basic)
  local controls = basic.defaultControls or {}
  RegisterKeyMapping('+myAction', 'My Action',
    controls.main?._type or 'keyboard',
    controls.main?._key or 'E')
end)

#Shared-side patterns

lua
-- Recalculate derived values used on both sides
lib.scriptConfig.on('basic', function(basic)
  local skillSettings = basic.skillSettings or {}
  MySkill.baseLevel = skillSettings.baseLevel or 1
  MySkill.maxLevel = skillSettings.maxLevel or 99
  generateLevelMap()
end)

#Real-World Example (dirk_fishing)

The fishing resource demonstrates the full system:

Server watchers (src/server/init.lua):

lua
lib.scriptConfig.on('equipment', function() registerRodUseables() end)
lib.scriptConfig.on('basic', function() registerGuidebookUseable() end)
lib.scriptConfig.on('stores', function() registerStoresAndPrices() end)
lib.scriptConfig.on('fish', function() registerStoresAndPrices() end)
lib.scriptConfig.on('baitDig', function() registerBaitDigUseables() end)

Wildcard watcher (src/server/install.lua):

lua
lib.scriptConfig.on('*', function()
  -- Regenerate ox.lua, qb.lua, esx.sql item definition files
  -- whenever ANY setting changes
  local basic = scriptConfig?.basic or {}
  local fish = scriptConfig?.fish or {}
  local equipment = scriptConfig?.equipment or {}
  -- ... generate and save files
end)

Client keybind registration (src/client/permit.lua):

lua
lib.scriptConfig.on('basic', function(basic)
  if permitControlsRegistered then return end
  permitControlsRegistered = true

  local controls = basic?.defaultControls or {}
  RegisterKeyMapping('+flipFishingPermit', 'Flip Fishing Permit',
    controls.flipCard?.main?._type or 'keyboard',
    controls.flipCard?.main?._key or 'r')
end)