RedFoxExpand

RedFoxExpand

RedFoxExpand 是由 RedFox团队 开发的 Minecraft 26.2 / 1.8.9 / 1.7.10 客户端 Mod。它允许材质包作者通过 RedFoxExpand is a Minecraft 26.2 / 1.8.9 / 1.7.10 client-side Mod developed by the RedFox Team. It allows resource pack authors to modify container GUIs through

原生小写资源域、Schema v2/v3/v3.1 JSON 配置和现代渲染管线修改容器 GUI，而不必修改或重新编译 Mod。 the native lowercase resource namespace, Schema v2/v3/v3.1 JSON configurations, and the modern rendering pipeline — without modifying or recompiling the Mod.

• 当前版本：0.2.2（Git Tag：v0.2.2）

- Current Version: 0.2.2 (Git Tag: v0.2.2)

• 运行端：仅客户端

- Environment: Client-side only

项目实例演示 Project Demo

功能状态 Feature Status

已实现 Implemented

• 通过 Fabric Resource Loader 读取 assets/kyeitk/redfoxexpand/index.json 原生 manifest；

- Reads the native manifest from assets/kyeitk/redfoxexpand/index.json through the Fabric Resource Loader;

• 严格校验 Schema v2、路径、JSON、PNG、动画与数量预算，按来源隔离错误；

- Strictly validates Schema v2, paths, JSON, PNGs, animations, and resource count budgets, while isolating errors by source;

• 支持 append、replace、disable、definition priority 和稳定资源包优先级；

- Supports append, replace, disable, definition priority, and stable resource pack priority;

• 支持 screen/menu 类、标题 key/text、menu type、GUI resource、Mod namespace 与 all/any/not 匹配；

- Supports screen/menu classes, title keys/text, menu types, GUI resources, Mod namespaces, and all/any/not matchers;

• 支持 GUI 逻辑位置/尺寸、Slot 索引/范围/基础坐标/类选择、实际位移和渐变高亮；

- Supports GUI logical position/size, Slot indices/ranges/base coordinates/class selection, actual offsets, and gradient highlights;

• 支持整图、区域 UV、三种显式资源类型、三种锚点和三种渲染层；

- Supports full-image rendering, region UVs, three explicit resource types, three anchors, and three rendering layers;

• gui 锚点、破限纹理和 Slot 会跟随配方书展开/收起及窗口重新布局同步移动；

- gui anchors, overflow textures, and Slots move synchronously with recipe book expansion/collapse and window relayout;

• 支持 PNG Alpha、显式文本、语义标题/玩家背包标签规则及时间动画；

- Supports PNG Alpha, explicit text, semantic title/player inventory label rules, and time-based animations;

• Schema v3 与 v2 并存：不需要响应式能力的旧 v2 材质包无需迁移；

- Schema v3 and v2 coexist: existing v2 resource packs that do not require reactive capabilities do not need to migrate;

• Schema v3 提供稳定 Sprite ID、严格表达式引擎和每 tick Runtime Context；

- Schema v3 provides stable Sprite IDs, a strict expression engine, and a per-tick Runtime Context;

• 支持玩家、屏幕、GUI、鼠标与按键状态，以及 health/burning/screen 生命周期事件；

- Supports player, screen, GUI, mouse, and keyboard states, as well as health/burning/screen lifecycle events;

• 支持 visible、alpha、平移、缩放、旋转绑定和数值平滑；

- Supports visible, alpha, translation, scaling, rotation bindings, and value smoothing;

• 支持属性动画、linear / smoothstep 插值、行为条件与安全动作；

- Supports property animations, linear / smoothstep interpolation, behavior conditions, and safe actions;

• Schema v3.1 新增统一 elements、Group/Parent 场景树、局部坐标和父级变换/显隐/透明度继承；

- Schema v3.1 introduces a unified elements array, a Group/Parent scene tree, local coordinates, and inherited parent transforms/visibility/opacity;

• 支持 GUI/Screen 九点 Anchor、元素 Pivot，以及 layer → z → scene order 稳定绘制顺序；

- Supports nine-point GUI/Screen Anchors, element Pivots, and stable draw ordering based on layer → z → scene order;

• 支持 Definition-local Constants、按声明顺序求值的 Derived Values，以及 Binding 中的基础布局几何；

- Supports Definition-local Constants, declaration-order Derived Values, and self.* / parent.* self.* / parent.* basic layout geometry in Bindings;

• 属性动画支持显式 replace / add / multiply 合成，Group 动画可由整个子树继承；

- Property animations support explicit replace / add / multiply composition, while Group animations can be inherited by the entire subtree;

• Reactive Core 独立保持 Java 8 源兼容，平台层仍使用 Minecraft 26.2 所需的 Java 25；

- The Reactive Core remains source-compatible with Java 8, while the platform layer still uses Java 25 required by Minecraft 26.2;

• F3+T 采用不可变 generation 原子切换，成功后统一释放上一代引用；

- F3+T uses immutable generation-based atomic switching and releases references from the previous generation after a successful reload;

• 全部 GUI 绘制使用 GuiGraphicsExtractor 与 RenderPipelines，不直接调用 OpenGL/LWJGL。

- All GUI rendering uses GuiGraphicsExtractor and RenderPipelines without directly calling OpenGL/LWJGL.

下一步 Next Steps

• 更清晰的结构化诊断与离线 Validator；

- Clearer structured diagnostics and an offline Validator;

• 面向材质包作者的 Inspector 与属性管线视图；

- An Inspector and property pipeline view designed for resource pack authors;

• Layout Container、Clip/Scroll 与 Component 复用；

- Layout Containers, Clip/Scroll, and Component reuse;

• Semantic Slot，以及 Text/Slot 的响应式 target；

- Semantic Slots and reactive Text/Slot targets;

• HUD API 与 Widget；

- HUD API and Widgets;

• Texture State、width/height/color Binding 与更多安全事件/动作； - Texture State, width/height/color Bindings, and more safe events/actions;

• 可读取并导出正式 Schema JSON 的可视化编辑器。

- A visual editor capable of reading and exporting the official Schema JSON.

项目方向 Project Direction

RedFoxExpand 的核心设计哲学是：

让资源包负责表现，让 Mod 负责能力。

The core design philosophy of RedFoxExpand is: > Let resource packs handle presentation, and let the Mod handle capabilities.

资源包使用 Texture、Layout、Animation、Color、Visibility、Style 与 Theme 描述界面；

Mod 负责 State、Rendering、Events、Input、Compatibility、Security 与 Runtime。

目标不是简单支持更多 PNG，而是让材质包作者只使用 PNG、JSON、Animation、Expression 和 Components，也能制作动态背包、动态 HUD、RPG/PvP/科幻界面、角色面板、响应式 GUI 与第三方 Mod UI。

Resource packs describe interfaces using Texture, Layout, Animation, Color, Visibility, Style, and Theme; the Mod handles State, Rendering, Events, Input, Compatibility, Security, and Runtime. The goal is not simply to support more PNGs, but to allow resource pack authors to create dynamic inventories, dynamic HUDs, RPG/PvP/sci-fi interfaces, character panels, reactive GUIs, and third-party Mod UIs using only PNG, JSON, Animation, Expression, and Components.

Resource Pack API  ─┐
                     ├─> Expression Engine -> UI Definition -> HUD / GUI / Components
Runtime Context  ──┘                                       -> Layout Engine
                                                              -> Animation Engine
                                                              -> Render Pipeline -> Minecraft

项目将从“材质包辅助 Mod”继续发展为 Minecraft Resource Pack UI Framework，并最终形成可复用的Minecraft Resource Pack UI Runtime。 The project will continue evolving from a “resource pack enhancement Mod” into a Minecraft Resource Pack UI Framework, and eventually into a reusable Minecraft Resource Pack UI Runtime.

Schema v3.1 已让复杂界面从平铺 Sprite 进入 Scene Graph；下一阶段优先改善诊断、Inspector、布局与复用能力，再在同一核心上扩展 Semantic Slot、HUD 和 Widget。

Schema v3.1 has already moved complex interfaces from flat Sprites into a Scene Graph; the next stage will

prioritize diagnostics, Inspector tooling, layout, and component reuse, followed by Semantic Slots, HUD, and Widgets built on the same core.

安装 Installation

1. 安装 Minecraft 26.2、Fabric Loader 0.19.3 和 Fabric API 0.156.0+26.2；

1. Install Minecraft 26.2, Fabric Loader 0.19.3, and Fabric API 0.156.0+26.2;

1. 从 GitHub Releases 下载

2. Download from GitHub Releases；

1. 将 JAR 放入 Minecraft 实例的 mods/ 目录；

3. Place the JAR into the mods/ directory of your Minecraft instance;

1. 启动游戏并启用符合 Schema v2、v3 或 v3.1 的 RedFoxExpand 材质包。

4. Launch the game and enable a RedFoxExpand resource pack compatible with Schema v2, v3, or v3.1.

Mod 不要求服务端安装。建议在新增或修改配置后执行 F3+T。 The Mod does not need to be installed on the server. Running F3+T after adding or modifying configurations is recommended.

制作第一个 Kyeitk 材质包 Creating Your First Kyeitk Resource Pack

1. 建立目录 1. Create the Directory Structure

MyKyeitkPack/
├─ pack.mcmeta
└─ assets/
   └─ kyeitk/
      └─ redfoxexpand/
         ├─ index.json
         ├─ config/
         │  └─ inventory.json
         └─ textures/
            └─ gui/
               └─ inventory.png

Minecraft 26.2 的 pack.mcmeta 必须同时声明格式与范围： Minecraft 26.2 requires pack.mcmeta to declare both the format and range:

{
  "pack": {
    "pack_format": 88,
    "min_format": 88,
    "max_format": 88,
    "description": "My first RedFoxExpand GUI pack"
  }
}

2. 放置 GUI 图片 2. Add the GUI Image

将带 Alpha 通道的 PNG 放到： Place the PNG with an Alpha channel at:

assets/kyeitk/redfoxexpand/textures/gui/inventory.png

26.2 只接受小写原生 namespace。 26.2 only accepts native lowercase namespaces.

3. 写入配置

3. Write the Configuration

assets/kyeitk/redfoxexpand/index.json：

{
  "api_version": 2,
  "configs": ["redfoxexpand/config/inventory.json"]
}

assets/kyeitk/redfoxexpand/config/inventory.json：

{
  "api_version": 2,
  "definitions": [{
    "id": "example:inventory",
    "operation": "replace",
    "priority": 100,
    "match": {
      "exact_menu_class": "net.minecraft.world.inventory.InventoryMenu"
    },
    "sprites": [{
      "texture": {
        "type": "pack_resource",
        "location": "textures/gui/inventory.png"
      },
      "anchor": "gui",
      "x": 0,
      "y": 0,
      "width": 176,
      "height": 166,
      "layer": "background"
    }]
  }]
}

启用材质包并打开玩家背包即可查看。修改资源后按 F3+T，成功 reload 后新 generation 一次性生效。 Enable the resource pack and open the player inventory to view it. After modifying resources, press F3+T; once the reload succeeds, the new generation becomes active atomically.

Schema v3 响应式界面

Schema v3 Reactive Interfaces

需要根据玩家或界面状态动态改变 Sprite 时，将 manifest 与 config 的 api_version 都设为 3，并为每个Sprite 增加 Definition 内唯一的 id。下面的配置会在玩家着火时显示火焰，并让图标平滑跟随鼠标横坐标：

When a Sprite needs to change dynamically according to player or interface state, set api_version to 3 in both the manifest and config, and give each Sprite a Definition-unique id. The following configuration displays a flame when the player is burning and smoothly follows the mouse's horizontal coordinate:

{
  "api_version": 3,
  "definitions": [{
    "id": "example:reactive_inventory",
    "match": {"exact_menu_class":"net.minecraft.world.inventory.InventoryMenu"},
    "sprites": [{
      "id": "fire",
      "texture": {"type":"pack_resource","location":"textures/gui/fire.png"},
      "anchor": "gui", "x": 80, "y": 20, "width": 32, "height": 32
    }],
    "bindings": [
      {"target":"fire","property":"visible","value":"player.is_burning"},
      {"target":"fire","property":"translate_x","value":"mouse.gui_x - 80","smoothing_ms":120}
    ]
  }]
}

v3 表达式在 reload 时预编译并严格校验，不支持脚本、反射、文件、网络或任意函数调用。完整 Runtime Context、表达式语法、属性、事件、动画、行为、预算及迁移说明见项目GitHub

v3 expressions are precompiled and strictly validated during reload. Scripts, reflection, file access, network access, and arbitrary function calls are not supported. See the project GitHub for the complete Runtime Context, expression syntax, properties, events, animations, behaviors, budgets, and migration details.

Schema v3.1 场景图

Schema v3.1 Scene Graph

