Lua 编码规范

Lua 是一门简洁、极简、优雅、高效、可嵌入、表现力强的脚本语言。想要高效开发 Luanti 模组与游戏，必须熟练掌握 Lua。

计时与事件循环

Luanti 的 Lua API 可用于获取时间、日期，或调度一次性/每帧执行的事件。

设置项

• 服务器：dedicated_server_step 控制服务端帧间隔，这是无忙等待时游戏循环的最大粒度。
• 单人模式：帧率决定服务端帧执行频率。

纹理修饰器

纹理修饰器是一串告诉 Luanti 如何处理图片的字符串，除动态媒体外，它是运行时动态生成纹理的唯一方式。
它也能用来简化模组，批量生成重复纹理，比如不同颜色的工具贴图。

ℹ️ 说明
纹理修饰器和硬件着色功能部分重叠。优先使用硬件着色，更灵活、产生的冗余纹理更少。

数据持久化

本页概览 Luanti 提供的序列化与数据持久化方案。

选择持久化方式主要看这些：

• 数据结构与类型：数据长啥样？有哪些类型？
• 数据大小与修改频率：能不能塞进内存？更新开销多大？
• 所需粒度：数据需要多久存一次？
• 查询需求：是否需要索引快速查找？
• 数据绑定对象：物品？玩家？方块？

对象属性

本页面列出对象可拥有的全部属性。

模组通信频道（Modchannels）

用于服务端模组（SSM） 和客户端模组（CSM） 互相发消息、双向通信。

LuaJIT

LuaJIT 是一款面向 Lua 的即时编译器（JIT），它完整实现了 Lua 5.1 标准（为区分起见，官方标准 Lua 称为 PUC Lua），同时附带一些扩展与差异。
LuaJIT 运行速度通常远快于 PUC Lua，因此强烈推荐使用。

除非你编译 Luanti 时手动禁用了 LuaJIT，否则 Luanti 默认都会用 LuaJIT 作为 Lua 运行时。
官方 Windows、Android 以及大多数 Linux 发行版安装包，均已启用 LuaJIT。
你可以在终端执行这条命令确认：

1

./luanti --version

Lua 运行环境

Luanti 采用 Lua 5.1。模组的实际运行环境取决于四大要素：

• 操作系统
• Luanti 构建版本：LuaJIT（默认）或 PUC Lua 5.1
• 模组类型：客户端侧（CSM）或服务端侧（SSM）
• 模组环境：安全模式 或 不安全模式

HTTP API

HTTP API 允许模组发起网络请求（GET/POST 等）。

设置（必须配置）

要使用此 API，模组必须在以下任一配置项中被列出（使用 CSV 格式，即逗号分隔）：

• secure.trusted_mods
• secure.http_mods

文件系统（Filesystem）

Luanti 提供大量工具函数，用于管理路径、文件、文件夹。

重要说明

模组安全系统会限制文件访问路径：

• 加载时：只能访问当前模组目录（mod path）
• 运行时：只能访问世界存档目录（world path）
  详见：Lua 环境（Lua Environment）