Skip to content

About

Galgame scenario editor prototype for FVP/hcb projects

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

hcb-ir-editor

Galgame 剧情编辑器雏形,FVP / hcb 项目与 Simple .hcb Editor 的 DSL 编辑界面。

两个工作区:写作(章节、原语块栈、参数)与资源(真实 .bin 归档浏览)。

仍是原型:写作区的块就是 Simple .hcb Editor 里的脚本原语,但还没有编译回 .hcb 的能力。项目内容只来自 .hcbproj 文件或导入的 DSL 脚本,资源全部来自扫描游戏目录里的 .bin,界面里不带示例数据。

运行

npm install
npm start
# 资源工作区左上角「扫描游戏目录」,选到放 .bin 的那一层
npm run test:dsl # DSL 解析与编码的静态测试,不开窗口
npm run test:mapping # 映射表解析与查询的静态测试
GAME_DIR=/path/to/game node tools/dump-mapping-inputs.cjs  # 扫描归档,准备生成数据
python tools/build-mapping.py # 重新生成 mappings/sakura.toml(需先有 Lua IR 与扫描数据)

目录

src/app/core.js        基础工具 / 常量
src/app/types.js       原语定义 / 色板
src/app/model.js       块视图 / 舞台 / 接线
src/app/project.js     项目文件
src/app/import-export.js DSL 导入 / 导出
src/app/state.js       全局状态 / 单选多选 / 下拉与菜单
src/app/history.js     撤销 / 重做
src/app/multi-inspector.js 多选参数栏
src/app/focus.js      聚焦模式
src/app/chapters.js    章节栏
src/app/stack.js       主栏 / 场景 / 拖拽
src/app/palette.js     插入面板 / 默认参数
src/app/inspector.js   右栏 / 单块字段 / 立绘选择器
src/app/menubar.js     菜单栏 / 快捷键
src/app/boot.js        启动
src/dsl.js             DSL 解析与编码解码
src/wiring.js          资源接线:映射表 → 文件
src/mapping.js         映射表:TOML 归一化与查询
docs/resource-wiring.md 接线模型、断线规则、背景编号
docs/code-structure.md 代码拆分、加载顺序、下一步计划
mappings/sample.toml   映射表最小示例(手工)
mappings/sakura.toml   从 Sakura.hcb 生成的完整表(角色 / 立绘 / 背景 / CG / BGM / 音效)
tools/build-mapping.py 从 hcb 的 Lua IR 生成立绘/角色/背景映射
tools/dump-mapping-inputs.cjs 扫描归档,准备生成用的条目/格数
src/resource.js        资源工作区(下一步拆分候选)
src/resource-store.js  扫描结果,两个工作区共用
src/styles/tokens.css  颜色/间距变量
src/styles/base.css    基础与外壳
src/styles/write.css   写作区左栏/主栏
src/styles/inspector.css 右栏/字段/立绘
src/styles/overlays.css 下拉/弹层/窄屏
src/styles/resource.css 资源工作区
src/styles/dialogs.css 起始页/导入/接线
electron/scan.js       读 .bin 名称表、解 hzc1、按范围取音频(主进程)
electron/main.js       窗口 + 扫描/缩略图/音频/映射表的 IPC 通道
electron/gbk.js        导出 DSL 用的 GBK 编码器
tools/capture.cjs      离屏截图与冒烟测试
tools/test-dsl.cjs     DSL 解析、GBK 编码的静态测试
tools/test-mapping.cjs 映射表的静态测试
tests/fixture.txt      覆盖全部原语的测试脚本

项目文件

文件 → 保存(Ctrl+S)写单个 .hcbproj(UTF-8 JSON),打开(Ctrl+O)读回;写盘先写 .tmp 再改名,旧文件留一份 .bak。启动时自动打开上次的项目,找不到就回到空状态;新建项目(Ctrl+N)是 0 章的空项目,不预置任何章节、场景或块。

{
  "format": "hcb-ir/project",
  "version": 1,
  "game": { "root": "/path/to/game" },
  "story": { "chapters": [] },
  "bindings": [],
  "ui": { "workspace": "write", "chapterId": "ch1", "collapsedScenes": {} }
}
  • game.root 只记路径,不存归档元数据;打开时目录不在,底部浮层提示并让你重新选,选完就地重扫。
  • ui 存工作区、当前章节、折叠的场景;不存光标。
  • 标题栏「未保存 / 已保存」跟脏标记走,块参数、章节场景增删、拖动排序、折叠状态都会置脏。
  • 版本比编辑器新会拒绝打开;块参数始终原样保存,解析不到资源也不改写它。
  • 绑定表随项目走;打开旧项目时按文件里的绑定重建,不再有内置的示例绑定。