Schema v3.1 面向由多个图层组成的角色、面板和动态界面。将 manifest 与 config 的 api_version 都设为数值 3.1，使用统一 elements 数组，并通过 Group 组织可共同移动、缩放、旋转、显隐或改变透明度的子树：

Schema v3.1 is designed for characters, panels, and dynamic interfaces composed of multiple layers. Set api_version to the numeric value 3.1 in both the manifest and config, use a unified elements array, and use Groups to organize subtrees that can be moved, scaled, rotated, shown/hidden, or have their opacity changed together:

{
  "api_version": 3.1,
  "definitions": [{
    "id": "example:character",
    "match": {"menu_type":"minecraft:player"},
    "constants": {"turn_limit": 4},
    "values": {
      "head_turn": "clamp((mouse.x - screen.width / 2) * 0.01, -turn_limit, turn_limit)"
    },
    "elements": [
      {
        "id":"character_root", "type":"group",
        "anchor":"screen_bottom_center", "x":-80, "y":-160,
        "width":160, "height":160,
        "children":["body", "head_group"]
      },
      {
        "id":"body", "type":"sprite",
        "texture":{"type":"pack_resource","location":"textures/gui/body.png"},
        "width":160, "height":160, "layer":"foreground"
      },
      {
        "id":"head_group", "type":"group", "width":160, "height":160,
        "children":["head"]
      },
      {
        "id":"head", "type":"sprite",
        "texture":{"type":"pack_resource","location":"textures/gui/head.png"},
        "width":160, "height":160, "layer":"foreground"
      }
    ],
    "bindings": [{
      "target":"head_group", "property":"rotation_z",
      "value":"head_turn", "smoothing_ms":180
    }]
  }]
}

根 Element 可使用 GUI/Screen 九点 Anchor，子 Element 使用父级局部坐标；Pivot 决定旋转和缩放中心。Constants 消除重复数字，Derived Values 复用表达式，self.* / parent.* 为鼠标跟随等效果提供稳定基础几何。完整字段、默认值、场景继承、动画合成和 v3.0 迁移见项目GitHub

A root Element can use a nine-point GUI/Screen Anchor, while child Elements use parent-local coordinates; Pivot determines the center of rotation and scaling. Constants eliminate repeated numbers, Derived Values reuse expressions, and self.* / parent.* provide stable base geometry for effects such as mouse following. See the project GitHub for complete fields, defaults, scene inheritance, animation composition, and v3.0 migration details.

完整配置示例

Complete Configuration Example

下面的示例扩展玩家背包、移动槽位并添加前景文字： The following example expands the player inventory, moves Slots, and adds foreground text:

{
  "api_version": 2,
  "definitions": [{
    "id": "example:expanded_inventory",
    "operation": "replace",
    "priority": 100,
    "match": {"exact_menu_class": "net.minecraft.world.inventory.InventoryMenu"},
    "geometry": {
      "width_offset": 132,
      "height_offset": 14,
      "x_offset": 66,
      "y_offset": 7
    },
    "slot_modifiers": [{
      "slots": ["9-35"],
      "x_offset": 2,
      "highlight_color": "#80FFFFFF",
      "highlight_color_2": "#20306080"
    }],
    "sprites": [{
      "texture": {"type": "pack_resource", "location": "textures/gui/inventory.png"},
      "anchor": "gui",
      "x": -122,
      "y": -5,
      "width": 307.5,
      "height": 180,
      "layer": "underlay"
    }],
    "texts": [{
      "text": "RedFoxExpand",
      "x": 92,
      "y": 6,
      "color": "#FFFFFFFF",
      "shadow": true,
      "anchor": "gui",
      "layer": "foreground"
    }]
  }]
}

常用字段： Common fields:

• match：严格的单 operator matcher，也可用 all、any、not 组合；

- match: a strict single-operator matcher, which can also be combined with all, any, and not;

• geometry：x_offset、y_offset、width_offset、height_offset；

• texture.type：resource_location、gui_sprite 或 pack_resource；

- texture.type: resource_location, gui_sprite, or pack_resource;

• anchor：gui、screen_center 或 screen；

- anchor: gui, screen_center, or screen;

• layer：underlay、background 或 foreground；

- layer: underlay, background, or foreground;

• id / priority / operation：控制跨资源包定义合并。

- id / priority / operation: controls definition merging across resource packs.

字段、默认值、合并顺序及错误回退见项目GitHub。 See the project GitHub for fields, defaults, merge order, and error fallback behavior.

动画 GUI

Animated GUI

26.2 将动画直接写入 Sprite： In 26.2, animations are defined directly on Sprites:

{
  "texture": {"type":"pack_resource","location":"textures/gui/default.png"},
  "animation": {
    "frame_duration_ms": 100,
    "loop": true,
    "condition": "always",
    "missing_frame": "use_default",
    "frames": [
      {"texture":{"type":"pack_resource","location":"textures/gui/frame_0.png"}},
      {"texture":{"type":"pack_resource","location":"textures/gui/frame_1.png"},"duration_ms":160}
    ]
  },
  "width": 176,
  "height": 166,
  "anchor": "gui",
  "layer": "background"
}

当前支持逐帧时长、循环、always / never、默认图片和 use_default / skip / disable 缺帧策略。格式见项目GitHub。

Currently supports per-frame duration, looping, always / never, a default image, and the use_default / skip / disable missing-frame strategies. See the project GitHub for the format.

第三方 Mod GUI

Third-Party Mod GUIs

第三方 GUI 不再使用专用 compatibility 目录，可直接通过数据驱动 matcher 匹配： Third-party GUIs no longer require a dedicated compatibility directory and can be matched directly using data-driven matchers:

{
  "all": [
    {"assignable_screen_class": "example.mod.client.ExampleContainerScreen"},
    {"mod_namespace": "examplemod"}
  ]
}

完整类名不会回退为简单类名；确需简单类名时必须使用显式 *_simple_class operator。第三方 Screen 若完全重写标签提取或跳过原版背景流程，相应语义文本或 underlay 能力可能降级。

Full class names do not fall back to simple class names; when a simple class name is required, an explicit *_simple_class operator must be used. If a third-party Screen completely rewrites label extraction or skips the vanilla background rendering flow, the corresponding semantic text or underlay capabilities may be degraded.

当前限制

Current Limitations

• 当前仅处理 Minecraft 客户端的容器 GUI，HUD 与 Widget 尚未实现；

- Currently only handles container GUIs on the Minecraft client; HUD and Widgets are not yet implemented;

• 不扫描旧 assets/Kyeitk/，旧版配置必须迁移至原生小写 Schema v2；

- Does not scan the legacy assets/Kyeitk/; legacy configurations must be migrated to the native lowercase Schema v2;

• imageWidth/imageHeight 保持原版 final 值，扩展尺寸使用独立逻辑 geometry；

- imageWidth/imageHeight retain their vanilla final values; expanded dimensions use independent logical geometry;

• Sprite 纹理帧动画条件仍只有 always 和 never；动态条件请使用 Schema v3；

- Sprite texture frame animations still only support always and never conditions; use Schema v3 for dynamic conditions;

• Schema v3.1 Scene Graph 当前只作用于 Sprite/Group；Text 和 Slot 尚不能进入场景树或作为响应式 target；

- The Schema v3.1 Scene Graph currently applies only to Sprites/Groups; Text and Slots cannot yet enter the scene tree or act as reactive targets;

• 不支持 HUD、Widget、Semantic Slot、Layout Container、Component、Clip/Scroll 或 Inspector；

- HUD, Widgets, Semantic Slots, Layout Containers, Components, Clip/Scroll, and Inspector are not supported;

• 尚无 Texture State、width/height/color Binding、自定义变量/事件、Timer、User Function、循环/递归或every.mode=repeat；

- Texture State, width/height/color Bindings, custom variables/events, Timer, User Function, loops/recursion, and every.mode=repeat are not yet available;

• self.* / parent.* 提供静态基础布局几何，不读取本帧 Binding/Animation 后的最终矩阵；

- self.* / parent.* provide static base layout geometry and do not read the final matrix after the current frame's Binding/Animation evaluation;

• OpenGL/Vulkan、第三方 Screen 与不同 GUI 布局的表现可能因环境组合而异。

- Behavior involving OpenGL/Vulkan, third-party Screens, and different GUI layouts may vary depending on the combination of environments.

许可

License

当前仓库遵循 CC BY-NC-SA 4.0 协议；除非权利人另行授权，源代码默认保留所有权利。仓库不包含第三方材质包或受限制美术素材。

The current repository is licensed under CC BY-NC-SA 4.0; unless separately authorized by the rights holder, the source code remains all rights reserved by default. The repository does not contain third-party resource packs or restricted art assets.