file

Сырое чтение и запись файлов в собственном каталоге плагина

file

Сырое чтение и запись файлов в собственном каталоге плагина.

file читает и пишет обычные файлы — байтовую строку целиком, без разбора формата. Для структурированных данных (таблиц) есть store/datafile; file для всего остального: csv-экспорт, готовый json, любой текстовый или бинарный формат, который плагин собирает сам.

file.write("report.csv", "name,score\nplayer1,10\n")
local content = file.read("report.csv")

Песочница

Все имена — только внутри plugin.data_dir(), той же папки, куда пишут db.open() и store. Подпапок нет — name не может содержать /, \ или что-то похожее на путь.

Имя — это stem или stem.ext:

• stem: буквы, цифры, _, -
• .ext — необязательно, ровно одна точка на всё имя, только буквы и цифры
• максимум 64 символа

Валидно: report.csv, export_2026.json, state. Невалидно: ../evil.txt, sub/dir.txt, a.b.c, .hidden, hidden..

Предел размера

Одно чтение или одна запись/дозапись — не больше 4 МиБ. Больше — nil и причина, ещё до того, как файл открыт: частично записанного файла при отказе не остаётся.

file.read

Читает содержимое файла целиком.

file.read(name)

Аргументы

#	имя	тип
1	name	string	имя файла в каталоге плагина (см. песочницу выше)

Возвращает

тип
string | nil	содержимое файла
string	причина, если файл не открылся, его нет или он больше 4 МиБ

Пример

local content, err = file.read("report.csv")
if not content then
  print("не смог прочитать: " .. err)
  return
end

Отсутствие файла — тоже ошибка здесь (nil, "cannot open ..."), в отличие от file.size, где отсутствие файла — просто nil без причины.

Смотри также

• file.size

file.write

Перезаписывает файл целиком (или создаёт его).

file.write(name, content)

Аргументы

#	имя	тип
1	name	string	имя файла в каталоге плагина (см. песочницу выше)
2	content	string	что записать, до 4 МиБ

Возвращает

тип
boolean | nil	true при успехе
string	причина при ошибке

Пример

local ok, err = file.write("report.csv", "name,score\n")
if not ok then
  print("не смог записать: " .. err)
end

Для дозаписи в конец существующего файла — file.append.

Смотри также

• file.append

file.append

Дописывает в конец файла, не трогая то, что уже было (или создаёт его).

file.append(name, content)

Аргументы

#	имя	тип
1	name	string	имя файла в каталоге плагина (см. песочницу выше)
2	content	string	что дописать, до 4 МиБ за один вызов

Возвращает

тип
boolean | nil	true при успехе
string	причина при ошибке

Пример

hook.add("player:death", "myplugin.kills_log", function(e)
  file.append("kills.csv", ("%s,%s\n"):format(e.attacker and e.attacker:name() or "world", e.player:name()))
end)

Предел 4 МиБ — на один вызов, не на итоговый размер файла: у file.append нет ограничения на то, насколько большим станет файл со временем. Для самоограничивающегося лога с ротацией по дням — log.write.

file.exists

Проверяет, есть ли файл в каталоге плагина.

file.exists(name)

Аргументы

#	имя	тип
1	name	string	имя файла в каталоге плагина (см. песочницу выше)

Возвращает

тип
boolean	true/false; неверное имя или отсутствие каталога плагина — тоже false, не ошибка

Пример

if not file.exists("config.json") then
  file.write("config.json", "{}")
end

file.remove

Удаляет файл из каталога плагина.

file.remove(name)

Аргументы

#	имя	тип
1	name	string	имя файла в каталоге плагина (см. песочницу выше)

Возвращает

тип
boolean | nil	true при успехе
string	причина при ошибке, в том числе если файла и не было

Пример

local ok, err = file.remove("tmp.csv")

file.size

Возвращает размер файла в байтах.

file.size(name)

Аргументы

#	имя	тип
1	name	string	имя файла в каталоге плагина (см. песочницу выше)

Возвращает

тип
number | nil	размер в байтах; nil без причины, если файла нет, имя не годится или нет каталога плагина

Пример

local size = file.size("report.csv")
if size and size > 1024 * 1024 then
  file.remove("report.csv")
end

Смотри также

• file.read

file.list

Возвращает имена всех файлов верхнего уровня в каталоге плагина.

file.list()

Возвращает

тип
table	массив имён файлов; пустой, если каталога плагина ещё нет

Пример

for _, name in ipairs(file.list()) do
  print(name)
end

Подпапка logs/, которую создаёт log.write, в список не попадает — это отдельное хранилище, не файлы плагина.