@amxts/config-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kukson777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PAWN.md

@@ -0,0 +1,13 @@
+# Config Core for Pawn plugins
+
+[English](PAWN.md) | [Русский](PAWN.ru.md)
+
+Config Core gives Pawn plugins the 28 natives of `universal_config.inc` — `cfg_load_file`, `cfg_get_value`, `cfg_set_int` and the rest — with their signatures, so compiled `.amxx` plugins (Menu Core's Pawn users among them) work against it unchanged.
+
+It takes the place of `universal_config.amxx`: comment that one out in `plugins.ini`, since two plugins cannot give the same natives. Pawn plugins write `#include <universal_config>`; the package ships `include/universal_config.inc`.
+
+## How the natives behave
+
+- No Pawn limits: a key or a value is as long as it is written, a section keeps every entry, blocks nest as deep as they are written, any number of files loads.
+- A number reads the way `parseFloat` reads it (`1e5` is 100000) and is written as the number it is (`2.5`, not `2.500000`).
+- `CFG_CONTENT_SIMPLE` and `CFG_CONTENT_STRINGS` are one content: a block of either holds a line of values, and `cfg_set_value` writes into it.

package/PAWN.ru.md

@@ -0,0 +1,13 @@
+# Config Core для Pawn-плагинов
+
+[English](PAWN.md) | [Русский](PAWN.ru.md)
+
+Config Core отдаёт Pawn-плагинам 28 нативов из `universal_config.inc` — `cfg_load_file`, `cfg_get_value`, `cfg_set_int` и остальные — с их сигнатурами, так что собранные `.amxx`-плагины (в том числе Pawn-плагины, работающие с Menu Core) работают без изменений.
+
+Он встаёт на место `universal_config.amxx`: тот закомментируйте в `plugins.ini` — два плагина не могут отдавать одни и те же нативы. Pawn-плагины пишут `#include <universal_config>`; в пакете лежит `include/universal_config.inc`.
+
+## Как работают нативы
+
+- Нет ограничений Pawn: ключ и значение любой длины, секция хранит все записи, блоки вложены на любую глубину, загружается сколько угодно файлов.
+- Число читается так, как его читает `parseFloat` (`1e5` — это 100000), и записывается как есть (`2.5`, а не `2.500000`).
+- `CFG_CONTENT_SIMPLE` и `CFG_CONTENT_STRINGS` — одно и то же содержимое: блок любого из них хранит строку значений, и `cfg_set_value` пишет в него.

package/README.md

@@ -0,0 +1,249 @@
+<div align="center">
+
+<img src="assets/logo.svg" width="96" alt="Config Core">
+
+# Config Core
+
+*Configs in INI, YAML or JSON, read into typed objects and written back*
+
+[![amxts module](https://img.shields.io/badge/amxts-module-3178c6?style=flat-square)](https://amxts.github.io/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[Features](#features) • [Installation](#installation) • [Usage](#usage) • [File formats](#file-formats) • [INI files](#ini-files) • [Pawn plugins](#pawn-plugins)
+
+**English** | [Русский](README.ru.md)
+
+</div>
+
+Read a config file — INI, YAML or JSON, whichever the admin wrote — into an object shaped like its defaults, typed in the editor, change it and write the file back, with its comments where they were.
+
+## Features
+
+- **A typed object.** `configs.load("settings", { chat: { prefix: "[Server]" } })` gives `settings.chat.prefix`, typed as its default is; a typo is the editor's error, not a setting silently missing.
+- **Three formats, one API.** `settings.yaml`, `settings.json` or `settings.ini`: the same code reads each of them.
+- **Mistakes said where they are.** A value of the wrong kind, a name not in its union, an unknown key — each is named in the server console with the file and the line (and the column in YAML and JSON), with "did you mean", and the default is kept.
+- **Writes back what it read.** `configs.save(settings)` puts the values in their places; comments on lines of their own survive, a missing file is written as YAML.
+- **Files of any shape too.** A tree of values with paths — `shop.items[0].name` — for a file whose keys are not known beforehand.
+- **INI with blocks and rows.** Sections, blocks and rows of values read into the same objects — and the 28 `cfg_*` natives serve them to Pawn plugins.
+- **One instance per server.** Every plugin, TypeScript or Pawn, sees the same loaded files and the same base folder.
+
+## Installation
+
+```bash
+npx amxts module add config-core
+```
+
+It installs the package and adds it to `modules` in your project's `amxts.config.ts`. The module's options go beside it, under `configs`:
+
+```ts
+export default defineConfig({
+	modules: ["@amxts/config-core"],
+	configs: {
+		baseDir: "myserver",   // names are read from configs/myserver/
+	},
+});
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `baseDir` | `""` | The folder under `configs/` that file names are read from; `""` is `configs/` itself. |
+
+A module that reads its files through Config Core, such as [Menu Core](https://github.com/amxts/menu-core), brings it along — there is nothing to add for it.
+
+## Usage
+
+A plugin uses the module as `configs`, without an import line: the build adds the import to the plugins that use it, and builds the module only when some plugin does.
+
+```ts
+const settings = configs.load("settings", {   // configs/myserver/settings.yaml, .json or .ini
+	chat: { prefix: "[Server]" },
+	round: { time: 2.5 },
+	maps: ["de_dust2"],
+});
+
+console.log(`${settings.chat.prefix} ${settings.maps.length} maps`);   // from the file, or the default
+
+settings.round.time = 3;
+configs.save(settings);                       // in the file's format, comments kept
+```
+
+The defaults say the object's shape. What the file has replaces the default, value by value; what it leaves out stays the default. An interface gives the fields descriptions, optional fields and unions of names:
+
+```ts
+type Mode = "normal" | "dm" | "knife";
+
+interface Settings {
+	/** The text before every chat message. */
+	chat: { prefix: string };
+	round: { time: number; mode: Mode };
+	maps: string[];
+	/** Shown on join; left out, nothing is shown. */
+	motd?: string;
+}
+
+const settings = configs.load<Settings>("settings", {
+	chat: { prefix: "[Server]" },
+	round: { time: 2.5, mode: "normal" },
+	maps: [],
+});
+```
+
+A mistake in the file keeps the default, and the console says where it is:
+
+```
+[ConfigCore] configs/myserver/settings.yaml:6:9: "mode" is "dmm", not one of "normal", "dm", "knife" - did you mean "dm"? - the default stays
+[ConfigCore] configs/myserver/settings.yaml:2:3: unknown key "prefx" in "chat" - did you mean "prefix"?
+```
+
+| In the object | In the file |
+| --- | --- |
+| `string`, `number`, `boolean` | a value; a number may be text, a boolean `true`/`false`, `yes`/`no`, `on`/`off` in any case or a number (0 is false) |
+| a union of names, `"normal" \| "dm"` | one of them |
+| `string[]`, `number[]`, `boolean[]`, a list of names | a list — an item of another kind is left out |
+| `string[][]` (of text, numbers, booleans or names) | a list of lists: rows of values; an INI block of rows |
+| an object, nested as deep as needed | an object |
+| a list of objects | a list of objects — a field an item leaves out is empty, and said |
+| `Map<string, number>` (of text, numbers, booleans or names) | an object |
+| `field?: T` | may be left out: `undefined` |
+
+- `configs.load()` gives a copy of the defaults with the file's values in it; a second call reads the file again. `configs.save(settings)` writes every field into the file it came from.
+- An object `load()` read without a type has no type name to write in a function's parameter: to pass the settings around, declare an interface and write `configs.load<Settings>(...)`.
+- The build reads the shape from the source: the defaults as an object literal (a list with an item in it), or the type given — `configs.load<Settings>(...)`. What it cannot read — an empty list without a type, a list of lists of lists — stops the build with the place and the fix.
+
+### Which file is read
+
+`load("settings")` and `read("settings")` read the first of `settings.ini`, `settings.yaml`, `settings.yml`, `settings.json` and `settings.jsonc` that is there. When two of them are, the first is read and the server console says so: keep one. A name with its extension — `load("settings.json", ...)` — reads that file. A file that is not there reads as the defaults, and is saved as `settings.yaml`.
+
+### Files of unknown shape
+
+A file whose keys are not known beforehand — a list of maps with settings of their own, a file another plugin writes — reads as a tree of values:
+
+```ts
+const maps = configs.read("maps");
+
+for (const map of maps.values()) {
+	console.log(`${map.key}: ${map.getNumber("rounds", 30)} rounds`);
+}
+
+maps.setNumber("de_dust2.rounds", 20);
+maps.save();
+```
+
+A value is a `ConfigNode`: an object, an array, text, a number, a boolean or null (`kind`), with the file, line and column it was read from. A path leads into it — `chat.prefix`, `items[0].name` — and a getter takes the value's fallback for when it is not there or not of that kind.
+
+### API
+
+| Function | What it does |
+| --- | --- |
+| `load(name, defaults)` | Reads a config file into an object shaped like `defaults`. |
+| `save(settings)` | Writes an object `load()` read back into its file. |
+| `read(name)` | Reads a config file as a tree of values; the file's top value. |
+| `resolve(name)` | The file `load(name)` and `read(name)` read, e.g. `"settings.yaml"`. |
+| `parse(text, format)` | Reads a text — `"yaml"`, `"json"` or `"ini"` — as a tree. |
+
+| `ConfigNode` | What it does |
+| --- | --- |
+| `kind` · `key` · `file` · `format` · `line` · `column` | What the value is, and where it was read. |
+| `get(path)` · `has(path)` | The value a path leads to, or `null`; whether there is one. |
+| `keys(path?)` · `values(path?)` | An object's keys; an array's items or an object's values. |
+| `getString(path?, fallback?)` · `getNumber` · `getBoolean` · `getStrings` | A value as text, a number, a boolean, a list of text. |
+| `set(path, text)` · `setNumber` · `setBoolean` · `setStrings` | Sets a value, making the objects on its path; `false` where the path goes through text or a number. |
+| `remove(path)` · `save()` | Removes a value; writes the whole file back in its format. |
+
+## File formats
+
+The same settings in each of them:
+
+```yaml
+# settings.yaml
+chat:
+  prefix: "[Server]"
+  rules:
+    - Be nice
+    - No cheats
+round:
+  time: 2.5
+hud:
+  enabled: true
+```
+
+```jsonc
+// settings.json or settings.jsonc
+{
+  "chat": {
+    "prefix": "[Server]",
+    "rules": ["Be nice", "No cheats"],
+  },
+  "round": { "time": 2.5 },
+  "hud": { "enabled": true },
+}
+```
+
+```ini
+; settings.ini
+[chat]
+prefix = [Server]
+rules = "Be nice" "No cheats"
+
+[round]
+time = 2.5
+
+[hud]
+enabled = 1
+```
+
+- **YAML:** mappings and lists, indented or in `{ }` and `[ ]`; plain, `'single'` and `"double"`-quoted text with its escapes; `|` and `>` blocks for text of several lines; numbers, `true`/`false`, `null` and `~` as YAML 1.2 reads them — `yes` is text; `#` comments; `---` before the document and `...` after it.
+- **Not read in YAML:** anchors and aliases (`&`, `*`), tags (`!`), complex keys (`?`), directives (`%YAML`), several documents in one file, and a plain value going on over several lines. The file then reads empty, and the console names the line and the column: `configs/settings.yaml:4:9: anchors and aliases (& and *) are not supported - write the value out`.
+- **JSON:** as JSON is written, plus JSONC's `//` and `/* */` comments and a comma after the last member or item — in `.json` files too.
+- **INI:** each `[section]` is an object of the top — `[chat]` with `prefix = [Server]` is `settings.chat.prefix`; a line of several values is a list; a `key = { ... }` block is an object, or a list of rows. The rules INI adds are under [INI files](#ini-files).
+- **Saving** writes the file in its own format: comments on lines of their own and blank lines stay; a comment after a value on its line, and comments inside `{ }` and `[ ]` in YAML, do not. JSON keeps its indentation.
+
+## INI files
+
+An INI config reads into the same kind of object: each `[section]` is an object, a `key = { ... }` block of keys an object in it, a line of several values a list, and a block of rows in quotes a list of lists:
+
+```ini
+; configs/myserver/settings.ini
+[MAIN]
+CHAT_PREFIX = [MYPLUGIN]
+MAPS = de_dust2 de_inferno de_nuke
+
+HUD = {
+	HIDE_TIME = 255 50 50
+}
+
+CVARS = {
+	"mp_timelimit" "30"
+	"mp_freezetime" "3"
+}
+```
+
+```ts
+const settings = configs.load("settings", {
+	MAIN: {
+		CHAT_PREFIX: "[Server]",
+		MAPS: ["de_dust2"],
+		HUD: { HIDE_TIME: [255, 255, 255] },
+		CVARS: [["mp_timelimit", "20"]],
+	},
+});
+
+for (const row of settings.MAIN.CVARS) {
+	const cvar = new Cvar(row[0]);
+	cvar.value = row[1];
+}
+```
+
+- A block of rows stays a block when the object is saved — rows of one value too; the comments above its rows stay.
+- A path into the tree of such a file (`configs.read()`) is written the same way: `MAIN.HUD.HIDE_TIME[0]`, `MAIN.CVARS[1][0]`. An item of a list is `[0]`: `MAIN.MAPS.0` looks for a key `0`.
+
+> [!WARNING]
+> **In an INI file:**
+>
+> - **Keys are found in any case, as the Pawn natives find them; section names are not:** `[main]` is not `MAIN`. A name the file has twice is its last section.
+> - **A value with spaces is quoted:** `TITLE = "Main menu"`. Unquoted, it is a list of words: a text field keeps its default and says why, and Pawn's `cfg_*` natives and Menu Core read the first word.
+> - **No place for a value at the top of the object that is not an object, nor for a list of objects:** in an INI file such a field stays its default, and the console says so once — write that config in YAML or JSON.
+
+## Pawn plugins
+
+Pawn plugins use Config Core through the 28 `cfg_*` natives of `universal_config.inc` — `#include <universal_config>`, which the package ships in `include/`; compiled `.amxx` plugins work unchanged. The natives read INI files. In `plugins.ini` it takes the place of `universal_config.amxx`. When no TypeScript plugin of the project uses the module, `pawn: ["@amxts/config-core"]` in `amxts.config.ts` keeps it in the build for them. The details: [PAWN.md](PAWN.md).

package/README.ru.md

@@ -0,0 +1,249 @@
+<div align="center">
+
+<img src="assets/logo.svg" width="96" alt="Config Core">
+
+# Config Core
+
+*Конфиги в INI, YAML или JSON: читаются в типизированные объекты и пишутся обратно*
+
+[![amxts module](https://img.shields.io/badge/amxts-module-3178c6?style=flat-square)](https://amxts.github.io/)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[Возможности](#возможности) • [Установка](#установка) • [Использование](#использование) • [Форматы файлов](#форматы-файлов) • [INI-файлы](#ini-файлы) • [Pawn-плагины](#pawn-плагины)
+
+[English](README.md) | **Русский**
+
+</div>
+
+Прочитайте файл конфига — INI, YAML или JSON, какой написал админ, — в объект той же формы, что его значения по умолчанию, типизированный в редакторе, измените его и запишите файл обратно, с комментариями на своих местах.
+
+## Возможности
+
+- **Типизированный объект.** `configs.load("settings", { chat: { prefix: "[Server]" } })` даёт `settings.chat.prefix` того же типа, что значение по умолчанию; опечатка — ошибка редактора, а не молча пропавшая настройка.
+- **Три формата, один API.** `settings.yaml`, `settings.json` или `settings.ini`: один и тот же код читает любой из них.
+- **Ошибки — с местом.** Значение не того вида, имя не из своего юниона, незнакомый ключ — каждое называется в консоли сервера с файлом и строкой (в YAML и JSON — и со столбцом), с «did you mean», и остаётся значение по умолчанию.
+- **Записывает то, что прочитал.** `configs.save(settings)` кладёт значения на их места; комментарии на отдельных строках переживают сохранение, отсутствующий файл пишется в YAML.
+- **И файлы любой формы.** Дерево значений с путями — `shop.items[0].name` — для файла, ключи которого заранее неизвестны.
+- **INI с блоками и строками.** Секции, блоки и строки значений читаются в те же объекты — а 28 нативов `cfg_*` отдают их Pawn-плагинам.
+- **Один экземпляр на сервер.** Все плагины, на TypeScript и на Pawn, видят одни и те же загруженные файлы и одну базовую папку.
+
+## Установка
+
+```bash
+npx amxts module add config-core
+```
+
+Команда ставит пакет и добавляет его в `modules` в `amxts.config.ts` проекта. Настройки модуля пишутся рядом, в `configs`:
+
+```ts
+export default defineConfig({
+	modules: ["@amxts/config-core"],
+	configs: {
+		baseDir: "myserver",   // имена файлов читаются из configs/myserver/
+	},
+});
+```
+
+| Опция | По умолчанию | Что делает |
+| --- | --- | --- |
+| `baseDir` | `""` | Папка внутри `configs/`, из которой читаются файлы; `""` — сама `configs/`. |
+
+Модуль, который читает свои файлы через Config Core, например [Menu Core](https://github.com/amxts/menu-core), приносит его с собой — добавлять для него ничего не нужно.
+
+## Использование
+
+Плагин пользуется модулем как `configs`, без строки импорта: сборка добавляет импорт в те плагины, которые им пользуются, и собирает модуль, только когда им пользуется хоть один.
+
+```ts
+const settings = configs.load("settings", {   // configs/myserver/settings.yaml, .json или .ini
+	chat: { prefix: "[Server]" },
+	round: { time: 2.5 },
+	maps: ["de_dust2"],
+});
+
+console.log(`${settings.chat.prefix} ${settings.maps.length} maps`);   // из файла или по умолчанию
+
+settings.round.time = 3;
+configs.save(settings);                       // в формате файла, с комментариями
+```
+
+Значения по умолчанию задают форму объекта. Что есть в файле, заменяет значение по умолчанию, значение за значением; чего в файле нет, остаётся по умолчанию. Интерфейс даёт полям описания, необязательные поля и юнионы имён:
+
+```ts
+type Mode = "normal" | "dm" | "knife";
+
+interface Settings {
+	/** Текст перед каждым сообщением в чате. */
+	chat: { prefix: string };
+	round: { time: number; mode: Mode };
+	maps: string[];
+	/** Показывается при входе; если не задан, ничего не показывается. */
+	motd?: string;
+}
+
+const settings = configs.load<Settings>("settings", {
+	chat: { prefix: "[Server]" },
+	round: { time: 2.5, mode: "normal" },
+	maps: [],
+});
+```
+
+Ошибка в файле оставляет значение по умолчанию, а консоль говорит, где она:
+
+```
+[ConfigCore] configs/myserver/settings.yaml:6:9: "mode" is "dmm", not one of "normal", "dm", "knife" - did you mean "dm"? - the default stays
+[ConfigCore] configs/myserver/settings.yaml:2:3: unknown key "prefx" in "chat" - did you mean "prefix"?
+```
+
+| В объекте | В файле |
+| --- | --- |
+| `string`, `number`, `boolean` | значение; число можно текстом, логическое — `true`/`false`, `yes`/`no`, `on`/`off` в любом регистре или число (0 — ложь) |
+| юнион имён, `"normal" \| "dm"` | одно из них |
+| `string[]`, `number[]`, `boolean[]`, список имён | список — элемент другого вида пропускается |
+| `string[][]` (текста, чисел, логических значений или имён) | список списков: строки значений; в INI — блок строк |
+| объект любой вложенности | объект |
+| список объектов | список объектов — поле, которого нет у элемента, пустое, и об этом сказано |
+| `Map<string, number>` (текста, чисел, логических значений или имён) | объект |
+| `field?: T` | можно не писать: `undefined` |
+
+- `configs.load()` отдаёт копию значений по умолчанию со значениями из файла; второй вызов читает файл заново. `configs.save(settings)` пишет каждое поле в файл, из которого объект прочитан.
+- У объекта, который `load()` прочитал без типа, нет имени типа, чтобы написать его в параметре функции: чтобы передавать настройки дальше, объявите интерфейс и пишите `configs.load<Settings>(...)`.
+- Сборка читает форму из исходника: значения по умолчанию — объектным литералом (в списке — элемент), или указан тип — `configs.load<Settings>(...)`. Чего так не прочитать — пустой список без типа, список списков списков, — останавливает сборку с местом и тем, как исправить.
+
+### Какой файл читается
+
+`load("settings")` и `read("settings")` читают первый из `settings.ini`, `settings.yaml`, `settings.yml`, `settings.json` и `settings.jsonc`, который есть. Если есть два, читается первый, а консоль сервера об этом говорит: оставьте один. Имя с расширением — `load("settings.json", ...)` — читает этот файл. Файла нет — читаются значения по умолчанию, а сохраняется он как `settings.yaml`.
+
+### Файлы неизвестной формы
+
+Файл, ключи которого заранее неизвестны, — список карт со своими настройками, файл, который пишет другой плагин, — читается деревом значений:
+
+```ts
+const maps = configs.read("maps");
+
+for (const map of maps.values()) {
+	console.log(`${map.key}: ${map.getNumber("rounds", 30)} rounds`);
+}
+
+maps.setNumber("de_dust2.rounds", 20);
+maps.save();
+```
+
+Значение — это `ConfigNode`: объект, массив, текст, число, логическое значение или null (`kind`), с файлом, строкой и столбцом, где оно прочитано. Путь ведёт внутрь — `chat.prefix`, `items[0].name`, — а геттер принимает запасное значение на случай, если значения нет или оно другого вида.
+
+### API
+
+| Функция | Что делает |
+| --- | --- |
+| `load(name, defaults)` | Читает файл конфига в объект той же формы, что `defaults`. |
+| `save(settings)` | Записывает объект, прочитанный `load()`, обратно в его файл. |
+| `read(name)` | Читает файл конфига деревом значений; верхнее значение файла. |
+| `resolve(name)` | Файл, который читают `load(name)` и `read(name)`, например `"settings.yaml"`. |
+| `parse(text, format)` | Читает текст — `"yaml"`, `"json"` или `"ini"` — деревом. |
+
+| `ConfigNode` | Что делает |
+| --- | --- |
+| `kind` · `key` · `file` · `format` · `line` · `column` | Что это за значение и где оно прочитано. |
+| `get(path)` · `has(path)` | Значение, к которому ведёт путь, или `null`; есть ли оно. |
+| `keys(path?)` · `values(path?)` | Ключи объекта; элементы массива или значения объекта. |
+| `getString(path?, fallback?)` · `getNumber` · `getBoolean` · `getStrings` | Значение как текст, число, логическое значение, список текста. |
+| `set(path, text)` · `setNumber` · `setBoolean` · `setStrings` | Задаёт значение, создавая объекты на пути; `false`, если путь идёт через текст или число. |
+| `remove(path)` · `save()` | Удаляет значение; записывает весь файл обратно в его формате. |
+
+## Форматы файлов
+
+Одни и те же настройки в каждом из них:
+
+```yaml
+# settings.yaml
+chat:
+  prefix: "[Server]"
+  rules:
+    - Be nice
+    - No cheats
+round:
+  time: 2.5
+hud:
+  enabled: true
+```
+
+```jsonc
+// settings.json или settings.jsonc
+{
+  "chat": {
+    "prefix": "[Server]",
+    "rules": ["Be nice", "No cheats"],
+  },
+  "round": { "time": 2.5 },
+  "hud": { "enabled": true },
+}
+```
+
+```ini
+; settings.ini
+[chat]
+prefix = [Server]
+rules = "Be nice" "No cheats"
+
+[round]
+time = 2.5
+
+[hud]
+enabled = 1
+```
+
+- **YAML:** отображения и списки — с отступами или в `{ }` и `[ ]`; простой текст, текст в `'одинарных'` и `"двойных"` кавычках со своими экранированиями; блоки `|` и `>` для текста в несколько строк; числа, `true`/`false`, `null` и `~`, как их читает YAML 1.2, — `yes` это текст; комментарии `#`; `---` перед документом и `...` после.
+- **Чего в YAML нет:** якорей и ссылок (`&`, `*`), тегов (`!`), сложных ключей (`?`), директив (`%YAML`), нескольких документов в одном файле и простого значения, которое продолжается на следующих строках. Тогда файл читается пустым, а консоль называет строку и столбец: `configs/settings.yaml:4:9: anchors and aliases (& and *) are not supported - write the value out`.
+- **JSON:** как пишется JSON, плюс комментарии `//` и `/* */` из JSONC и запятая после последнего поля или элемента — и в файлах `.json` тоже.
+- **INI:** каждая `[секция]` — объект верхнего уровня: `[chat]` с `prefix = [Server]` — это `settings.chat.prefix`; строка из нескольких значений — список; блок `key = { ... }` — объект или список строк. Правила, которые добавляет INI, — в [INI-файлах](#ini-файлы).
+- **Сохранение** пишет файл в его формате: комментарии на отдельных строках и пустые строки остаются; комментарий после значения на той же строке и комментарии внутри `{ }` и `[ ]` в YAML — нет. JSON сохраняет свои отступы.
+
+## INI-файлы
+
+INI-конфиг читается в такой же объект: каждая `[секция]` — объект, блок ключей `key = { ... }` — объект в нём, строка из нескольких значений — список, а блок строк в кавычках — список списков:
+
+```ini
+; configs/myserver/settings.ini
+[MAIN]
+CHAT_PREFIX = [MYPLUGIN]
+MAPS = de_dust2 de_inferno de_nuke
+
+HUD = {
+	HIDE_TIME = 255 50 50
+}
+
+CVARS = {
+	"mp_timelimit" "30"
+	"mp_freezetime" "3"
+}
+```
+
+```ts
+const settings = configs.load("settings", {
+	MAIN: {
+		CHAT_PREFIX: "[Server]",
+		MAPS: ["de_dust2"],
+		HUD: { HIDE_TIME: [255, 255, 255] },
+		CVARS: [["mp_timelimit", "20"]],
+	},
+});
+
+for (const row of settings.MAIN.CVARS) {
+	const cvar = new Cvar(row[0]);
+	cvar.value = row[1];
+}
+```
+
+- Блок строк остаётся блоком, когда объект сохраняется, — и строки из одного значения тоже; комментарии над его строками остаются.
+- Путь в дереве такого файла (`configs.read()`) пишется так же: `MAIN.HUD.HIDE_TIME[0]`, `MAIN.CVARS[1][0]`. Элемент списка — это `[0]`: `MAIN.MAPS.0` ищет ключ `0`.
+
+> [!WARNING]
+> **В INI-файле:**
+>
+> - **Ключи ищутся без учёта регистра, как их ищут Pawn-нативы, имена секций — нет:** `[main]` — не `MAIN`. Из двух секций с одним именем берётся последняя.
+> - **Значение с пробелами берётся в кавычки:** `TITLE = "Main menu"`. Без кавычек это список слов: текстовое поле остаётся со значением по умолчанию, а консоль говорит почему, и нативы `cfg_*` Pawn и Menu Core читают первое слово.
+> - **Нет места значению на верхнем уровне объекта, которое не объект, и списку объектов:** в INI-файле такое поле остаётся по умолчанию, и консоль один раз об этом говорит — такой конфиг пишите в YAML или JSON.
+
+## Pawn-плагины
+
+Pawn-плагины работают с Config Core через 28 нативов `cfg_*` из `universal_config.inc` — `#include <universal_config>`, который лежит в пакете в `include/`; собранные `.amxx`-плагины работают без изменений. Нативы читают INI-файлы. В `plugins.ini` он встаёт на место `universal_config.amxx`. Когда модулем не пользуется ни один плагин проекта на TypeScript, `pawn: ["@amxts/config-core"]` в `amxts.config.ts` оставляет его в сборке для них. Подробности — в [PAWN.ru.md](PAWN.ru.md).