Настройки

Настройки — значения, которые игрок меняет в интерфейсе модуля. Компилятор превращает объявления defineSettings() в игровой config.json, а объект в коде читает и изменяет живую нативную таблицу Config.

Так схема, TypeScript-тип и ключ среды выполнения остаются в одном месте.

Минимальный пример

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);
}

Пространство имён создаёт ключи camera.enabled, camera.speed и похожие. Добавляйте короткое имя компонента, когда в разных файлах могут встретиться одинаковые свойства вроде enabled или color.

defineSettings() должен инициализировать const на верхнем уровне, но объявление разрешено в любом файле, импортированном клиентским или серверным entry. Собирать все настройки в обязательном settings.ts не нужно.

Типы настроек

const hud = defineSettings("hud", {
  // Обычные значения по умолчанию.
  visible: true,
  opacity: 0.85,

  // Число с подписью и границами.
  scale: setting(1, {
    label: "Масштаб HUD",
    min: 0.5,
    max: 2,
  }),

  // Одна строка из фиксированного списка.
  anchor: setting.choice(
    ["left", "center", "right"],
    "center",
    { label: "Положение на экране" },
  ),

  // Несколько вариантов в числовой битовой маске.
  layers: setting.flags(
    ["agents", "items", "pings"],
    ["agents", "pings"],
  ),

  // #RRGGBB, #RRGGBBAA или RGBA-компоненты от 0 до 1.
  accent: setting.color("#4DE3FFFF"),
});

Объявление	Тип в коде	Настройка игры
`true` / `false`	`boolean`	Переключатель
число или `setting(number, ...)`	`number`	Число с необязательными границами
`setting.choice(...)`	Union из перечисленных строк	Enum с индексацией от нуля
`setting.flags(...)`	`number`	Битовая маска вариантов
`setting.color(...)`	`Color`	Выбор цвета

Choice остаётся понятной строкой в TypeScript, хотя игра хранит enum как число с нулевой индексацией. Flags остаётся числом, потому что значение может одновременно представлять несколько выбранных вариантов.

Биты flags соответствуют порядку вариантов и начинаются с нулевого:

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

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

Одно flags-объявление поддерживает не больше 31 варианта.

Чтение и изменение текущих значений

Возвращаемый объект не является снимком:

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

Каждый доступ напрямую компилируется в обращение к нативному Config. Если игрок изменит значение в интерфейсе модуля, следующее чтение после обновления таблицы увидит новое значение.

Клиент и Reflex могут импортировать одно общее объявление. Если обе стороны регистрируют одинаковый итоговый ключ, определения обязаны совпадать. Компилятор заранее отклоняет разные значения по умолчанию, повторяющиеся ключи и варианты, неверные границы и цвета вне допустимого диапазона.