文件系统（Filesystem）

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

重要说明

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

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

VoxelArea

VoxelArea 是用于VoxelManip（地图区块操作）的面向对象工具类，专门用来计算坐标索引，避免手写复杂的三维下标公式。

VoxelArea.new(self, o)

创建一个 VoxelArea 实例。
会自动设置 self.__index = self，并将 self 设为 o 的元表。

必须字段

• MinEdge：区域最小坐标（包含）
  为整数向量，默认 vector.new(1, 1, 1)
• MaxEdge：区域最大坐标（包含）
  为整数向量，默认 vector.new(0, 0, 0)

向量 API

Vector（向量）过去只是带 x/y/z 的普通表，现在已升级为带元表的增强类型。
除非特别说明，本文提到的 vector 均指带元表的向量。

vector 命名空间函数

vector.new(a, b, c)

创建新向量。

• a、b、c 为数字 → 返回 {x=a, y=b, z=c}
• a 是向量 → 等价 vector.copy(a)
• 全空 → 等价 vector.zero()

射线检测（Raycast）

射线用于模拟一条“线”，检测它碰到了哪些选择箱（selection box）。
效果和玩家准星指向几乎完全一样（有少量限制）。

指向结果（pointed_thing）格式

射线碰到的东西只有 3 种：

1. nothing：没碰到任何东西
2. object：实体、生物、玩家
3. node：方块（固体/液体）

随机数（Random）

Luanti 提供四种随机数生成器，各有优缺点，模组开发者需要根据场景选择。

Lua 内置随机（全局）

不受模组安全限制，服务端和客户端模组都能用。

math.randomseed(seed)

设置全局随机种子。
引擎已经用系统时间自动帮你设置过。

PlayerMetaData

PlayerMetaData 是每个世界、每个玩家独立的持久化字符串键值存储，完全继承 MetaData 所有方法。

保存频率

数据保存间隔由服务器配置 map_save_interval 控制。

重要规范（必看）

PlayerMetaData 是所有模组共用的，为了避免键名冲突，必须给你的 key 加模组名前缀。

例子：

• 任务模组的分数 → fancy_quests:score
• 生物模组的分数 → fancy_mobs:score

NodeMetaData

NodeMetaData 让你可以给世界里的每一个方块绑定独立的持久化键值数据，完全继承 MetaData 所有方法。
它最常用的功能是给箱子、熔炉等方块存储背包与界面。

传统方块只能存这些（非常少）

• 方块ID（名称）
• param1：通常用于光照（0–255）
• param2：旋转、颜色、形状等（0–255）

有了 NodeMetaData，你想存多少就存多少。

ModStorage

ModStorage 是每个世界、每个模组独立的持久化字符串键值存储，完全继承 MetaData 的所有方法。

保存机制

数据的保存频率由服务器配置 map_save_interval 决定。

MetaData

MetaData 是一个通用键值存储接口，用于给对象持久化保存字符串数据。
下面所有方法，在它的所有子类里都可以用。

子类（它管哪些东西）

• ModStorage：模组全局存储（整个模组共用）
• NodeMetaData：地图上的单个方块存储
• ItemStackMetaData：物品堆存储
• PlayerMetaData：玩家存储

ItemStackMetaData

ItemStackMetaData 是 MetaData 的子类，通过 stack:get_meta() 获取，用于给物品堆绑定持久化的键值对数据。