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() 获取，用于给物品堆绑定持久化的键值对数据。

硬编码功能列表

这里列出 Luanti 引擎里写死、无法被模组自定义的功能。
长期目标是把这些都改成可配置，但目前暂时改不了。

游戏玩法

血量与伤害

• 坠落伤害计算公式是写死的
• 伤害方块固定 1 秒掉一次血，不能改间隔
• 氧气机制写死：
  • 每 2 秒掉一次氧气或溺水伤害
  • 每 0.5 秒恢复一次氧气
• 受伤时的屏幕变红效果时长固定
• 受伤时的屏幕震动固定

物品

• 工具挖掘速度公式写死（只能改参数，不能改公式）
• 工具耐久损耗公式写死
• 所有物品都能指向方块，无法关闭
• range=0 不生效，因为在方块内部依然能指向

玩家

• 所有相机模式永远可用，无法禁用或强制

画面表现

• 受伤屏幕闪红
• 受伤屏幕震动
• 太阳光带轻微黄色
• 黑暗带轻微蓝色
• 光照曲线固定（每个亮度等级的显示效果）
• 全局光色固定
• 物品 3D 展示模型：角度、旋转写死
• inventory_image 只支持 2D 图
• 挖掘粒子的数量、大小、生命周期写死
• 手持物品/空手的画面表现几乎不能自定义

HUD 界面

• 聊天窗口位置不能被模组移动
• 状态提示文字（如“已开启飞行模式”）不能移动或隐藏
• Formspec 样式大量写死，无法自定义：
  • 滚动条
  • 下拉框
  • 选中文本高亮色
  • 文字阴影

控制按键

• 鼠标滚轮固定切换快捷栏，无法改绑其他功能

可以接受的硬编码（没问题）

• Esc 键 = 暂停/退出
• 调试界面内容（但可选择显示多少）
• WASD / 摇杆移动