Grasscutter Handbook 数据生成完全指南使用 -dump 参数导出 GM 手册数据集【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter本篇技术指南面向 Grasscutter 服务端搭建者与 HandbookGM 手册维护者完整讲解如何利用 Grasscutter 内置的 Dumpers 工具通过一条-dumpcontent,language启动参数从游戏资源中生成 Handbook 前端所需的全部数据文件命令、物品、角色、任务、实体、区域、场景等。读完本文你将掌握每类数据的生成命令、前置条件、语言区域映射规则、输出文件格式以及物品图标 URL 的命名规范并能独立完成一套可被src/handbook前端直接消费的完整数据集。Handbook 数据在项目中的定位Grasscutter 仓库中附带了一个独立的 Web 前端——Handbook它是一个基于 Vite React 构建的单页应用用于查询服务器命令、物品、角色、实体、场景与任务信息。该前端本身不包含任何游戏数据其数据全部来自src/handbook/data/目录下的数据文件。从前端入口 data.ts 可以看到它一次性导入了七个数据文件import mainQuests from data/mainquests.csv; import commands from data/commands.json; import entities from data/entities.csv; import avatars from data/avatars.csv; import scenes from data/scenes.csv; import quests from data/quests.csv; import items from data/items.csv;这七个文件正是 src/handbook/data/README.md 所描述的“Files Required”清单。也就是说Handbook 的完整数据链路是Grasscutter 服务端资源 →-dump导出 → 七个数据文件 → 前端消费。本文核心任务就是把链路的中间一环——数据生成——讲透。前置条件什么是Grasscutter 已就绪README 明确说明使用 Dumpers 生成数据要求 Grasscutter 处于已设置好set up状态具体包含两点已安装 Java 运行时Grasscutter 以grasscutter.jar形式运行导出数据同样通过该 jar 的启动参数触发工作目录中已提供游戏资源ResourcesDumpers 需要从资源目录加载 TextMap文本映射表、Excel 配置等数据才能解析出名称与描述。从源码看这一点在 Dumpers.java 中得到了印证——每个导出函数除命令外都会先执行ResourceLoader.loadAll(); Language.loadTextMaps();loadAll()负责加载全部游戏配置资源loadTextMaps()负责加载各语言文本映射之后才能把 hash 值翻译成人类可读的名称。若缺少资源目录导出将无法正确输出名称字段。七类数据导出命令详解所有导出命令统一通过启动参数-dumpcontent,language触发。该参数在 StartupArguments.java 中被解析content决定导出哪类数据language决定使用哪种语言区域若参数缺少逗号会输出错误提示Dumper usage: -dumpcontent,language。导出完成后程序打印Finished dumping.并退出。数据类型生成命令输出文件文件格式命令java -jar grasscutter.jar -dumpcommands,en-uscommands.jsonJSON物品java -jar grasscutter.jar -dumpitems,ENitems.csvCSV角色java -jar grasscutter.jar -dumpavatars,ENavatars.csvCSV任务java -jar grasscutter.jar -dumpquests,ENquests.csvmainquests.csvCSV实体java -jar grasscutter.jar -dumpentities,en-usentities.csvCSV区域java -jar grasscutter.jar -dumpareas,ENareas.csvCSV场景java -jar grasscutter.jar -dumpscenes,en-usscenes.csvCSV注意-dumpscenes不接收语言参数见 StartupArguments.java因为场景导出仅包含脚本标识符与场景类型不涉及翻译文本。不过传入语言值也不会报错。命令commands→ JSON导出命令会遍历CommandMap中注册的全部命令处理器为每个命令收集标签与别名、本地化描述、用法、权限和目标要求最终写入commands.jsonnew CommandInfo( labels, // 标签 别名 description, // 本地化描述 List.of(command.usage()), List.of(command.permission(), command.permissionTargeted()), command.targetRequirement());对应的 TypeScript 类型定义见 types.ts前端按name[0]主标签对命令排序展示。这是唯一输出 JSON 格式的数据类型其余均为 CSV。物品items→ items.csv物品导出遍历GameData.getItemDataMap()为每个物品记录 ID、本地化名称、品质、物品类型和图标字段new ItemInfo( id, Language.getTextMapKey(item.getNameTextMapHash()).get(locale), Quality.from(item.getRankLevel()), item.getItemType(), item.getIcon().length() 0 ? item.getIcon().substring(3) : );导出时会做三重过滤见 Dumpers.java丢弃名称含[CHS]的条目、丢弃名称重复的条目、丢弃 ID 重复的条目以保证 Handbook 列表干净无冗余。物品的品质由rankLevel映射而来Dumpers.javarankLevel品质0UNKNOWN1COMMON2UNCOMMON3RARE4EPIC≥5LEGENDARY角色avatars→ avatars.csv角色导出遍历GameData.getAvatarDataMap()根据角色品质类型QUALITY_PURPLE→ EPIC其余 → LEGENDARY与本地化名称生成记录new AvatarInfo( langHash 0 ? avatar.getName() : Language.getTextMapKey(langHash).get(locale), avatar.getQualityType().equals(QUALITY_PURPLE) ? Quality.EPIC : Quality.LEGENDARY);任务quests→ quests.csv mainquests.csv这是唯一一次导出产生两个文件的类型。quests.csv记录子任务ID、描述、所属主任务 IDmainquests.csv记录主任务ID、标题Files.writeString(file.toPath(), Dumpers.miniEncode(dump, id, description, mainId)); // ... Files.writeString(file.toPath(), Dumpers.miniEncode(mainDump, id, title));注意其中描述/标题中的英文逗号会被替换为\转义防止破坏 CSV 列结构前端 data.ts 读取时会用replaceAll(\\, ,)还原。前端利用mainId字段把子任务挂到对应主任务下并以react-d3-tree渲染任务树。实体entities→ entities.csv实体导出遍历GameData.getMonsterDataMap()每条记录包含本地化名称与内部名称internal即怪物配置键名new EntityInfo( langHash 0 ? monster.getMonsterName() : Language.getTextMapKey(langHash).get(locale), monster.getMonsterName());前端读取时会过滤掉名称中含Mechanicus的条目data.ts避免展示实验性/机关类实体。区域areas→ areas.csv区域导出遍历GameData.getWorldAreaDataMap()并带有父子层级处理逻辑以childArea子区域作为记录 IDparentArea父区域作为 parent 字段若某区域没有子区域则退而用父区域 ID 作为记录 IDdump.put( area.getChildArea() 0 ? area.getParentArea() : area.getChildArea(), new AreaInfo(area.getParentArea(), /* 本地化名称 */));输出带表头id,parent,name完整保留了区域间的从属关系。场景scenes→ scenes.csv场景导出遍历GameData.getSceneDataMap()记录场景 ID、脚本数据标识scriptData与场景类型new SceneInfo(scene.getScriptData(), scene.getSceneType());前端按 ID 升序排列展示并依据SceneTypeSCENE_WORLD、SCENE_DUNGEON、SCENE_HOME_WORLD等见 types.ts进行分类。CSV 通用编码格式除commands.json外其余文件均由miniEncode方法生成Dumpers.java。核心规则为一行一条记录ID,值两列多字段数据追加列private static String miniEncode(MapInteger, ? dump) { return dump.entrySet().stream() .map(entry - entry.getKey() , entry.getValue().toString()) .collect(Collectors.joining(\n)); }其中每条记录的toString()输出由各 Info 类决定例如物品行格式为id,name,quality,type,iconDumpers.java实体行格式为id,name,internal。若需要表头如quests.csv、mainquests.csv、areas.csv则调用带headers参数的重载在首行拼入列名。语言区域Language Locales映射README 提供了一个关键映射表Grasscutter Language LocaleHandbook Language Localeen-usEN含义是命令行传入的en-us或EN会被解析为同一种英语区域。你可以把en-us或EN替换成其他与格式匹配的语言区域代码从而生成对应语言的数据集。从实现上看Grasscutter 的语言文件按TextMaplang.json存放Tools.java 通过扫描TextMap*.json列出可用语言。Dumpers.java 中的commandDescription方法展示了语言解析的核心逻辑通过Language.getLanguage(locale)获取语言对象再查询commands.label.description键若语言无效则回退为命令标签本身。因此只要资源目录中存在对应语言的 TextMap 文件即可用该语言区域代码进行导出。生成后的文件清单一次完整的导出流程按上述七条命令逐条执行会在当前工作目录产生以下文件README 中将其列为 Handbook 运行所必需的输入mainquests.csvcommands.jsonentities.csvavatars.csvscenes.csvquests.csvitems.csv把这些文件放入src/handbook/data/目录后执行npm install npm run build见 package.json即可将数据集打包进 Handbook 前端。构建时rollup/plugin-dsv负责把 CSV 转换为可导入模块vite-plugin-singlefile负责把整站打包为单文件。数据在前端的分类规则生成后的物品数据会依据 ID 区间进一步分类data.ts角色Avatar ItemsID 在1002–1099之间命之座ConstellationID 在1102–1199之间这正与 README 中Avatar Items are between ranges 1001 and 1099的说明相呼应也是后续图标命名规范中区分角色物品与普通物品的依据之一。物品图标 URL 命名规范README 为 Handbook 物品卡片引用了外部图源并记录了详细的 URL 模板规则以下模式均来自 src/handbook/data/README.md 的原始说明供维护者拼接图源时参考圣遗物Artifacts基础模板https://bbs.hoyolab.com/hoyowiki/picture/reliquary/(name)/(piece)_icon.png备用源为https://api.ambr.top/assets/UI/reliquary/UI_RelicIcon_(set)_(piece).png。(piece)的取值规则如下编号后缀部件xxxx1goblet_of_eonothem时之沙/空之杯族系xxxx2plume_of_death死之羽xxxx3circlet_of_logos/plume_of_death理之冠xxxx4flower_of_life生之花xxxx5sands_of_eon时之沙注意xxxx3的特殊处理套装完整时使用circlet_of_logos只有套装一部分时使用plume_of_death。杂物Miscellaneous Items模板https://bbs.hoyolab.com/hoyowiki/picture/object/(name)_icon.png备用源为https://api.ambr.top/assets/UI/UI_ItemIcon_(id).png。涵盖材料、任务物品、食物等。角色与角色物品Avatars / Avatar Items模板https://bbs.hoyolab.com/hoyowiki/picture/character/(name)_icon.png。角色物品的 ID 位于1001–1099区间。武器Weapons模板https://api.ambr.top/assets/UI/UI_EquipIcon_(type)_(name).png。家具Furniture模板https://api.ambr.top/assets/UI/furniture/UI_Homeworld_(location)_(name).png。怪物Monsters模板https://api.ambr.top/assets/UI/monster/UI_MonsterIcon_(type)_(variant).png。数据来源与致谢README 在 Credits 部分明确列出了两类数据辅助来源Grasscutter Command Helper 项目的...List.json文件用于命令列表数据以及 Project Amber 的内部素材 API用于物品/实体详情与图标。这些外部数据源仅作为 Handbook 展示层的补充参考而核心数据集ID、名称、品质、类型始终由 Grasscutter 自身资源通过本文所述的-dump参数导出生成从而保证手册数据与服务器实际运行的数据严格一致。维护建议每次更新服务器资源后重新导出由于名称与描述来源于 TextMap 和 Excel 配置游戏版本更新后应重跑全部-dump命令避免 Handbook 与服务器数据脱节语言一致性导出的语言区域必须与 Handbook 目标受众一致如英文站统一使用en-us/EN检查七个文件是否齐全前端构建依赖全部七个文件缺失任何一个都会导致vite build阶段模块导入失败关注转义规则quests.csv与mainquests.csv中英文逗号会被转义为\手工编辑这两个文件时务必保持该约定否则前端解析会错乱。【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Grasscutter Handbook 数据生成完全指南：使用 -dump 参数导出 GM 手册数据集
Grasscutter Handbook 数据生成完全指南使用 -dump 参数导出 GM 手册数据集【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter本篇技术指南面向 Grasscutter 服务端搭建者与 HandbookGM 手册维护者完整讲解如何利用 Grasscutter 内置的 Dumpers 工具通过一条-dumpcontent,language启动参数从游戏资源中生成 Handbook 前端所需的全部数据文件命令、物品、角色、任务、实体、区域、场景等。读完本文你将掌握每类数据的生成命令、前置条件、语言区域映射规则、输出文件格式以及物品图标 URL 的命名规范并能独立完成一套可被src/handbook前端直接消费的完整数据集。Handbook 数据在项目中的定位Grasscutter 仓库中附带了一个独立的 Web 前端——Handbook它是一个基于 Vite React 构建的单页应用用于查询服务器命令、物品、角色、实体、场景与任务信息。该前端本身不包含任何游戏数据其数据全部来自src/handbook/data/目录下的数据文件。从前端入口 data.ts 可以看到它一次性导入了七个数据文件import mainQuests from data/mainquests.csv; import commands from data/commands.json; import entities from data/entities.csv; import avatars from data/avatars.csv; import scenes from data/scenes.csv; import quests from data/quests.csv; import items from data/items.csv;这七个文件正是 src/handbook/data/README.md 所描述的“Files Required”清单。也就是说Handbook 的完整数据链路是Grasscutter 服务端资源 →-dump导出 → 七个数据文件 → 前端消费。本文核心任务就是把链路的中间一环——数据生成——讲透。前置条件什么是Grasscutter 已就绪README 明确说明使用 Dumpers 生成数据要求 Grasscutter 处于已设置好set up状态具体包含两点已安装 Java 运行时Grasscutter 以grasscutter.jar形式运行导出数据同样通过该 jar 的启动参数触发工作目录中已提供游戏资源ResourcesDumpers 需要从资源目录加载 TextMap文本映射表、Excel 配置等数据才能解析出名称与描述。从源码看这一点在 Dumpers.java 中得到了印证——每个导出函数除命令外都会先执行ResourceLoader.loadAll(); Language.loadTextMaps();loadAll()负责加载全部游戏配置资源loadTextMaps()负责加载各语言文本映射之后才能把 hash 值翻译成人类可读的名称。若缺少资源目录导出将无法正确输出名称字段。七类数据导出命令详解所有导出命令统一通过启动参数-dumpcontent,language触发。该参数在 StartupArguments.java 中被解析content决定导出哪类数据language决定使用哪种语言区域若参数缺少逗号会输出错误提示Dumper usage: -dumpcontent,language。导出完成后程序打印Finished dumping.并退出。数据类型生成命令输出文件文件格式命令java -jar grasscutter.jar -dumpcommands,en-uscommands.jsonJSON物品java -jar grasscutter.jar -dumpitems,ENitems.csvCSV角色java -jar grasscutter.jar -dumpavatars,ENavatars.csvCSV任务java -jar grasscutter.jar -dumpquests,ENquests.csvmainquests.csvCSV实体java -jar grasscutter.jar -dumpentities,en-usentities.csvCSV区域java -jar grasscutter.jar -dumpareas,ENareas.csvCSV场景java -jar grasscutter.jar -dumpscenes,en-usscenes.csvCSV注意-dumpscenes不接收语言参数见 StartupArguments.java因为场景导出仅包含脚本标识符与场景类型不涉及翻译文本。不过传入语言值也不会报错。命令commands→ JSON导出命令会遍历CommandMap中注册的全部命令处理器为每个命令收集标签与别名、本地化描述、用法、权限和目标要求最终写入commands.jsonnew CommandInfo( labels, // 标签 别名 description, // 本地化描述 List.of(command.usage()), List.of(command.permission(), command.permissionTargeted()), command.targetRequirement());对应的 TypeScript 类型定义见 types.ts前端按name[0]主标签对命令排序展示。这是唯一输出 JSON 格式的数据类型其余均为 CSV。物品items→ items.csv物品导出遍历GameData.getItemDataMap()为每个物品记录 ID、本地化名称、品质、物品类型和图标字段new ItemInfo( id, Language.getTextMapKey(item.getNameTextMapHash()).get(locale), Quality.from(item.getRankLevel()), item.getItemType(), item.getIcon().length() 0 ? item.getIcon().substring(3) : );导出时会做三重过滤见 Dumpers.java丢弃名称含[CHS]的条目、丢弃名称重复的条目、丢弃 ID 重复的条目以保证 Handbook 列表干净无冗余。物品的品质由rankLevel映射而来Dumpers.javarankLevel品质0UNKNOWN1COMMON2UNCOMMON3RARE4EPIC≥5LEGENDARY角色avatars→ avatars.csv角色导出遍历GameData.getAvatarDataMap()根据角色品质类型QUALITY_PURPLE→ EPIC其余 → LEGENDARY与本地化名称生成记录new AvatarInfo( langHash 0 ? avatar.getName() : Language.getTextMapKey(langHash).get(locale), avatar.getQualityType().equals(QUALITY_PURPLE) ? Quality.EPIC : Quality.LEGENDARY);任务quests→ quests.csv mainquests.csv这是唯一一次导出产生两个文件的类型。quests.csv记录子任务ID、描述、所属主任务 IDmainquests.csv记录主任务ID、标题Files.writeString(file.toPath(), Dumpers.miniEncode(dump, id, description, mainId)); // ... Files.writeString(file.toPath(), Dumpers.miniEncode(mainDump, id, title));注意其中描述/标题中的英文逗号会被替换为\转义防止破坏 CSV 列结构前端 data.ts 读取时会用replaceAll(\\, ,)还原。前端利用mainId字段把子任务挂到对应主任务下并以react-d3-tree渲染任务树。实体entities→ entities.csv实体导出遍历GameData.getMonsterDataMap()每条记录包含本地化名称与内部名称internal即怪物配置键名new EntityInfo( langHash 0 ? monster.getMonsterName() : Language.getTextMapKey(langHash).get(locale), monster.getMonsterName());前端读取时会过滤掉名称中含Mechanicus的条目data.ts避免展示实验性/机关类实体。区域areas→ areas.csv区域导出遍历GameData.getWorldAreaDataMap()并带有父子层级处理逻辑以childArea子区域作为记录 IDparentArea父区域作为 parent 字段若某区域没有子区域则退而用父区域 ID 作为记录 IDdump.put( area.getChildArea() 0 ? area.getParentArea() : area.getChildArea(), new AreaInfo(area.getParentArea(), /* 本地化名称 */));输出带表头id,parent,name完整保留了区域间的从属关系。场景scenes→ scenes.csv场景导出遍历GameData.getSceneDataMap()记录场景 ID、脚本数据标识scriptData与场景类型new SceneInfo(scene.getScriptData(), scene.getSceneType());前端按 ID 升序排列展示并依据SceneTypeSCENE_WORLD、SCENE_DUNGEON、SCENE_HOME_WORLD等见 types.ts进行分类。CSV 通用编码格式除commands.json外其余文件均由miniEncode方法生成Dumpers.java。核心规则为一行一条记录ID,值两列多字段数据追加列private static String miniEncode(MapInteger, ? dump) { return dump.entrySet().stream() .map(entry - entry.getKey() , entry.getValue().toString()) .collect(Collectors.joining(\n)); }其中每条记录的toString()输出由各 Info 类决定例如物品行格式为id,name,quality,type,iconDumpers.java实体行格式为id,name,internal。若需要表头如quests.csv、mainquests.csv、areas.csv则调用带headers参数的重载在首行拼入列名。语言区域Language Locales映射README 提供了一个关键映射表Grasscutter Language LocaleHandbook Language Localeen-usEN含义是命令行传入的en-us或EN会被解析为同一种英语区域。你可以把en-us或EN替换成其他与格式匹配的语言区域代码从而生成对应语言的数据集。从实现上看Grasscutter 的语言文件按TextMaplang.json存放Tools.java 通过扫描TextMap*.json列出可用语言。Dumpers.java 中的commandDescription方法展示了语言解析的核心逻辑通过Language.getLanguage(locale)获取语言对象再查询commands.label.description键若语言无效则回退为命令标签本身。因此只要资源目录中存在对应语言的 TextMap 文件即可用该语言区域代码进行导出。生成后的文件清单一次完整的导出流程按上述七条命令逐条执行会在当前工作目录产生以下文件README 中将其列为 Handbook 运行所必需的输入mainquests.csvcommands.jsonentities.csvavatars.csvscenes.csvquests.csvitems.csv把这些文件放入src/handbook/data/目录后执行npm install npm run build见 package.json即可将数据集打包进 Handbook 前端。构建时rollup/plugin-dsv负责把 CSV 转换为可导入模块vite-plugin-singlefile负责把整站打包为单文件。数据在前端的分类规则生成后的物品数据会依据 ID 区间进一步分类data.ts角色Avatar ItemsID 在1002–1099之间命之座ConstellationID 在1102–1199之间这正与 README 中Avatar Items are between ranges 1001 and 1099的说明相呼应也是后续图标命名规范中区分角色物品与普通物品的依据之一。物品图标 URL 命名规范README 为 Handbook 物品卡片引用了外部图源并记录了详细的 URL 模板规则以下模式均来自 src/handbook/data/README.md 的原始说明供维护者拼接图源时参考圣遗物Artifacts基础模板https://bbs.hoyolab.com/hoyowiki/picture/reliquary/(name)/(piece)_icon.png备用源为https://api.ambr.top/assets/UI/reliquary/UI_RelicIcon_(set)_(piece).png。(piece)的取值规则如下编号后缀部件xxxx1goblet_of_eonothem时之沙/空之杯族系xxxx2plume_of_death死之羽xxxx3circlet_of_logos/plume_of_death理之冠xxxx4flower_of_life生之花xxxx5sands_of_eon时之沙注意xxxx3的特殊处理套装完整时使用circlet_of_logos只有套装一部分时使用plume_of_death。杂物Miscellaneous Items模板https://bbs.hoyolab.com/hoyowiki/picture/object/(name)_icon.png备用源为https://api.ambr.top/assets/UI/UI_ItemIcon_(id).png。涵盖材料、任务物品、食物等。角色与角色物品Avatars / Avatar Items模板https://bbs.hoyolab.com/hoyowiki/picture/character/(name)_icon.png。角色物品的 ID 位于1001–1099区间。武器Weapons模板https://api.ambr.top/assets/UI/UI_EquipIcon_(type)_(name).png。家具Furniture模板https://api.ambr.top/assets/UI/furniture/UI_Homeworld_(location)_(name).png。怪物Monsters模板https://api.ambr.top/assets/UI/monster/UI_MonsterIcon_(type)_(variant).png。数据来源与致谢README 在 Credits 部分明确列出了两类数据辅助来源Grasscutter Command Helper 项目的...List.json文件用于命令列表数据以及 Project Amber 的内部素材 API用于物品/实体详情与图标。这些外部数据源仅作为 Handbook 展示层的补充参考而核心数据集ID、名称、品质、类型始终由 Grasscutter 自身资源通过本文所述的-dump参数导出生成从而保证手册数据与服务器实际运行的数据严格一致。维护建议每次更新服务器资源后重新导出由于名称与描述来源于 TextMap 和 Excel 配置游戏版本更新后应重跑全部-dump命令避免 Handbook 与服务器数据脱节语言一致性导出的语言区域必须与 Handbook 目标受众一致如英文站统一使用en-us/EN检查七个文件是否齐全前端构建依赖全部七个文件缺失任何一个都会导致vite build阶段模块导入失败关注转义规则quests.csv与mainquests.csv中英文逗号会被转义为\手工编辑这两个文件时务必保持该约定否则前端解析会错乱。【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
