🖼️ 图像

快速入门

图像系统的本质就是把 PNG 图片变成字符，让你可以在任意文本中使用它们。下面是最短的上手路径——从零到在游戏里看到效果：

第一步 — 在任意包的 configuration/ 目录下创建图像配置：

images:
  my_pack:star:
    height: 10
    ascent: 9
    font: my_pack:ui
    file: my_pack:font/ui/star.png

第二步 — 在物品名称中使用它：

items:
  my_pack:star_sword:
    material: diamond_sword
    data:
      item_name: "<!i><white><image:my_pack:star> 星剑"

就这么简单。<image:命名空间:id> 标签会把你图像对应的字符插入到文本中，该字符绑定了你指定的字体，Minecraft 渲染时就会显示为你的图片。

接下来的内容逐一拆解：怎么配置图像、怎么在不同场景中使用、以及怎么把多个图像组合成复杂的 UI。

图像配置

基本字段

图像配置写在任意包的 images: 节点下，每个图像以 命名空间:id 作为唯一标识。

images:
  internal:item_browser:
    height: 140        # 每个字形的高度（像素）。别名：scale, scale_ratio
    ascent: 18         # 相对于文本基线的垂直偏移。别名：y_position
    font: minecraft:internal
    file: minecraft:font/gui/custom/item_browser.png
    char: '\ub000'     # 可选。别名：chars, unicode

字段	是否必填	说明
`file`	是	PNG 文件路径。`.png` 后缀会自动补全。
`height`	自动检测	每个字形的高度。不填则自动读取 PNG 实际高度。
`ascent`	默认 `height - 1`	基线偏移量。增大该值会让图像在屏幕上往上移。
`font`	默认 `命名空间:default`	图像所属的字体。
`char`	自动分配	映射到此图像的码位。

警告

height 必须 ≥ ascent，这是 Minecraft 的硬性限制。
单个字形不得超过 256×256 像素。注意：这里指的是精灵图中的每一个格子，不是整张 PNG。

字符的几种写法

不填 char 时，插件会自动挑选一个空闲码位——推荐这样做，完全没有冲突风险。

如果需要手动指定：

# 固定码位
char: '\ub000'

# 数字形式
char: 1000

# 直接写字
char: '我'

垂直定位

ascent 控制字形相对于文本基线的位置。值越大，图像越靠上。

如果图像需要往上移但 ascent 已经等于 height 无法再加（受限于 ascent ≤ height 规则），可以在 PNG 图片的底部增加透明像素来拉高图片尺寸，这样 height 变大后就能设置更大的 ascent 了。

精灵图

当一张 PNG 里排列了多个图标（像精灵图那样），用 chars 逐行定义：

images:
  default:icons:
    height: 10
    ascent: 9
    font: minecraft:icons
    file: minecraft:font/image/icons.png
    chars:
     - '\ub000\ub001\ub002'   # 第 0 行
     - '\ub003\ub004\ub005'   # 第 1 行

每行是一个字符串，行内字符从左到右依次对应格子。所有行的字符数必须一致。

用 grid_size 自动排列

不想手动管字符分配的话，直接用 grid_size 让插件全自动处理：

images:
  default:icons:
    height: 10
    ascent: 9
    font: minecraft:icons
    file: minecraft:font/image/icons.png
    grid_size: 2,3   # 2 行 × 3 列 → 共 6 格

引用单个格子

给精灵图中的某个格子起一个有意义的名字：

images:
  # 短格式
  default:angry:
    ref: default:emojis:0:1

  # 长格式
  default:sad:
    ref: default:emojis
    row: 0
    column: 2

引用不需要 file、height 或 font——它只是指向已有位图的某个格子。

使用图像

MiniMessage 标签

物品名称、Lore、聊天消息、GUI 标题——所有解析 MiniMessage 的地方都能用：

<image:命名空间:id>
<image:命名空间:id:行>
<image:命名空间:id:行:列>
<image:命名空间:id:行:列:格式>

# 第一个格子
item_name: "<!i><white><image:default:icons> 黄玉钓竿"

# 指定格子
item_name: "<!i><white><image:default:icons:0:1> 黄玉钓竿"

# 给字形本身添加格式
item_name: "<!i><red><image:default:icons:0:1:'<!shadow><white>'> 黄玉钓竿"

可选的 format 参数会在图像字符前面追加 MiniMessage 样式——一般用于消除阴影或调整颜色。

预览调试

/ce debug image <命名空间:id> [行] [列]

执行后会输出三个可直接点击复制的按钮：

MiniMessage：<font:命名空间:字体名>字符</font>
MineDown：[字符](font=命名空间:字体名)
RAW JSON：{"text":"字符","font":"命名空间:字体名"}

包级标签

对于本身不支持 MiniMessage 的插件，CraftEngine 可以在网络包层面拦截并替换 <image:命名空间:id> 标签。详见下方兼容性一节，并在 config.yml → network.intercept-packets 中启用需要的通道。

用 Image 与 Shift 搭建 UI

<shift> 和 <image> 是构建自定义游戏界面的两块积木。<shift:N> 插入一个字符，其字形宽度让后续文本产生 N 像素的水平位移（负值左移，正值右移）。

把它们串联起来就能组合出各种布局：

title: "<white><shift:-11><image:internal:cooking_recipe><shift:-136><image:internal:blasting>"

逐个拆解：

<shift:-11> — 左移 11 像素，让整体居中
<image:internal:cooking_recipe> — 第一个图标
<shift:-136> — 再次左移，为第二个图标腾位置
<image:internal:blasting> — 第二个图标紧挨在右边

每个 shift 值背后都是一个精心调整了 height/ascent 的预配置图像，用来产生精确的像素位移：

# config.yml
image:
  offset-characters:
    enable: true
    font: minecraft:default
    -1: ''
    1: ''
    # ... 范围覆盖 -256 到 +256

注意

除非你完全理解 Minecraft 字形度量机制，否则不要修改 offset-characters。错误的值会破坏文本布局。

配置参考

config.yml 中的 image 部分：

image:
  # 阻止玩家直接输入原始码位字符
  illegal-characters-filter:
    anvil: true
    book: true
    chat: true
    command: true
    sign: true

  # 自动分配码位的起始值，可按字体分别设置
  codepoint-starting-value:
    default: 19968
    overrides:
      minecraft:default: 57344

信息

该用什么字体？ 除了 minecraft:default 以外的自定义字体天然安全——玩家只能在 minecraft:default 字体下输入字符，无法直接打出属于其他字体的字形。

只有在必要场景（如原版语言文件）才使用 minecraft:default，此时务必保持 illegal-characters-filter 开启。

兼容性

PlaceholderAPI

%image_mm_命名空间:id[:行:列]%   # MiniMessage 格式
%image_md_命名空间:id[:行:列]%   # MineDown 格式
%image_raw_命名空间:id[:行:列]%  # 原始字符

完整列表见 PlaceholderAPI 兼容页。

包拦截

对于不支持 MiniMessage 的插件，CraftEngine 可以在网络包层面拦截并替换标签。根据需要开启对应通道：

network:
  intercept-packets:
    system-chat: true
    actionbar: true
    title: true
    bossbar: true
    container: true
    item: true
    # ... 等等

提示

每个拦截器都会给 Netty 线程增加负担。关闭不需要的通道可以优化 Netty 性能。

语言文件

原版语言文件（assets/minecraft/lang/*.json）始终使用 minecraft:default 渲染，因此用在其中的图像必须使用该字体：

images:
  test:custom_ui:
    height: 140
    ascent: 18
    font: minecraft:default
    file: minecraft:font/gui/custom/gui.png

langs:
  en_us:
    container.custom_furnace: "<image:test:custom_ui>"

快速入门​

图像配置​

基本字段​

字符的几种写法​

垂直定位​

精灵图​

用 grid_size 自动排列​

引用单个格子​

使用图像​

MiniMessage 标签​

预览调试​

包级标签​

用 Image 与 Shift 搭建 UI​

配置参考​

兼容性​

PlaceholderAPI​

包拦截​

语言文件​