GFBS 3D-CONSOLE Studio 1.0.1

GFBS 3D-CONSOLE Studio 是 LytharaLab 为 GFBS-Main / 3D-CONSOLE 制作的 Blockbench Desktop 可视化 Scene 编辑器。

它直接打开和保存：

data/<namespace>/gfbs_console/scenes/*.json

GFBS Scene JSON 始终是 source of truth；不会要求 .bbmodel 中间格式。

1.0.1 面向 Blockbench Desktop 5.2.2 和 GFBS-Main 当前的 3D-CONSOLE format_version 1。常用操作集中到右侧中文工作台，Scene JSON 继续直接作为项目文件。

1.0.1 修复 root/父节点拖动时子树留在原地的问题：移动仅修改所选最上层节点，子节点局部 Transform 保持不变；支持全局/局部轴、平面拖动、多选和撤销/重做。

1.0 工作台：从打开到验收

安装 dist/gfbs_console_studio.js 后，在 File → New → 新建 GFBS 控制台场景 创建场景，或使用 File → Import → Open GFBS 3D-CONSOLE Scene... 打开现有 JSON。右侧出现 GFBS 工作台；关闭后可通过 Tools → GFBS 工作台 / Workbench 找回。

进入 Console 场景后，场景树放在左侧，右侧留给可滚动工作台；原生 UV、纹理和单位不同的变换面板暂时隐藏。离开 Console 场景或卸载插件时恢复原有面板条件与场景树位置。

页签	可以完成的工作
节点	搜索 ID / 路径 / 类型；直接修改 ID、位置、XYZ 旋转、缩放、轴心、文字与模型资源；编辑交互框、材质、部件；多选对齐和等距分布
创建	一键添加全部 17 种内建节点；生成带属性、绑定、信号连接的入门控制台
逻辑	常驻查看场景属性、绑定、信号连接；直接添加、编辑、删除；编辑 Map 值
调试	三种视图；按下 / 松开 / 激活 / 滚动模拟；属性监视和临时覆盖；单步 Tick 或 20 Hz 计时器；最近 100 条信号日志
资源	设置项目根与 MC JAR、管理资源包优先级；按需扫描并搜索项目模型；浏览并打开项目场景
问题	格式、引用和资源问题列表；可定位的问题点击选择节点

建议先这样用

新建场景，点击 创建 → 生成入门控制台。
在画布或 Outliner 选择节点，直接在节点页改位置、文字和模型。位置与轴心使用 Minecraft 方块；16 Blockbench units = 1 方块。离开输入框即应用，可 Ctrl+Z 撤销。
资源 → 选择项目根 → 扫描项目。选择 GFBS-Main 根目录，可浏览 src/main/resources 下的场景和模型。项目模型可新建节点，也可替换所选模型。
在逻辑页检查绑定和信号；在调试页选择交互节点并激活，观察根属性和选中节点属性。
打开问题页检查，点击保存或 Ctrl+S 写回 GFBS Scene JSON。另存为 使用 GFBS Codec。

可靠性和兼容性

Blockbench 5.2 的插件作用域 requireNativeModule、显式 Buffer、SystemInfo 路径适配。读取项目/MC 资源需要 Blockbench 的文件访问许可；不申请进程、网络或外部程序权限。
Console 父节点补齐 openUp()，避免新版 Blockbench 选择子节点时报错；原生重命名入口也进入引用安全编辑。
属性、绑定、连接、Map、部件、材质、Indicator 映射与命中框编辑进入撤销记录。节点 ID 重命名时，绑定/信号/模型引用一并撤销和恢复。
添加、复制子树和入门模板的 Undo post snapshot 包含新节点，可重做。
没有选中节点时，新节点加入现有场景根节点，避免意外创建多个根。
导入前检查树结构、重复 ID、深度、节点数量和变换，失败时保留当前文档。
保留现有根/节点/连接中的扩展字段；编辑属性定义和材质时保留未识别的扩展键。
计时器对齐 ConsoleTimerNode.tick 的 interval / running / period / elapsed / elapsed 信号顺序。每次单步最多 200 Tick；信号传播继续受 256 次预算限制。
调试值、时钟、日志不写入 Scene；切换/关闭项目、撤销/重做及卸载插件会暂停计时器。运行中只重建状态发生变化的视觉节点。
多选对齐与分布要求相同父节点，使用局部坐标；不跨父空间推断坐标。
项目扫描由用户触发，跳过符号链接，限制深度 24、遍历 12000 项、结果 4000 项。MC JAR 和资源包仍使用已有资源解析器。

旧菜单与完整属性对话框继续可用，下面保留详细功能参考。

0.3 核心升级

所有节点都能从画布选中：每个 Console 节点拥有不可见的拾取代理；模型、文字会按实际内容自动贴合，Interaction 按 hit shape 贴合，纯逻辑节点也保留稳定点击范围。
父子 Transform 真正联动：移动、旋转或缩放父节点时，整个子树即时跟随，同时继续以局部 Transform 写回 Scene JSON。
Console 节点可真正收纳子节点：node_3d 等 Console 节点现在会被 Blockbench 识别为 Outliner 父节点，可直接把 model、text 等节点拖入；右键或 Structure 菜单另有 Move to Console Parent...，支持多选、循环检测和保持世界 Transform。
不会再由父节点吞掉子节点选择：父级代理只计算自己的直接视觉内容，不包围整棵子树。
清晰的选中反馈：Render / Authoring / Debug 三种视图中，当前节点都有轻量琥珀色选择框。
引用安全重命名：改 Node ID 时同步更新 Indicator、Animation、Binding、Connection、Preview Override 与资源诊断引用；支持 ID 内含 .。
引用安全复制子树：自动生成全局唯一 ID，重写内部引用，并复制相关 Binding / Connection / Preview Override。
Find / Select Node：通过完整 Outliner 路径与节点类型快速定位节点。
Scene Overview / Preflight：集中查看节点类型统计、逻辑图规模、资源缺失与保存前错误。
Starter Console Assembly：一键生成 Panel、Text、Button、Toggle、Knob、Slider、Indicator、Property、Binding 与 Connection 相互连通的示例骨架。
完整快捷创建：补齐 Knob、Lever、Slider、Indicator、Animation、Sound、Timer、Linear/Grid/Surface Layout。
Resource Roots 可管理：除了添加，还能删除、清空和调整优先级。
节点类型图标：Outliner 使用对应的 Model、Text、Sound、Control、Layout 等图标，复杂场景更易读。
Minecraft 1.20.1 字体一致预览：Text 不再使用浏览器 monospace；Studio 会读取 Minecraft font/default.json、位图字形与 include/unifont / unifont.zip，按游戏端相同的字符宽度、字距、ascent、2x oversample 与 9px 行高生成预览。中文不会再因系统字体回退而在进游戏后突变；legacy Unicode 资源包也仍可预览。

Text 字体资源与 Vanilla 模型资源共用同一套来源解析。一般使用 Auto-detect Minecraft 1.20.1 Assets 即可；也可以通过 Set Minecraft Client JAR... 指定客户端 JAR。字体位图异步完成解码后，文字平面会自动按真实像素宽度重建，无需重新打开场景。若资源中缺少 assets/minecraft/font/default.json，Resource Status 会明确标记该 Text 正在使用临时系统字体，而不会把近似结果冒充为 MC 预览。

Minecraft 1.20.1 的 unifont.zip 由 client JAR 内的字体定义引用，实际字节可能位于启动器的哈希资源库中。Studio 会把已经选中的 client JAR 作为安装根锚点并优先读取其资源；插件同时内置完整且字节一致的 1.20.1 默认字体资源组。Blockbench 若解析出“合法但只有 bitmap、没有 Unihex”的 minecraft:default，Studio 会强制把 1.20.1 原版 Unihex 追加为最终 Unicode 覆盖层；资源包 provider 保持更高优先级。若 Blockbench 提供的是残缺 Unihex，普通 provider 全部查找失败后还会直接查询内置原版码点，然后才允许进入 missing-glyph 分支。外部字体链无论在哪一环失真，原版支持的中文都不会再被画成方框。

Blockbench 自带的 Move to Group / 移动至分组 只面向原生 Group，不负责 GFBS Scene 节点。0.3.2 已从 Console 节点菜单移除这个误导入口，请使用拖放或 Move to Console Parent...。

Studio 让 Blockbench 真正承担 3D-CONSOLE Scene Visual Editor / Studio 的职责：真实模型预览、干净 Render View、交互调试、Preview Runtime、Binding/Indicator/Material 状态预览，以及结构化逻辑编辑。

运行要求

Blockbench Desktop 5.2.2+（1.0.0 的实际适配基线）
GFBS-Main 当前 3D-CONSOLE format_version: 1
推荐把 Scene 放在标准 Forge/Gradle 项目下：

<project>/src/main/resources/

安装

打开 Blockbench Desktop。
File → Plugins...。
选择 Load Plugin from File。
选择 dist/gfbs_console_studio.js。
安装后会出现 GFBS 3D-CONSOLE Scene 格式和 Tools → GFBS 3D-CONSOLE Studio 菜单。

打开 Scene

Visual Editor

三种 View Mode

Render

默认模式。

只显示真正有视觉意义的 Scene 内容：

Model
Text
Material / Indicator preview state
glTF animation preview

不会把所有 Node、Indicator、Sound、Interaction hitbox 全部画成蓝色 wireframe。

无法解析的模型只显示一个很小的洋红色 missing marker，而不是 1×1×1 大代理方块淹没场景。

Authoring

显示真实场景，同时只给当前选中节点显示编辑辅助：

origin
interaction hitbox
spatial helper
logic helper

适合摆放、对齐、改 hitbox。

Interaction Debug

显示真实场景，并打开所有交互/逻辑辅助信息，适合检查：

Button / Toggle / Knob / Lever / Slider hit shape
Sound range helper
logic/spatial node helper

菜单：

Tools
└─ GFBS 3D-CONSOLE Studio
   ├─ View Mode: Render
   ├─ View Mode: Authoring
   └─ View Mode: Interaction Debug

Model Preview

GFBS glTF

gfbs_main:gltf：

优先使用 Blockbench 当前 THREE.GLTFLoader
支持 glTF / GLB
保留 hierarchy / standard material
支持 named node / part alias 查找
支持 Scene Material Profile preview
支持 Indicator 状态驱动 profile
支持 Animation node 的 playing / speed Preview Runtime
Blockbench 无 GLTFLoader 时保留静态 core glTF fallback reader

项目资源：

source.location = gfbs_main:models/console/foo.gltf

解析为：

src/main/resources/assets/gfbs_main/models/console/foo.gltf

Vanilla / Minecraft JSON

gfbs_main:vanilla_json 不再只是 wireframe proxy。

0.2.0 内置 Minecraft Java model preview renderer，支持：

parent
block registry ID → blockstates/*.json model fallback
texture variable inheritance，例如 #all
namespace inheritance
elements
from / to
six faces
per-face texture
UV
face texture rotation
element rotation
element rotation origin
rescale
shade: false
transparent texture
item/generated / layer0 的平面预览

例如：

{
  "source": {
    "adapter": "gfbs_main:vanilla_json",
    "location": "minecraft:polished_deepslate"
  }
}

插件会尝试解析：

assets/minecraft/models/block/polished_deepslate.json

并递归读取它的 parent 和 textures。

Minecraft 原版资源从哪里来？

插件按顺序搜索：

当前 Forge project 的 src/main/resources
手工添加的 Resource Pack / resource root
手工指定的 Minecraft assets directory 或 client JAR
自动探测 Minecraft 1.20.1 client JAR

Windows 默认会尝试：

%APPDATA%\.minecraft\versions\1.20.1\1.20.1.jar

以及 ForgeGradle Minecraft cache。

插件内置轻量 ZIP/JAR resource reader，因此不需要先解压 Minecraft JAR。

Preview Runtime

0.2.0 新增编辑器内 Preview Runtime。

它会建立当前 Scene 的 property state：

Scene root properties
Node authored properties
built-in properties
Preview overrides

然后执行当前 Binding：

Direct
Map
Range
Format

所以例如：

power_toggle.state
        ↓ binding
$root.power
        ↓ indicator
PowerLamp material profile

可以直接在 Blockbench 中预览。

菜单：

Preview Runtime State...

可以给任意已知 property 设置仅编辑器使用的 override，例如：

$root.power = true
$root.mode = AUTO
output_knob.value = 0.75
scanner_animation.playing = true

这些 Preview override 不会写进 Scene JSON。

Show Resolved Preview State 可以查看经过 Binding 后的最终属性值。

Material Profile Preview

Model 的 material_profiles 会作用到真实 linked preview，并按当前 GFBS adapter 能力区分：

GFBS glTF adapter：

PBR
UNLIT
NEON（Blockbench 近似预览）
color
alpha
emissive color
emissive strength
neon strength
fullbright
visible

vanilla_json adapter 当前按 GFBS-Main runtime 对齐，只预览实际会生效的：

RGB tint
fullbright
visible

不会在 Blockbench 中给 vanilla JSON 虚构 runtime 尚未实现的 Neon/emissive/alpha 行为。

Indicator 会根据：

source property
→ mapping key
→ states
→ model::partAlias
→ material profile

实时决定当前 preview profile。

最终 Minecraft shader / GFBS-RP / GFBS-glTF 的光照、Bloom、Neon 结果仍以 Minecraft dev client 为准；Blockbench 预览用于 Scene authoring，不声称逐像素复刻游戏渲染器。

Interaction Simulation

选中：

interaction
button
toggle
knob
lever
slider

然后使用：

Simulate ACTIVATE
Simulate Interaction...

支持模拟：

PRESS
RELEASE
ACTIVATE
SCROLL
DRAG_START
DRAG
DRAG_END

行为按照当前 GFBS ConsoleInteractionNode 语义实现：

Toggle / Lever 的 ACTIVATE 切换 state
Lever 同步 min/max value
Knob / Slider / Lever 的 SCROLL / DRAG 更新 value
step / min / max sanitize
发射对应 signal

随后 Studio 会执行 Scene connection：

set
toggle
emit

host 和第三方 custom action 不会在 Blockbench 真执行，而会记录到 simulation log，因为真实 host action 属于 Minecraft server/runtime。

快速添加

通用 “Add Node” 默认选择 gfbs_main:model，同时提供按用途组织的快捷创建项。

菜单提供：

Add Minecraft / Vanilla Model...
Add GFBS glTF Model...
Add Text...
Add Button...
Add Toggle...
Add Knob...
Add Lever...
Add Slider...
Add Indicator...
Add Animation Driver...
Add Sound Node...
Add Timer...
Add Linear Layout...
Add Grid Layout...
Add Surface Layout...
Add Empty Node3D...
Add GFBS Console Node...

Create Starter Console Assembly 会一次生成一套已连通的控制台示例，可直接用 Preview Runtime 和 Interaction Simulation 检查 Toggle、Knob、Indicator、Text、Binding 与 Connection。

例如创建一块石头：

Add Minecraft / Vanilla Model...
Node ID: test_block
Resource: minecraft:stone

即可获得真实 Minecraft JSON 模型预览；如果找不到原版 assets，再配置 Minecraft JAR。

Scene / Node Authoring

支持当前全部内建节点：

node
node_3d
model
text
indicator
animation
sound
timer
linear_layout
grid_layout
surface_layout
interaction
button
toggle
knob
lever
slider

并支持第三方 ResourceLocation node type，以及 unknown JSON 字段 round-trip 保留。

支持：

parent / child Scene Tree
position / rotation / scale / pivot
GFBS XYZ Euler order
layout preview offset
引用安全的 node rename / subtree duplication
subtree JSON 一键复制到剪贴板
reparent（Blockbench Outliner）
Find / Select Node 路径导航

Properties / Logic

Properties

支持：

boolean
integer
long
double
string
color
vec3
resource

以及：

default
sync
save
interpolate
built-in property type conflict validation

Bindings

结构化编辑：

source / target property address
Direct
Map
Range
Format

Connections / Actions

结构化编辑：

signal source
set
toggle
emit
host
custom ResourceLocation action
typed literal value

Model Tools

Model Part Aliases
glTF node name scan
Material Profiles

Indicator Tools

source property picker
model::partAlias picker
state → profile mapping

Interaction Tools

box / aabb / obb
sphere
cylinder
plane / plane_rect
Fit Interaction Hitbox

Validation

保存前自动校验当前 GFBS format_version: 1 的主要约束：

max 4096 nodes
max depth 64
node ID 格式 / 全局唯一
ResourceLocation 字符规则
transform finite / non-zero scale
property definitions / built-in type compatibility
model source / part / material profile
indicator target/profile
animation target
hit shape / control range
sound range/speed
timer/layout
binding address/map/range/format
connection signal source
set/toggle/emit/host 参数

手工执行：

Tools → GFBS 3D-CONSOLE Studio → Validate Scene

Scene Overview / Preflight 还会把节点类型数量、Binding / Connection 数量、Preview Override、资源缺失及前 30 项校验结果合并显示，适合发布前快速扫一遍。

典型工作流

Blender / Minecraft model resources
             ↓
GFBS-Main Forge project
             ↓
Blockbench + GFBS 3D-CONSOLE Studio
             ↓
Open data/.../gfbs_console/scenes/*.json
             ↓
Render View 检查真实视觉
Authoring View 摆放 / 对齐
Interaction Debug 检查 hitbox
Preview Runtime 调状态 / 跑 Binding / Indicator
Simulate Interaction 测局部 Scene logic
             ↓
Ctrl+S
             ↓
Minecraft /reload
             ↓
GFBS-RP / GFBS-glTF / Minecraft runtime 最终验证

测试

npm ci
npm run build
npm test

src/workbench.js 在构建时嵌入主插件闭包，最终安装仍只需一个 dist/gfbs_console_studio.js。npm run check 也检查分发文件是否与源代码一致。

回归测试使用独立资源夹具，设置 GFBS_CONSOLE_STUDIO_AUTO_ASSETS=0 避免读取测试机器上意外存在的 Minecraft 安装；生产环境默认自动探测。

真实应用验收脚本：在隔离配置下启动 Blockbench 5.2.2，指定 --remote-debugging-port=19422，然后运行 node test/blockbench-runner.js test/blockbench-scenario.js。可用 GFBS_MAIN_ROOT 指定 GFBS-Main 根目录。脚本只读两个真实场景，并校验源文件 SHA-256 未变化；不会保存到 GFBS-Main。

真实应用脚本覆盖实际 Vue 面板、Outliner 选择、单位换算、引用重命名、Blockbench Undo/Redo、添加节点重做、计时器、信号、预览不入库、异常导入保护、项目资源扫描。它不替代 Minecraft 客户端的渲染和宿主业务验收。

1.0.1 移动专项回归：使用 --userData <独立目录>/validation-1.0.1-profile --remote-debugging-port=19423 启动 Blockbench，设置 GFBS_BLOCKBENCH_CDP_PORT=19423 后运行 node test/blockbench-runner.js test/blockbench-drag-scenario.js。该脚本仅用于独立测试实例，会创建夹具项目并重载插件；通过应用的 TransformerModule 分发及 Canvas 鼠标事件验证移动、局部数据、导出、取消和 Undo/Redo。专项测试禁用可选原生模块，不读取项目资源，也不修改插件权限。

当前自动测试覆盖：

JS syntax check
Scene parse → compile round-trip
unknown/known data preservation
validation negative cases
Preview Binding / Format evaluation
Preview override propagation
interaction ACTIVATE simulation
host action simulation logging
Vanilla model parent/texture inheritance
Forge workspace resource resolution
Minecraft JAR/ZIP entry reader
从 JAR 继承 Vanilla model geometry
Minecraft font reference provider 展开
bitmap / Unihex / legacy Unicode 字形宽度与 advance 计算
由深层 client JAR 反向解析便携启动器 asset store
完整内置默认字体 provider 链、三张 PNG 与 Unihex 档案的完整性及无 MC 安装回退
Headless Canvas 实际渲染“中文”及中英混合控制台标题，并校验宽度与非空字形像素
模拟 Blockbench 返回“合法但仅 bitmap”的 minecraft:default，验证强制 Unihex 补全后仍实际渲染中文
模拟“存在但不含中文”的残缺 Unihex provider，验证 canonical 码点直查阻断 missing-glyph 分支

预览边界

Studio 已经是视觉编辑器，但 Blockbench 仍不是 Minecraft client：

Forge BakedModel 的所有 loader/mod extension 不可能全部在 Blockbench 原生执行；Studio 实现的是标准 Minecraft Java model JSON renderer，并保留 ResourceLocation/Scene 数据。
GFBS-RP、Oculus/Embeddium、Minecraft light engine、GFBS-glTF 自定义 shader 的最终像素结果必须以 dev client 为准。
GFBS-Auralis 声音数据可以编辑，但 Studio 不启动真实 Auralis source/runtime。
host action 不在 Studio 执行真实机器逻辑。

这些边界不会把默认场景退化回 wireframe proxy；它们只决定“最终游戏渲染/服务器逻辑”仍需 Minecraft 验收。

Name		Name	Last commit message	Last commit date
dist		dist
scripts		scripts
src		src
test		test
third_party/unifont		third_party/unifont
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
VALIDATION.md		VALIDATION.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation