Skip to content

[resource] 材质图标与材料模型收敛:注册范围裁剪、继承回退树、去空占位与动态绘制方案 #384

Open

Description

@Tanimodori

本课题属总课题「资源体积治理」:#383 。全包空间账本、跨模块对比与总路线图见该课题。

所属阶段:跨越 Phase 1(Step 1:范围裁剪与去空占位) → Phase 2(Step 2:继承回退树与模型虚拟化)

依赖关系:


一、现状与量化诊断

在 1.0.7 成品 JAR(1.21.1)中,材质图标相关贴图占整包贴图体积的 45.7%(5.06 MiB):

目录 源码 (851c92179) 1.0.7 JAR (含 82 coin 残留) 唯一 SHA-1 冗余副本 全透明空图 唯一调色板同构 唯一 Alpha
textures/item/material_icons/ 8,118 PNG (41×99×2) 8,200 PNG (3.67 MiB) 441 7,759 (3.41 MiB) 3,177 333 291
textures/block/material_icons/ 2,676 文件 (2,624 PNG + 52 mcmeta) 2,676 文件 (1.39 MiB) 79 2,545 (1.31 MiB) 1,341 68 28
models/item/material/ 4,018 JSON (41×98) 折叠进 model-json-aliases.json — — — — —
models/block/material/ 453 JSON (41×11+2) 折叠进 model-json-aliases.json — — — — —
小计 15,265 源文件 10,876 JAR 条目 / 5.06 MiB 520 10,304 (4.72 MiB) 4,518 401 319

核心矛盾:磁盘有 10,824 张 PNG(源码去 coin 后 10,742 张),但实际承载的唯一图像仅有 520 张,且其中 4,518 张是 Alpha 全 0 的全透明空图。


二、问题根因(代码与注册范围核查)

  1. 6 个 MaterialTextureSet 在代码与材料表中零引用:
    • FLUID、GAS、HEX、NETHERSTAR、PLASMA、RAD 在材料目录和 Java 注册逻辑中为 0 引用(仅 FluidVisualPolicy 以字符串路径借用过 fluid/molten、fluid/gas、plasma/gas),平白多出 ~1,572 个不可达文件。
    • 其余 35 个有效 set 高度长尾:FINE(158)、DULL(144)、METALLIC(127)、RUBY(60) 占主体,而 CUBE_SHINY、FOOD、GLASS、NONE、OPAL、PAPER、RUBBER、SPACE 等 8 个 set 各仅服务 1 个材质。
  2. 形态维度未与实际注册投影对齐:
    • 物品侧:candidatePrefixes() 有 98 个前缀,~29,912 个实际物品仅投影到 2,246 个唯一 (set, prefix) 组合(占 41×98 = 4,018 的 55.9%),且磁盘多出不在 candidatePrefixes() 中的 void/void_overlay(82 张);
    • 方块侧:BlockMaterialPrefix 共 13 个注册项,~3,520 个材料方块仅投影到 254 个唯一 (set, prefix) 组合,贴图目录却按 32 个文件名 × 41 × 2 铺开(膨胀 5.17×,19 个基名根本不在方块注册中)。
  3. 模型硬编码无条件声明双层,强迫 void.png 存在:
    • MaterialIconDefinitions.generatedModelJson() 硬编码写入 "layer0" + "layer1",导致物品侧 4,059 张 _overlay 中有 3,089 张(76.1%) 为全透明空图;
    • BlockMaterialIcons.sharedModelJson() 同样硬编码 composite 双子模型(layer0 solid + layer1 cutout),导致方块侧 1,312 张 _overlay 中有 1,300 张(99.1%) 为全透明空图,还让普通材料方块多渲染一遍 6 面立方体。
  4. 缺失外观集继承回退树:100 个形态中有 38 个在全部 41 套中像素完全一致,ingot 全 41 套仅 9 种唯一图像,但每个 set 都硬拷贝了全套文件。

三、分阶段实施方案

Step 1(Phase 1:注册范围裁剪 + 消除无条件空 overlay — 立省 ~2.0+ MiB)

  1. 迁出流体借用并删除零引用与不可达资产:将 FluidVisualPolicy 实际引用的 3 张贴图迁至 block/fluids/ 后,删除 6 个零引用 MaterialTextureSet 的目录与模型,删除不在 (有效 set × 合法 prefix) 投影内的所有不可达文件。
  2. 模型按存在层按需生成:修改 MaterialIconDefinitions 与 BlockMaterialIcons / SharedInventoryModelPack:无有效 _overlay 时,物品模型仅生成单层 layer0,方块模型仅生成单层 cube_all(直接取消无意义的 cutout pass);直接删除全部 4,518 张全透明空 PNG。

Step 2(Phase 2:引入 MaterialTextureSet 继承回退树 + 模型虚拟化 — 再省 ~2.5 MiB)

  1. 引入父级继承回退链(对标 GregTech-Modern):为 MaterialTextureSet 增加 @Nullable MaterialTextureSet parent() 回退链(如 SHINY -> METALLIC -> DULL、EMERALD/DIAMOND/OPAL -> RUBY、SPACE/PAPER/WOOD -> DULL),在 MaterialIconDefinitions、BlockMaterialIcons 与 MaterialBlockClientModels 中沿继承链探测存在的贴图路径;删除所有与父集字节一致的冗余副本,将材料贴图收敛至 ≤520 张唯一图像。
  2. 材料模型 JSON 全虚拟化收口:借助 SharedInventoryModelPack 在内存中按需生成这几百个共享 (set, prefix) 模板 JSON,移除磁盘静态 core/models/item/material/(4,018 文件)与 minecraft/models/block/material/(453 文件)。
  3. 与 Phase 3 衔接:经 Step 1–2 收敛后最终保留下来的少量静态材料贴图(若其中存在同构灰度变体可评估双层 ItemColor 拆分),其余静态 16×16 贴图交由 [resource] 同模板换色资产动态分层绘制与原版 unstitch 图集压缩(木桶/瓶罐/流体/零散图标) #397 · Step 2 统一打入 minecraft:unstitch spritesheet。
    • 技术红线:禁止使用 minecraft:paletted_permutations 按材料展开(会撑爆 GPU 图集),禁用 NeoForge 独占的 RegisterSpriteSourceTypesEvent。

四、验收标准

  • Phase 1:6 个零引用 MaterialTextureSet 及不可达 (set, prefix) 清理完成(FluidVisualPolicy 3 张流体图无缺失);material_icons 内 0 张全透明空 PNG,layer1/cutout 层仅在存在有效 overlay 时声明;
  • Phase 2:MaterialTextureSet 继承回退链落地,重复 SHA-1 副本清零;磁盘 models/{item,block}/material/ 静态 JSON 清零并由 SharedInventoryModelPack 承接;
  • 双平台(1.20.1 Forge / 1.21.1 NeoForge)实机验证全部已注册材料物品、材料方块、矿石与创造页图标渲染完全一致,无缺失模型/缺失纹理警告。

Activity

  1. added
    enhancement建议总类 / Suggestion umbrella
    needs triage等待维护者分类 / Awaiting maintainer triage
    perf卡顿、内存、启动或注册耗时 / Lag, memory, startup or registration cost
    scope: uiGUI、tooltip、Jade/EMI/JEI、模型、贴图与渲染 / GUI, tooltips, Jade/EMI/JEI, models, textures, rendering
    on Nov 13, 2026
  2. added
    priority: high崩溃、数据丢失或主要功能不可用 / Crash, data loss or major feature unusable
    refactor重构、清理、内部实现调整,不改变对外行为 / Refactor, cleanup or internal change without external behavior change
    and removed
    needs triage等待维护者分类 / Awaiting maintainer triage
    on Nov 13, 2026
  3. added this to the v1.0.7 milestone on Nov 13, 2026
  4. added
    scope: material材料注册、ID、形态、成分、统一化与流体属性 / Materials: IDs, forms, composition, unification, fluids
    on Nov 14, 2026
  5. self-assigned this
    on Nov 14, 2026
  6. changed the title [-][resource] 材质图标按「外观集 × 形态」全量展开,未按实际物品需求生成[/-] [+][resource] 材质图标与材料模型收敛:注册范围裁剪、继承回退树、去空占位与动态绘制方案[/+] on Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancement建议总类 / Suggestion umbrellaperf卡顿、内存、启动或注册耗时 / Lag, memory, startup or registration costpriority: high崩溃、数据丢失或主要功能不可用 / Crash, data loss or major feature unusablerefactor重构、清理、内部实现调整,不改变对外行为 / Refactor, cleanup or internal change without external behavior changescope: material材料注册、ID、形态、成分、统一化与流体属性 / Materials: IDs, forms, composition, unification, fluidsscope: uiGUI、tooltip、Jade/EMI/JEI、模型、贴图与渲染 / GUI, tooltips, Jade/EMI/JEI, models, textures, rendering

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions