https://pangz.fun/icon.png 还要再走500里 2026-04-16T08:43:14.689Z https://pangz.fun/ 木辛念做梓 Hexo https://pangz.fun/luanti-lua-conventions.html 2026-04-16T08:41:47.000Z 2026-04-16T08:43:14.689Z

<h1 id="Lua-编码规范"><a href="#Lua-编码规范" class="headerlink" title="Lua 编码规范"></a>Lua 编码规范</h1><p>Lua 是一门简洁、极简、优雅、高效、可嵌入、表现力强的脚本语言。想要高效开发 Luanti 模组与游戏，必须熟练掌握 Lua。</p>

https://pangz.fun/luanti-API-timing-and-event-loop.html 2026-04-16T08:39:52.000Z 2026-04-16T08:40:40.642Z

<h1 id="计时与事件循环"><a href="#计时与事件循环" class="headerlink" title="计时与事件循环"></a>计时与事件循环</h1><p>Luanti 的 Lua API 可用于获取时间、日期，或调度<strong>一次性/每帧执行</strong>的事件。</p> <h2 id="设置项"><a href="#设置项" class="headerlink" title="设置项"></a>设置项</h2><ul> <li><strong>服务器</strong>：<code>dedicated_server_step</code> 控制<strong>服务端帧间隔</strong>，这是无忙等待时游戏循环的最大粒度。</li> <li><strong>单人模式</strong>：帧率决定服务端帧执行频率。</li> </ul>

https://pangz.fun/luanti-API-texture-modifiers.html 2026-04-16T08:38:18.000Z 2026-04-16T08:39:14.502Z

<h1 id="纹理修饰器"><a href="#纹理修饰器" class="headerlink" title="纹理修饰器"></a>纹理修饰器</h1><p>纹理修饰器是一串告诉 Luanti 如何处理图片的字符串，除动态媒体外，它是<strong>运行时动态生成纹理</strong>的唯一方式。<br>它也能用来简化模组，批量生成重复纹理，比如不同颜色的工具贴图。</p> <p>ℹ️ 说明<br>纹理修饰器和硬件着色功能部分重叠。<strong>优先使用硬件着色</strong>，更灵活、产生的冗余纹理更少。</p>

https://pangz.fun/luanti-API-persistence.html 2026-04-16T08:37:04.000Z 2026-04-16T08:37:52.814Z

<h1 id="数据持久化"><a href="#数据持久化" class="headerlink" title="数据持久化"></a>数据持久化</h1><p>本页概览 Luanti 提供的<strong>序列化与数据持久化方案</strong>。</p> <p>选择持久化方式主要看这些：</p> <ul> <li>数据结构与类型：数据长啥样？有哪些类型？</li> <li>数据大小与修改频率：能不能塞进内存？更新开销多大？</li> <li>所需粒度：数据需要多久存一次？</li> <li>查询需求：是否需要索引快速查找？</li> <li>数据绑定对象：物品？玩家？方块？</li> </ul>

https://pangz.fun/luanti-API-object-properties.html 2026-04-16T08:35:46.000Z 2026-04-16T08:37:14.374Z

<h1 id="对象属性"><a href="#对象属性" class="headerlink" title="对象属性"></a>对象属性</h1><p>本页面列出对象可拥有的全部属性。</p>

https://pangz.fun/luanti-API-modchannels.html 2026-04-16T08:34:32.000Z 2026-04-16T08:35:17.830Z

<h1 id="模组通信频道（Modchannels）"><a href="#模组通信频道（Modchannels）" class="headerlink" title="模组通信频道（Modchannels）"></a>模组通信频道（Modchannels）</h1><p>用于<strong>服务端模组（SSM）</strong> 和<strong>客户端模组（CSM）</strong> 互相发消息、双向通信。</p>

https://pangz.fun/luanti-API-luajit.html 2026-04-16T08:33:11.000Z 2026-04-16T08:34:03.604Z

<h1 id="LuaJIT"><a href="#LuaJIT" class="headerlink" title="LuaJIT"></a>LuaJIT</h1><p>LuaJIT 是一款面向 Lua 的<strong>即时编译器（JIT）</strong>，它完整实现了 <strong>Lua 5.1 标准</strong>（为区分起见，官方标准 Lua 称为 PUC Lua），同时附带一些扩展与差异。<br>LuaJIT 运行速度通常远快于 PUC Lua，因此<strong>强烈推荐使用</strong>。</p> <p>除非你编译 Luanti 时<strong>手动禁用了 LuaJIT</strong>，否则 Luanti 默认都会用 LuaJIT 作为 Lua 运行时。<br>官方 Windows、Android 以及大多数 Linux 发行版安装包，均已启用 LuaJIT。<br>你可以在终端执行这条命令确认：</p> <figure class="highlight plaintext"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">./luanti --version</span><br></pre></td></tr></tbody></table></figure>

https://pangz.fun/luanti-API-lua-environment.html 2026-04-16T08:29:19.000Z 2026-04-16T08:30:16.709Z

<h1 id="Lua-运行环境"><a href="#Lua-运行环境" class="headerlink" title="Lua 运行环境"></a>Lua 运行环境</h1><p>Luanti 采用 <strong>Lua 5.1</strong>。模组的实际运行环境取决于<strong>四大要素</strong>：</p> <ul> <li>操作系统</li> <li>Luanti 构建版本：LuaJIT（默认）或 PUC Lua 5.1</li> <li>模组类型：客户端侧（CSM）或服务端侧（SSM）</li> <li>模组环境：安全模式 或 不安全模式</li> </ul>

https://pangz.fun/luanti-API-http-api.html 2026-04-16T08:25:05.000Z 2026-04-16T08:26:35.659Z

<h1 id="HTTP-API"><a href="#HTTP-API" class="headerlink" title="HTTP API"></a>HTTP API</h1><p>HTTP API 允许模组发起网络请求（GET/POST 等）。</p> <h2 id="设置（必须配置）"><a href="#设置（必须配置）" class="headerlink" title="设置（必须配置）"></a>设置（必须配置）</h2><p>要使用此 API，模组必须在以下<strong>任一配置项</strong>中被列出（使用 CSV 格式，即逗号分隔）：</p> <ul> <li><code>secure.trusted_mods</code></li> <li><code>secure.http_mods</code></li> </ul>

https://pangz.fun/luanti-API-filesystem.html 2026-04-11T04:17:04.000Z 2026-04-11T04:19:29.822Z

<h1 id="文件系统（Filesystem）"><a href="#文件系统（Filesystem）" class="headerlink" title="文件系统（Filesystem）"></a>文件系统（Filesystem）</h1><p>Luanti 提供大量工具函数，用于管理<strong>路径、文件、文件夹</strong>。</p> <h1 id="重要说明"><a href="#重要说明" class="headerlink" title="重要说明"></a>重要说明</h1><p>模组安全系统会<strong>限制文件访问路径</strong>：</p> <ul> <li>加载时：只能访问<strong>当前模组目录（mod path）</strong></li> <li>运行时：只能访问<strong>世界存档目录（world path）</strong><br>详见：Lua 环境（Lua Environment）</li> </ul>

https://pangz.fun/luanti-API-Classes-voxelarea.html 2026-04-11T04:15:31.000Z 2026-04-11T04:16:27.805Z

<h1 id="VoxelArea"><a href="#VoxelArea" class="headerlink" title="VoxelArea"></a>VoxelArea</h1><p>VoxelArea 是用于<strong>VoxelManip（地图区块操作）<strong>的面向对象工具类，专门用来</strong>计算坐标索引</strong>，避免手写复杂的三维下标公式。</p> <hr> <h2 id="VoxelArea-new-self-o"><a href="#VoxelArea-new-self-o" class="headerlink" title="VoxelArea.new(self, o)"></a>VoxelArea.new(self, o)</h2><p>创建一个 VoxelArea 实例。<br>会自动设置 <code>self.__index = self</code>，并将 <code>self</code> 设为 <code>o</code> 的元表。</p> <h3 id="必须字段"><a href="#必须字段" class="headerlink" title="必须字段"></a>必须字段</h3><ul> <li><strong>MinEdge</strong>：区域最小坐标（包含）<br>为整数向量，默认 <code>vector.new(1, 1, 1)</code></li> <li><strong>MaxEdge</strong>：区域最大坐标（包含）<br>为整数向量，默认 <code>vector.new(0, 0, 0)</code></li> </ul>

