Settings

Settings are values the player can change in the module UI. The compiler turns defineSettings() declarations into the game’s config.json, while the handle in your code reads and writes the live native Config table.

This keeps the schema, TypeScript type and runtime key in one place.

Minimal example

import { defineSettings, setting } from "@killscript/sdk/client";

export const cameraSettings = defineSettings("camera", {
  enabled: true,
  speed: setting(5, { min: 1, max: 20 }),
  mode: setting.choice(["follow", "orbit", "free"], "follow"),
});

if (cameraSettings.enabled) {
  updateCamera(cameraSettings.speed, cameraSettings.mode);
}

The namespace produces keys such as camera.enabled and camera.speed. Use a short feature namespace when several files may choose generic property names like enabled or color.

defineSettings() must initialize a top-level const, but it may live in any file imported by a client or server entry. It does not have to be collected in one special settings.ts file.

Setting types

const hud = defineSettings("hud", {
  // Direct boolean and number defaults.
  visible: true,
  opacity: 0.85,

  // Number with a visible label and limits.
  scale: setting(1, {
    label: "HUD scale",
    min: 0.5,
    max: 2,
  }),

  // One string from a fixed list.
  anchor: setting.choice(
    ["left", "center", "right"],
    "center",
    { label: "Screen anchor" },
  ),

  // Several options stored as a numeric bit mask.
  layers: setting.flags(
    ["agents", "items", "pings"],
    ["agents", "pings"],
  ),

  // #RRGGBB, #RRGGBBAA or an RGBA tuple from 0 to 1.
  accent: setting.color("#4DE3FFFF"),
});

Declaration	Type in your code	Game configuration
`true` / `false`	`boolean`	Boolean toggle
number or `setting(number, ...)`	`number`	Numeric value with optional limits
`setting.choice(...)`	Union of the listed strings	Zero-based enum
`setting.flags(...)`	`number`	Bit-mask enum
`setting.color(...)`	`Color`	Color picker

Choices deliberately appear as readable strings in TypeScript even though the game stores a zero-based numeric enum. Flag values remain numeric because they can represent several selected options at once.

Flag bits follow the option order, starting at bit zero:

const AgentsLayer = 1 << 0;
const ItemsLayer = 1 << 1;

if ((hud.layers & AgentsLayer) !== 0) {
  drawAgents();
}

A flags declaration supports at most 31 options.

Read and write live values

The returned object is not a snapshot:

cameraSettings.enabled = !cameraSettings.enabled;
cameraSettings.speed = 8;

Each access is compiled directly to the native Config entry. If the player changes a value in the module UI and the game refreshes the table, the next read observes the new value.

Client and Reflex may import the same shared declaration. If both entries register the same final key, their definitions must be identical. The compiler rejects conflicting defaults, duplicate keys, invalid ranges, duplicate choice labels and out-of-range colors before it writes any game files.