Skip to content
酷学小栈

luanti API 纹理修饰器

纹理修饰器 纹理修饰器是一串告诉 Luanti 如何处理图片的字符串,除动态媒体外,它是 运行时动态生成纹理 的唯一方式。 它也能用来简化模组,批量生成重复纹理,比如不同颜色的工具贴图。 ℹ️ 说明 纹理修饰器和硬件着色功能部分重叠。 优先使用硬件着色 ,更灵活、产生的冗余纹理更少。 性能问题 所有纹理在 CPU…

On this page
  1. 性能问题
  2. 已知 Bug
  3. 材质包(Texture Packs)
  4. 在 Lua 中使用
  5. API
  6. 字符串写法
  7. 语法
  8. 叠加(Overlaying)
  9. 参数转义
  10. 分组(括号)
  11. 组合型修饰器(多图合并)
  12. 基础纹理修饰器
  13. <base>^[brighten
  14. <base>^[noalpha
  15. <base>^[makealpha:<r>,<g>,<b>
  16. <base>^[opacity:<ratio>
  17. <base>^[invert:<mode>
  18. <base>^[transform<transforms>
  19. <base>^[verticalframe:<framecount>:<frame>
  20. <base>^[crack[<opacity>]:[<framecount>:]<tilecount>:<frame>
  21. <base>^[sheet:<w>x<h>:<x>,<y>
  22. <base>^[multiply:<color>
  23. <base>^[colorize:<color>[:<ratio>]
  24. <base>^[mask:<texture>
  25. <base>^[lowpart:<percent>:<texture>
  26. 基础纹理生成器(不需要底图)
  27. [png:<data>
  28. [combine:<w>x<h>:<x>,<y>=<tex>:...
  29. [inventorycube{<top>{<left>{<right>
  30. 破损方块
  31. 裁切
  32. 进度条
  33. 嵌套 combine(分辨率相关)
  34. lowpart + 旋转(分辨率无关)

纹理修饰器

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

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

性能问题

  • 所有纹理在 CPU 生成,不在 GPU,速度慢,可能短暂卡住客户端线程
  • 纹理修饰器会永久留在客户端内存
  • 生成新修饰器时不会复用缓存
  • 解析器可能出现至少是二次方的时间复杂度

建议:

  • 尽量静态使用纹理修饰器
  • 动态生成的纹理越少越好,避免撑爆客户端缓存
  • 不要短时间内让客户端大量生成高开销纹理
  • 尽量别写又长又复杂的修饰器

已知 Bug

  • 大型修饰器可能卡死客户端
  • 部分修饰器可能导致越界内存读取,例:[lowpart:0:blank.png
  • 越界像素通常被当成纯白色(#FFFFFFFF)
  • 非法修饰器可能导致客户端段错误
  • 语法错误的部分可能被静默忽略

材质包(Texture Packs)

  • 纹理修饰器可用于方块、物品的纹理覆盖
  • 修饰器生成的纹理不能被材质包直接替换(只能通过覆盖替换),只有基础纹理可以
  • 部分修饰器依赖固定分辨率,低分辨率材质包通常可以向上缩放,高分辨率则需要缩小

💡 小贴士 用 [resize 强制缩放到你需要的尺寸,能更好地兼容各种材质包。


在 Lua 中使用

API

core.inventorycube(top, left, right) 唯一自带的纹理修饰工具函数。

参数:

  • top、left、right:字符串,对应面的纹理修饰器

返回: 生成 [inventorycube{<top>{<left>{right> 格式修饰器,并自动转义。


字符串写法

Lua 有三种字符串写法:双引号、单引号、长字符串。 纹理名一般不包含引号,所以用哪种都行。

  • 引号字符串里写反斜杠需要转义: a.png^[mask:b.png\^c.png 写成 "a.png^[mask:b.png\\^c.png"

  • 长字符串用双方括号 [[...]],内部不需要转义,非常适合写纹理修饰器: [[[combine:1x1:0,0=a.png]]

💡 小贴士 可以用元方法实现一套优雅的 DSL,帮你自动转义与格式化。


语法

⚠️ 警告 纹理修饰器只在客户端解析,服务器不做校验。出错轻则显示错误纹理,重则直接崩溃。 务必保证语法正确、数值合法。

基础规则:

  • <...> 表示必填参数
  • [...] 表示可选
  • 所有范围都是闭区间(包含起止值)

叠加(Overlaying)

用 ^ 符号实现叠加:

  • 右侧纹理覆盖在左侧之上
  • 支持链式:a^b^c
  • 叠加前,像素少的纹理会缩放到多的那一张
  • 正确处理 Alpha 混合

参数转义

用反斜杠 \ 转义,只在组合型修饰器内需要。 必须转义:^、:、\。

嵌套转义需要翻倍反斜杠:n 层嵌套需要 2ⁿ 个反斜杠。

inventorycube 转义规则特殊:

  • ^ 换成 &
  • 不支持嵌套

示例转义函数:

local function escape_argument(texture_modifier)
return texture_modifier:gsub(".", {
["\\"] = "\\\\",
["^"] = "\\^",
[":"] = "\\:"
})
end

分组(括号)

用括号 () 强制优先计算,只对叠加有效。 不能在组合修饰器里用来分隔参数,必须用转义。

错误:a^[lowpart:1:(b^c) 正确:a^[lowpart:1:b\^c


修饰器列表

所有修饰器都生成新纹理,不修改原图。


组合型修饰器(多图合并)

  • [mask:按位遮罩
  • [lowpart:贴下半部分
  • [combine:按坐标拼贴多图
  • [inventorycube:生成物品栏立方体

基础纹理修饰器

<base>^[brighten

每个像素颜色与白色50% 混合,提亮。

<base>^[noalpha

把 Alpha 通道强制设为 255(完全不透明)。

<base>^[makealpha:<r>,<g>,<b>

把 RGB 完全匹配的像素设为透明。

<base>^[opacity:<ratio>

透明度整体缩放,ratio 0~255。

<base>^[invert:<mode>

反色通道,mode 可包含 r/g/b/a。

<base>^[transform<transforms>

旋转/翻转,支持数字或名称(不区分大小写):

数字 名称 效果
0 I 不变
1 R90 逆时针90°
2 R180 逆时针180°
3 R270 逆时针270°
4 FX 水平翻转
5 FXR90 水平翻转+逆时针90°
6 FY 垂直翻转
7 FYR90 垂直翻转+逆时针90°

<base>^[verticalframe:<framecount>:<frame>

按帧数垂直裁切动画纹理。 ⚠️ framecount=0 会除零崩溃客户端。

<base>^[crack[<opacity>]:[<framecount>:]<tilecount>:<frame>

在纹理上叠加破损动画(crack_anylength.png)。

  • opacity 填 o → 只在完全不透明区域显示破损
  • tilecount:分块数,通常 1
  • frame:当前破损帧

<base>^[sheet:<w>x<h>:<x>,<y>

从精灵图中截取一格。

<base>^[multiply:<color>

RGB 通道与颜色相乘,忽略 Alpha。

<base>^[colorize:<color>[:<ratio>]

颜色混合:

  • ratio 0~255:0=原图,255=纯颜色
  • 填 alpha:按纹理自身透明度混合

<base>^[mask:<texture>

按位与遮罩,只保留重叠不透明部分。

<base>^[lowpart:<percent>:<texture>

把另一张图的下百分之 N 贴上来。


基础纹理生成器(不需要底图)

[png:<data>

从 base64 编码的 PNG 生成纹理。

"[png:" .. core.encode_base64(core.encode_png(w, h, data))

⚠️ Luanti 5.4 及以下不支持,用作方块贴图可能崩溃。

[combine:<w>x<h>:<x>,<y>=<tex>:...

创建指定尺寸的透明图,按坐标拼贴其他纹理。 背景:透明黑 #00000000。

[inventorycube{<top>{<left>{<right>

用三张图生成物品栏立方体图标。 尺寸公式:9 * max(4, min(64, 2^ceil(log2(max_size))))


实用示例

破损方块

default_stone.png^[crack:1:2

裁切

裁掉左上6px(16x16→8x8): [combine:8x8:-8,-8=default_stone.png

进度条

嵌套 combine(分辨率相关)

[combine:256x48:0,0=bg.png:0,0=[combine\:128x48\:0,0=bar.png

lowpart + 旋转(分辨率无关)

bg.png^[transformR90^[lowpart:50:bar.png\^[transformR90^[transformR270