https://pangz.fun/luanti-API-Classes-vector.html 2026-04-11T03:51:26.000Z 2026-04-11T04:15:04.388Z

<h1 id="向量-API"><a href="#向量-API" class="headerlink" title="向量 API"></a>向量 API</h1><p>Vector（向量）过去只是带 <code>x</code>/<code>y</code>/<code>z</code> 的普通表，现在已升级为带元表的增强类型。<br>除非特别说明，本文提到的 <code>vector</code> 均指<strong>带元表的向量</strong>。</p> <h2 id="vector-命名空间函数"><a href="#vector-命名空间函数" class="headerlink" title="vector 命名空间函数"></a>vector 命名空间函数</h2><h3 id="vector-new-a-b-c"><a href="#vector-new-a-b-c" class="headerlink" title="vector.new(a, b, c)"></a><code>vector.new(a, b, c)</code></h3><p>创建新向量。</p> <ul> <li><code>a</code>、<code>b</code>、<code>c</code> 为数字 → 返回 <code>{x=a, y=b, z=c}</code></li> <li><code>a</code> 是向量 → 等价 <code>vector.copy(a)</code></li> <li>全空 → 等价 <code>vector.zero()</code></li> </ul>

https://pangz.fun/luanti-API-Classes-raycast.html 2026-04-11T03:50:17.000Z 2026-04-11T03:51:04.157Z

<h1 id="射线检测（Raycast）"><a href="#射线检测（Raycast）" class="headerlink" title="射线检测（Raycast）"></a>射线检测（Raycast）</h1><p>射线用于模拟一条“线”，检测它碰到了哪些<strong>选择箱</strong>（selection box）。<br>效果和玩家准星指向几乎完全一样（有少量限制）。</p> <h2 id="指向结果（pointed-thing）格式"><a href="#指向结果（pointed-thing）格式" class="headerlink" title="指向结果（pointed_thing）格式"></a>指向结果（pointed_thing）格式</h2><p>射线碰到的东西只有 3 种：</p> <ol> <li><strong>nothing</strong>：没碰到任何东西</li> <li><strong>object</strong>：实体、生物、玩家</li> <li><strong>node</strong>：方块（固体/液体）</li> </ol>

https://pangz.fun/luanti-API-Classes-random.html 2026-04-11T03:48:32.000Z 2026-04-11T03:49:43.617Z

<h1 id="随机数（Random）"><a href="#随机数（Random）" class="headerlink" title="随机数（Random）"></a>随机数（Random）</h1><p>Luanti 提供<strong>四种随机数生成器</strong>，各有优缺点，模组开发者需要根据场景选择。</p> <h2 id="Lua-内置随机（全局）"><a href="#Lua-内置随机（全局）" class="headerlink" title="Lua 内置随机（全局）"></a>Lua 内置随机（全局）</h2><p>不受模组安全限制，服务端和客户端模组都能用。</p> <h3 id="math-randomseed-seed"><a href="#math-randomseed-seed" class="headerlink" title="math.randomseed(seed)"></a><code>math.randomseed(seed)</code></h3><p>设置全局随机种子。<br>引擎<strong>已经用系统时间自动帮你设置过</strong>。</p>

https://pangz.fun/luanti-API-Classes-playermetadata.html 2026-04-11T03:47:27.000Z 2026-04-11T03:48:07.646Z

<h1 id="PlayerMetaData"><a href="#PlayerMetaData" class="headerlink" title="PlayerMetaData"></a>PlayerMetaData</h1><p>PlayerMetaData 是<strong>每个世界、每个玩家独立</strong>的持久化字符串键值存储，<strong>完全继承 MetaData 所有方法</strong>。</p> <h2 id="保存频率"><a href="#保存频率" class="headerlink" title="保存频率"></a>保存频率</h2><p>数据保存间隔由服务器配置 <code>map_save_interval</code> 控制。</p> <h2 id="重要规范（必看）"><a href="#重要规范（必看）" class="headerlink" title="重要规范（必看）"></a>重要规范（必看）</h2><p>PlayerMetaData 是<strong>所有模组共用</strong>的，为了避免键名冲突，<strong>必须给你的 key 加模组名前缀</strong>。</p> <p>例子：</p> <ul> <li>任务模组的分数 → <code>fancy_quests:score</code></li> <li>生物模组的分数 → <code>fancy_mobs:score</code></li> </ul>

https://pangz.fun/luanti-API-Classes-nodemetadata.html 2026-04-11T03:46:11.000Z 2026-04-11T03:46:57.146Z

<h1 id="NodeMetaData"><a href="#NodeMetaData" class="headerlink" title="NodeMetaData"></a>NodeMetaData</h1><p>NodeMetaData 让你可以给<strong>世界里的每一个方块</strong>绑定独立的持久化键值数据，完全继承 MetaData 所有方法。<br>它最常用的功能是给箱子、熔炉等方块<strong>存储背包与界面</strong>。</p> <h2 id="传统方块只能存这些（非常少）"><a href="#传统方块只能存这些（非常少）" class="headerlink" title="传统方块只能存这些（非常少）"></a>传统方块只能存这些（非常少）</h2><ul> <li>方块ID（名称）</li> <li>param1：通常用于光照（0–255）</li> <li>param2：旋转、颜色、形状等（0–255）</li> </ul> <p>有了 NodeMetaData，你想存多少就存多少。</p>

https://pangz.fun/luanti-modstorage.html 2026-04-11T03:43:13.000Z 2026-04-11T03:44:30.940Z

<h1 id="ModStorage"><a href="#ModStorage" class="headerlink" title="ModStorage"></a>ModStorage</h1><p>ModStorage 是<strong>每个世界、每个模组独立</strong>的持久化字符串键值存储，<strong>完全继承 MetaData 的所有方法</strong>。</p> <h2 id="保存机制"><a href="#保存机制" class="headerlink" title="保存机制"></a>保存机制</h2><p>数据的保存频率由服务器配置 <code>map_save_interval</code> 决定。</p>

https://pangz.fun/luanti-metadata.html 2026-04-11T03:41:31.000Z 2026-04-11T03:42:51.917Z

<h1 id="MetaData"><a href="#MetaData" class="headerlink" title="MetaData"></a>MetaData</h1><p>MetaData 是一个<strong>通用键值存储接口</strong>，用于给对象持久化保存字符串数据。<br>下面所有方法，在它的<strong>所有子类</strong>里都可以用。</p> <h2 id="子类（它管哪些东西）"><a href="#子类（它管哪些东西）" class="headerlink" title="子类（它管哪些东西）"></a>子类（它管哪些东西）</h2><ul> <li><strong>ModStorage</strong>：模组全局存储（整个模组共用）</li> <li><strong>NodeMetaData</strong>：地图上的单个方块存储</li> <li><strong>ItemStackMetaData</strong>：物品堆存储</li> <li><strong>PlayerMetaData</strong>：玩家存储</li> </ul>

https://pangz.fun/luanti-itemstackmetadata.html 2026-04-11T03:39:16.000Z 2026-04-11T03:41:09.796Z

<h1 id="ItemStackMetaData"><a href="#ItemStackMetaData" class="headerlink" title="ItemStackMetaData"></a>ItemStackMetaData</h1><p>ItemStackMetaData 是 <strong>MetaData 的子类</strong>，通过 <code>stack:get_meta()</code> 获取，用于<strong>给物品堆绑定持久化的键值对数据</strong>。</p>

https://pangz.fun/luanti-list-of-hardcoded-features.html 2026-04-09T12:26:51.000Z 2026-04-09T12:27:22.914Z

<h1 id="硬编码功能列表"><a href="#硬编码功能列表" class="headerlink" title="硬编码功能列表"></a>硬编码功能列表</h1><p>这里列出 Luanti