编辑 / 多选 / 撤销

  • 撤销 / 重做:Ctrl+Z / Ctrl+Shift+Z(Ctrl+Y 也可以);菜单「编辑」里同样有,栈上限 100 步。覆盖剧本内容(块参数、插入/删除/复制、拖拽、章节/场景增删改),不覆盖映射表、绑定表和折叠这种 UI 状态;新建/打开项目会清空历史。
  • 选择:单击单选;Ctrl/Cmd+单击切换一块;Shift+单击按当前章节的块顺序选一段;Ctrl+Shift+单击把一段并进已有选择;Ctrl+A 全选当前章节;Esc 清空。
  • 多选参数栏:选中的块类型不同时只显示「选中了不同类型块」;类型相同时显示该类型的字段。值一致就显示单一值,不一致显示「多个值」;改一次会批量写回所有选中块(文本、数字、开关、下拉、立绘、向量等)。选项列表这类数组字段在多选时只显示汇总,不批量编辑。
  • 多选右键菜单:在多选里右键已选中的块,菜单会显示「复制 N 个块」/「删除 N 个块」,复制或删除整批;右键未选中的块会先切回单选。插入仍以右键块为锚点。
  • 聚焦模式:视图 → 聚焦模式… 里多选要保留的块类型,其余块会被压成一条淡灰细条;连续的非聚焦块合成一条,灰条不响应右键。聚焦时选择、Ctrl+A、方向键都只在聚焦类型里走;聚焦块仍可拖动排序,也可以拖到灰条上移到整段前后。显示全部块 恢复全部,新建/打开项目会清除聚焦。

导入 DSL

文件 → 导入 DSL…(Ctrl+I)读入一份 Simple .hcb Editor 的脚本文本,选编码、选导入目标,确认后直接变成可编辑的原语块。

  • 编码:自动(逐行判断,UTF-8 失败的行按 GBK 解,能处理一份文件里混用两种编码的情况)、UTF-8、GBK / GB18030、Shift-JIS、UTF-16 LE。显式编码用严格解码,字节不合法就报错,不会塞一堆替换字符。改编码会重新解码同一份文件,不用重新选文件。
  • 目标:新文件(替换当前项目,标题取脚本文件名)、章节(追加到所选章末尾)、小节(追加到所选节末尾)。
  • 拆分:勾选「按 :: 标签拆成小节」时,每个 ::label 起一个新小节,标题就是标签名;不勾选则整份脚本进一个小节。导入到小节时固定不拆。
  • 不认识的行:[test,…] 这类编辑器没建模的指令,以及没有闭合括号的行,会变成「自定义指令」块原样保留,DSL 行一字不改。
  • 认不全的参数:[dia,(心声),nil,1] 这种尾部多出来的参数留在块尾,编辑器不解释它们,但保存、再次打开时不会丢。
  • 脚本里的 bgload / cgload 会顺手登记成绑定(校门 → [bg,500]),导入后绑定表就有内容;背景块也直接显示 bgload 给的名字。

导出 DSL

文件 → 导出 DSL…(Ctrl+E)或标题栏「导出」,把当前项目按章节 → 场景 → 块的顺序摊平成一份 DSL,用 GBK 写盘(Simple .hcb Editor 用 encoding='gbk' 读脚本)。导出的文件可以直接作为它的输入,也能被本编辑器重新导入:冒烟里验证过导出的 51 个块重新解析仍是 51 个块。

  • 章节和小节只影响空行分隔;DSL 本身没有章节概念,多章项目会按顺序连在一起。
  • 导出前检查 GBK 不支持的字符(例如 emoji),有就报出来,不静默替换。
  • 导出走原子写,失败给浮层提示。

写作工作区

块 = 原语,名字就是脚本里的命令字。39 个原语按 8 组,另加一个「扩展」组里的自定义指令,一起放进插入面板(流程、台词、画面、立绘、声音、演出、变量、备注、扩展),面板可搜 bg、dia、bs_move、custom 这类命令字。

每块右侧显示它展开后的 DSL 行,右栏顶部显示完整调用(选项这种多行原语就展开成 [sel,start,…] / [sel,op,…] / [sel,end])。改参数,这一行立刻跟着变。

参数顺序与 hcb_build.py 里 line_to_hcb 的分派一致:

原语 DSL 形态
bg [bg,67,2] 背景编号 + 可选差分(1=底图,2/3=变体)
cgload / cg [cgload,KURO_e011a1]、[cg,KURO_e011a1,0,0,2000,900](2000 = 1×)
bs [bs,3,1,1,17,-1,l,1000,-200,100,1] 角色 姿势 服装 表情 构图 站位 z x y 图层
bs_fade / bs_move / bs_color / bs_ani / bsfade 退场、移动、着色、小动作、清除全部
cha / dia / msg [cha,真白/???,5000010]、[dia,…]、[msg,normal]
sel start / 若干 op / end 三段落
bgm / bgmstop / se 序号;se 另带 loop / end 与音量、时长
wait / shake / motion / v3d / snow / fog / endback 演出类,参数原样对应
global_set / global_eq 全局变量读写;global_eq 不等时跳标签
start / end / ::label / jump / ssel / achieve / chaload 结构类;chaload 先登记角色名才能用 cha

dia 不重复渲染 DSL 行(它的一句话就是正文),但右栏仍然给出完整调用。说话人取自同一场景里最近的 cha 块——和脚本里 cha 设定人名、dia 显示台词的先后关系一致。

标签在界面里只写名字(loop),:: 只在拼成调用时才出现(::loop);跳转、选项目标同样只填名字。

参数面板按「一行一个参数」排:标签在左、控件在右,x y z、RGB、姿势 服装 表情 这类同组数值压成一行并排输入。互相排斥的字段会自己收起来——cg 打开「沿用当前设定」后只剩时长,se 选「单次」时不显示音量和时长。10 个入参的 bs 因此只有 6 行。

自定义指令

扩展组里的「自定义指令」是底层逃生通道:块里只存一整行 DSL 原文,编辑器不解释命令和参数,保存、再次打开都原样写回。导入时认不出的行([test,…]、没闭合括号的行)也进这里。

  • 从插入面板选「自定义指令」,在右栏「指令」里填 [命令,参数…]。
  • 行不是 [ … ] 形式时,块上会标警告,但仍然原样保存。
  • 已知原语仍建议用对应的块,参数面板和舞台预览都更好用;自定义指令是给还没建模的命令留的口子。

资源接线

块参数是事实,文件是投影:项目里只存 DSL 参数,扫描结果、文件路径、偏移都是每次打开重新解析的。解析不到就保留参数、在右栏「接线」里标断线,不会自动改写。背景编号从映射表的 bg.file(或自定义 bgload 的文件名)解析,不再用 BG%03d 约定。完整规则、断线处理和下一步见 docs/resource-wiring.md。

映射表

所有资源类型都从映射表走:character / sprite / bg / cg / voice / bgm / se。DSL 里的编号只查表,不再按 cha_list 顺序、归档出现顺序、BG%03d 或三位补零去猜。

资源工作区 → 映射表 → 导入 TOML…;映射表会存进项目文件,换机器也还在。

  • mappings/sample.toml 是最小示例,解释字段;
  • mappings/sakura.toml 是从 Sakura.hcb 生成的完整表:24 个角色、99 个立绘组合、62 个背景(54 条差分)、238 个 CG、70 个 BGM、304 个音效,共 797 条。角色编号来自 hcb f_00058B8C 的 a1,姿势/服装来自 a2/a3;cloth 从 0 开始,0 是制服。
  • 背景差分按 hcb 的 a7 还原:diff=1 是底图,diff=2/3 选变体;函数里 a9/a10=100 的时段/天气分支需要额外参数,DSL 的 diff 不覆盖,没有并入。
  • 映射表的 TOML 路径会写进项目文件;映射表视图显示路径,重开项目后路径还在,可以用「重新载入」从原文件刷新。映射表内容本身也内嵌在项目里,文件被移走时仍能打开项目。
  • 没有映射表时,bg 编号、bs 的 cha/pose/cloth/face、chaPick 的 cha 退回数字输入,cha/chaload 的角色名退回文本输入;不再用推断的名字和立绘选择器。导入映射表后恢复选择器。

以前按 cha_list 和归档顺序推断时,[bs,14,1,0,12] 会被当成大雅;hcb 里 14 实际是 CHR_ハル2(春2),完整表已经纠正。生成流程:hcb_to_ir.py → tools/dump-mapping-inputs.cjs → python tools/build-mapping.py。

  • character:no(DSL 角色编号)、name、aliases;
  • sprite:cha / pose / cloth 三个数字,body / sheet 指向 graph_bs.bin 条目,faces 是表情格数,pose_name / cloth_name 是选择器里的显示名;
  • bg:no / name / file,可选 [[bg.variant]] 把 [bg,67,2] 的差分接到另一个条目;
  • cg:name 是 DSL 里的名字,label 是显示名,file 是实际条目;
  • voice:no / name / file;本表暂时 0 条。DSL 的 voice 是 hcb 语音表里的序号,不是 voice.bin 的 8 位文件号,没有基表就只能留空,agent 可以按这份 schema 补;
  • bgm / se:no / name / file,完整表把 70 / 304 条全部列了,file 是归档里的 001 这种条目名。

解析链固定为:映射表 → 剧本里的 bgload / cgload 声明(只用于自定义资源)→ 没有。扫描只负责把条目名变成偏移、缩略图、表情格数,不参与编号猜测。

舞台示意

右栏顶部跟着选中的块走:从本章开头把它之前的原语按顺序跑一遍,画出这一块执行时的画面构成——背景(接线到就显示真图,没接到就按名字里的情境给底色)、立绘(真图,按站位摆)、CG、对话框(说话人、台词、middle 居中、boxout 隐藏)、bgm 与 se。背景、立绘、BGM 跨场景留着,和脚本里的实际行为一致。改站位、切背景、换 CG,示意图立刻跟着动。

立绘选择器

bs 的「立绘」字段点开是四块:角色、姿势、衣装、表情表。姿势(基、喜、悲、幼少基…)和衣装一起决定身体图与表情表——换姿势,表情表的格数和内容都会变(千和 喜 是 50 格、基 是 48 格);当前姿势没有图的衣装会置灰。最右边是选中组合的全身预览和 CHR_千和_基_制服 这样的文件名。点「使用」就把 cha / pose / cloth / face 写进块里,界面上不出现可编辑的编号,编号只留在块右侧的 DSL 行里。

只引用角色、不需要换衣装的原语(bs_move、bs_fade、bs_color、bs_ani)用带小图的下拉选角色,同样不填编号。

数据来源:只读映射表的 sprite 行;cha、pose、cloth 的编号、角色名、显示名、body/sheet 都来自表。扫描只提供 graph_bs.bin 条目的偏移、尺寸和表情格数。没有映射表时立绘字段直接显示四个数字输入,没有选择器。

以前按 cha_list 顺序对角色、按归档里的出现顺序对 cloth 的推断已经删掉;[bs,14,1,0,12] 现在由表解析成 CHR_ハル2_基_制服,不会再落到大雅。

背景、角色、CG 的下拉也只从映射表(加上剧本里的 bgload / chaload / cgload 声明)取,不再读 hcb_build.py 的领域表或扫描文件名去猜。

真实归档格式

FVP 的 .bin 是平面名称表:u32 条目数、u32 名称区大小、逐条 {u32 名称偏移, u32 文件偏移, u32 大小},随后是 NUL 分隔的名称区。名称没有目录,全部平铺。

图像条目是 hzc1,44 字节头:

68 7a 63 31   'hzc1'
u32           解压后字节数
u32 32
4e 56 53 47   'NVSG'
u8 0, u8 1, u8 类型, u8 0
u16 宽, u16 高, u16 ?, u16 ?
… 补齐到 44 字节
zlib 流

图像条目的类型和像素格式:

type 每像素字节 通道 用在哪
0 3 BGR 背景 375、事件图 579、SD 立绘 57、补丁里一部分
1 4 BGRA 立绘 297、界面部件
2 4 BGRA,逐格存放 脸部表(6 列,先拼回整图再切)
3 / 4 1 未解 graph.bin 里 67 条

类型 0 和 1 的 宽 × 高 × 每像素字节 都正好等于解压后字节数;类型 2 是 宽 × 高 × 4 × 格子数。音频是 OggS 或 RIFF,按条目范围取出来就能直接播。

抽样结果:

归档 条目 大小 内容形态
graph_bs 594 761 MB 立绘,`CHR_角色_情绪_服装[_表情][L
graph_bg 375 671 MB 背景,BG001_000 加 b 变体与时间档
graph_vis 579 1916 MB 事件立绘,角色_e011a1 按差分编号
graph_vish 380 1065 MB 事件立绘差分,角色_h01a0 序列
graph 1146 338 MB 界面部件与数字命名素材
voice 14498 1020 MB 纯数字 ID,前两位是分组
bgm / se / se_env / se_sys 70 / 304 / 79 / 13 939 / 101 / 94 / 3 MB 数字序号

资源工作区

左栏顶部是「来源」:没扫描时这里只有扫描入口,点「扫描游戏目录」选到放 .bin 的那一层,主进程会把目录里所有 .bin 的名称表读出来,标题、条目数、大小、偏移、hzc1 的宽高与类型都来自真实文件。扫描后图片条目点开就是解出来的真图。

下面两个入口:绑定表、归档。

归档是底层:扫描到的每个 .bin,中栏列出名称、压缩大小、解压后、偏移,顶部按角色、背景 ID、语音前缀分组,每页 100 条,可前后翻页或直接填页码跳转(语音 14498 条共 145 页)。右栏预览只有两页:预览与概览;立绘是图层栈(身体、表情、L、U 可点切文件),背景与事件图是真图,音频可以直接播放(按条目范围取出,做成 Blob 播放,显示时长与进度)。

映射表是资源层的唯一事实:所有资源类型都在这里(见上一节)。绑定表是项目层:一行是 名字 → 调用 → 文件,例如导入 [bgload,500,BG500,校门] 后得到 校门 / [bg,500] / 有就解析、没有就标缺失。调用一律先查映射表:bg / cg / bs / se / bgm 都不再补 BG%03d 或三位零;只有 bgload / cgload 这种剧本里显式写了文件名的自定义资源才在表缺行时兜底。没有绑定时表格给出空状态,不再有内置的示例行。右栏概览列出名称、类型、调用、文件、偏移、备注、状态;「链」是映射表 → 调用 → 条目 → 位置,命中标绿、缺失标红。

绑定随项目文件保存;bgload / cgload 在导入时自动登记,写作区以后可以显示这些名字,DSL 里仍旧写编号。

已知限制

  • 扫描结果只存在内存里,重启要再扫一次(项目里只记了游戏目录)
  • 接线只按映射表走 bg / cg / bs / se / bgm;voice 的 schema 已留,但表里还没有行。背景差分通过 [[bg.variant]] 接,完整表已收 a7 的默认分支;a9/a10=100 的时段/天气分支没并入
  • graph.bin 里 67 条 1 字节/像素的图像(type 3/4)还没解,预览显示「这种格式还没解」
  • 断线后还没有「重新链接」按钮,只能通过原有字段重新选;绑定表仍只读;映射表只能整份导入,不能在界面里逐条改
  • 衣装、姿势的编号现在只来自映射表;face 仍是表情表格子序号,PartsSelect 的 a4 还没映射
  • 写作区的原语还不能编译回 .hcb;ssel、achieve、movie 只记录参数
  • 导入只做语法层,不校验跳转标签是否存在、资源编号是否有效;这些在块的警告标记里提示
  • 立绘按需解码缩略图,首次打开选择器会慢一拍
  • 完整表的 24 个角色里,只有 16 个在 graph_bs.bin 有图;另外查过 graph_sd.bin(57 条,全是 SD_e… 事件 SD 图)、graph.bin(1146 条 UI 图)和 patch.bin(71 条),没有 CHR_/サブ 条目,所以 サブ 系 8 个槽位在这份游戏资源里就是没有立绘
  • 背景 84 / 1010 在 graph_bg.bin 没有条目;34 / 102 没有 _000,表里取了第一个变体
  • 映射表的 faces 是表情表格数,不是 hcb 的 a4 PartsSelect 编号。a4 是 PartsSelect 的条目号(例如 [bs,14,1,0,12] 的 12),一张 2 格的表情表装不下;选择器只在用户真的点了脸时才改写 face,没点就保留原值,并在标题旁标「原值 12 未映射」
  • voice 的 [[voice]] 段已经在 schema 里,但完整表暂时是 0 条:DSL 的 voice 是 hcb 语音表里的序号,不是 voice.bin 的 8 位文件号,需要先从 hcb 基表推出来,或者由 agent 手工补。BGM / SE 已经全量列进完整表(70 / 304),file 是归档条目名。

About

Galgame scenario editor prototype for FVP/hcb projects

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages