Файлы
@amxts/core/fs читает и пишет файлы так же, как fs в Node:
import * as fs from "@amxts/core/fs";
const rulesFile = `${server.configsDir}/myplugin/rules.txt`;
server.addCommand("/rules", ({ player }) => showRules(player));
function showRules(player: Player) {
const text = fs.readFileSync(rulesFile);
if (text == null) return; // файла нет
for (const line of text.split("\n")) console.log(line);
fs.appendFileSync(`${server.dataDir}/myplugin-rules.log`, `${player.name} прочитал правила\n`);
}
У каждой функции есть синхронная форма и форма с промисом, для await:
| Синхронная | С промисом | Что делает |
|---|---|---|
readFileSync(path) → string | null | readFile(path) → Promise<string> | читает весь файл как текст |
readBytesSync(path) → Uint8Array | null с v0.3 | readBytes(path) → Promise<Uint8Array> | читает весь файл как байты |
writeFileSync(path, data) → boolean | writeFile(path, data) → Promise<void> | записывает в файл текст или байты с v0.3, заменяя то, что там было |
appendFileSync(path, data) → boolean | appendFile(path, data) → Promise<void> | дописывает текст или байты в конец, при необходимости создаёт файл |
existsSync(path, options?) → boolean | exists(path, options?) → Promise<boolean> | есть ли такой файл или папка; { game: true } с v0.3.1 ищет во всех папках, из которых игра читает файлы |
readdirSync(path) → string[] | null | readdir(path) → Promise<string[]> | имена в папке, без . и .. |
mkdirSync(path, options?) → boolean | mkdir(path, options?) → Promise<void> | создаёт папку; { recursive: true } создаёт и недостающие папки выше |
unlinkSync(path) → boolean с v0.3 | unlink(path) → Promise<void> | удаляет файл |
renameSync(from, to) → boolean с v0.3 | rename(from, to) → Promise<void> | перемещает или переименовывает файл |
rmdirSync(path) → boolean с v0.3 | rmdir(path) → Promise<void> | удаляет пустую папку |
statSync(path) → Stats | null с v0.3 | stat(path) → Promise<Stats> | size, mtime, isFile(), isDirectory() |
extractSync(archive) → ArchiveEntry[] с v0.3 | extract(archive) → Promise<ArchiveEntry[]> с v0.3.1 | файлы архива |
import * as fs from "@amxts/core/fs";
async function saveMap() {
await fs.mkdir(`${server.dataDir}/myplugin`, { recursive: true });
await fs.writeFile(`${server.dataDir}/myplugin/last-map.txt`, server.map);
}
fs.readFile("missing.txt").catch((error) => console.log(error.message));
// ENOENT: no such file or directory, open 'missing.txt'
Пути
Путь задаётся относительно папки игры, cstrike/, как у любого плагина
AMX Mod X. server.configsDir — папка конфигов (addons/amxmodx/configs),
server.dataDir — папка данных (addons/amxmodx/data), где бы сервер их ни
держал. Храните файлы плагина в своей папке или под своим именем:
configs/myplugin/, data/myplugin-stats.txt.
Текст
Файлы читаются и пишутся как текст в UTF-8. Файл читается целиком, какого бы размера он ни был. Метка порядка байтов (BOM) в начале файла сохраняется, как в Node.
Байты и архивы с v0.3
Файл, который не текст, — карта, звук, архив, — это байты: Uint8Array.
readBytesSync читает его, а writeFileSync и appendFileSync принимают,
кроме текста, Uint8Array или ArrayBuffer. fs.extract(bytes) даёт файлы
архива, каждый — ArchiveEntry с путём path внутри архива и байтами data.
Вид архива он узнаёт по первым байтам; читает zip-архивы:
import * as fs from "@amxts/core/fs";
async function downloadMap(name: string) {
const response = await fetch(`https://maps.example.com/${name}.zip`);
for (const entry of await fs.extract(await response.arrayBuffer())) {
const folder = entry.path.substring(0, entry.path.lastIndexOf("/"));
if (folder.length > 0) await fs.mkdir(folder, { recursive: true });
await fs.writeFile(entry.path, entry.data);
}
}
Большая загрузка может сразу идти в файл — request из @amxts/core/kit
с опцией file, — а
fs.readBytes прочитает её для extract.
Байты читаются и пишутся только внутри папки игры: абсолютный путь или путь с
.. даёт null или false. extract отклоняется с Error для архива с
таким путём, для вида, который он не читает, — rar или 7z, а в сообщении
названы виды, которые он читает, — и для зашифрованного или повреждённого
архива. Из zip-архива он читает файлы, сохранённые как есть или сжатые
deflate, — то, что пишут архиваторы, — и папки не перечисляет.Не задерживая сервер с v0.3.1
Сервер работает кадр за кадром, и кадр ждёт код плагина. extract,
readBytes, а также writeFile и appendFile с байтами делают свою работу
в рабочем потоке сервера и выполняются на одном из следующих кадров, так что
распаковка карты в мегабайты не задерживает игру. Их синхронные формы,
extractSync, readBytesSync и writeFileSync, делают её сразу, внутри
кадра: для маленького файла это нормально, для большого — лаг у игроков.
Байты, записанные writeFile и appendFile, ложатся в порядке вызовов.
Текст пишется теми же файловыми функциями, что и в writeFileSync, сразу.
Сжатие с v0.3.1
@amxts/core/zlib сжимает и распаковывает байты так же, как zlib в Node, в
трёх форматах:
| Синхронная | С промисом | Формат |
|---|---|---|
gzipSync(data), gunzipSync(data) | gzip(data), gunzip(data) | gzip, файл .gz |
deflateSync(data), inflateSync(data) | deflate(data), inflate(data) | zlib: deflate с заголовком и контрольной суммой zlib |
deflateRawSync(data), inflateRawSync(data) | deflateRaw(data), inflateRaw(data) | голый deflate, как файл лежит в zip-архиве |
Каждая принимает Uint8Array или ArrayBuffer — сжимающие ещё и текст, в
UTF-8, — и даёт Uint8Array. Формы с промисом работают в рабочем потоке
сервера, как extract:
import * as fs from "@amxts/core/fs";
import * as zlib from "@amxts/core/zlib";
async function saveRun(name: string, recording: Uint8Array) {
await fs.writeFile(`${server.dataDir}/myplugin/${name}.rec.gz`, await zlib.gzip(recording));
}
async function loadRun(name: string): Promise<Uint8Array> {
return zlib.gunzip(await fs.readBytes(`${server.dataDir}/myplugin/${name}.rec.gz`));
}
Данные, которые не целые данные своего формата, — обрезанные или другого формата, — бросают
Error в синхронном вызове и отклоняют промис, со словами
zlib: incorrect header check, unexpected end of file. Распаковка
останавливается на 64 МБ: дальше вызов завершается ошибкой, а не сервер
остаётся без памяти.JSON
JSON читает и пишет текст JSON, как в JavaScript. JSON.parse говорят, что
он читает, — JSON.parse<Stats>(text) или тип, куда уходит значение, — и он
строит этот объект вместе с его массивами, Record и полями:
import * as fs from "@amxts/core/fs";
interface Stats {
kills: number;
deaths: number;
lastMap?: string;
}
const statsFile = `${server.dataDir}/myplugin/stats.json`;
function loadStats(): Stats {
const text = fs.readFileSync(statsFile);
if (text == null) return { kills: 0, deaths: 0 };
return JSON.parse(text);
}
function saveStats(stats: Stats) {
fs.writeFileSync(statsFile, JSON.stringify(stats, null, 2));
}
Текст, который не JSON, — это SyntaxError; значение не того рода, что
говорит тип, — текст там, где число, поле, которое должно быть и которого
нет, — это TypeError с именем поля. Ловите их через try/catch.
JSON.stringify пропускает поле, которое undefined, пишет Date как её
текст ISO, а объект с toJSON() — как то, что он отдаёт.
Uint8Array с v0.3.1 в JSON — текст base64 в обе стороны:
JSON.stringify пишет его байты так, а не объектом индексов, как JavaScript,
а JSON.parse читает текст base64 в поле типа Uint8Array.
Настройки, которые правит владелец сервера, типизированный конфиг config-core читает одинаково из YAML, JSON и INI.
Когда не получилось
Синхронная функция сообщает об ошибке результатом: null у readFileSync и
readdirSync, false у writeFileSync, appendFileSync и mkdirSync —
например, если нет папки. Функция с промисом отклоняется с Error, чьё
сообщение начинается с ENOENT, как в Node (у mkdir — с EEXIST or ENOENT).
В обоих случаях работа делается сразу: к моменту, когда функция с промисом вернулась, промис уже завершён.
Операционная система
import { EOL, platform } from "@amxts/core/os";
if (platform() == "linux") console.log("сервер на Linux");
const lines = ["first", "second"].join(EOL); // "\r\n" в Windows, "\n" в Linux
platform() — это "win32" или "linux", а EOL — перевод строки этой
системы.
В тесте фейковый сервер держит папку игры в памяти: server.writeFile(path, text) — до того, как плагин читает, server.file(path) — после того, как
он записал (Тесты).
Хранилище
Storage хранит значения по ключу, как Map, только на диске: то, что плагин сохранил, переживает смену карты и перезапуск сервера. Это место для накопленных очков игрока, его последнего визита, настройки.
HTTP
Плагин обращается к веб-сервисам через две функции, обе глобальные — без строки импорта: