file
文件读写 + 图像资源。
文件路径相对应用同级目录，路径字符串含子串 .. 即拒（沙盒）；绝对路径也拒。注意是子串匹配，my..file.txt 也会拒。
文件
file.read(path) → string | nil
参数：path : string
file.write(path, content) → bool
参数：path : string, content : string
自动创建父目录。
file.exists(path) → bool
file.remove(path) → bool
file.rename(old, new) → bool
沙盒内重命名/移动文件,自动创建目标父目录。两边都走 sandbox 校验(禁 .. / 绝对路径)。
file.list(dir) → table<string>
列 dir 下文件名（非递归，只列文件不列子目录）。dir 为空 / 不存在返空表。
file.scan(pattern) → table<string>
按 glob 通配符匹配返完整相对路径(非递归)。支持 * 任意字符序列 + ? 单字符。
lua
local logs = file.scan("logs/*.log") -- {"logs/a.log", "logs/b.log", ...}
local cfgs = file.scan("scripts/state/*.json")
local r24 = file.scan("logs/2024-??-??.log") -- 单字符通配图像资源 (file.image)
handle 是不透明纹理句柄，传给 draw.image 显示。
脚本卸载时该脚本创建的全部图像句柄自动释放。
file.image:load(path) → handle | nil
参数：path : string
也支持 (path, w, h) 强制目标尺寸。
file.image:svg(svg_str, w, h) → handle | nil
参数：svg_str : string, w : int, h : int
file.image:create(rgba, w, h) → handle | nil
参数：rgba : table 长度 = w*h*4 的 byte 数组, w/h : int
file.image:get(name) → handle | nil
file.image:has(name) → bool
file.image:list() → table<string>
列出 TextureManager 全部纹理名——包括项目内置 ESP 图标、其它脚本创建的纹理，不仅当前脚本拥有的。配合 file.image:remove 时要先匹配自己 owner，否则会误删别人。
file.image:remove(name) → bool
file.image:load_gif(path) → AnimatedTexture | nil
参数：path : string — GIF 文件路径（沙盒内相对路径）
返回 AnimatedTexture userdata，包含多帧 + 每帧延迟（毫秒）。所有帧 SRV 由 AnimatedTexture 自行管理，脚本卸载时整体释放。
AnimatedTexture 方法 / 字段
| 名称 | 说明 |
|---|---|
:advance(dt_sec) → handle | 按 dt_sec 推进帧。返回当前帧 handle，可直接喂 draw.image。dt 大时跳帧不漏帧 |
:current_frame() → handle | 不推进，只返回当前帧 handle |
:reset() | 回到第 0 帧 |
.frame_count | int — 总帧数 |
.width / .height | int — GIF 尺寸（所有帧统一） |
.current_index | int — 当前帧下标（0-based） |
.current_delay_ms | int — 当前帧延迟（毫秒） |
lua
local gif = file.image:load_gif("scripts/assets/loading.gif")
event.on("frame_update", function(e)
if gif then
local frame = gif:advance(e.delta_time)
draw.image(frame, 100, 100, gif.width, gif.height)
end
end)示例
lua
-- 配置持久化
local cfg_path = "scripts/state/my_script.json"
if file.exists(cfg_path) then
local raw = file.read(cfg_path)
-- 解析 JSON / ...
end
file.write(cfg_path, [[{"flag":true}]])
-- 加载 logo
local logo = file.image:load("scripts/assets/logo.png")
event.on("frame_update", function(e)
if logo then draw.image(logo, 10, 10, 64, 64) end
end)
-- 程序生成 SVG icon
local icon = file.image:svg(
[[<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="#ff5050"/></svg>]],
24, 24)