GDevelop 5 主题系统完全指南基于 theme.json 与 Style Dictionary 的编辑器主题开发【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop主题Themes是 GDevelop 5 编辑器位于 newIDE 目录中一套统一的颜色与样式集合负责让整个编辑器的视觉风格保持一致。本篇指南以官方文档 newIDE/README-themes.md 为骨架结合仓库中的真实源码构建脚本、主题模板、内置主题配置进行深入讲解。读完本文你将掌握 GDevelop 主题系统的整体架构theme.json→ CSS 自定义属性 扁平 JSON 双产物、create-new-theme与build-theme-resources两个 npm 脚本的完整用法与底层实现并能够独立创建、编辑和重新编译自己的主题。主题系统概览一份 theme.json两种消费方式GDevelop 的主题本质上是一个可编辑的单一事实来源single source of truth。所有主题细节颜色、宽度、圆角等样式都保存在一个theme.json文件中该文件会被用于生成两类产物一个.css文件将样式编译为CSS Custom PropertiesCSS 变量。这些属性通过把主题类theme class应用到应用的特定区块上而生效。想要了解这些属性在哪些地方被使用可以查看Global文件夹下的样式表。一个.json文件将样式编译为扁平对象其中每个样式是对象的一个字段。该文件会被Material UI 库以及自定义组件导入使用。这套编译工作由 Style Dictionary 中注册了对应的 npm 脚本build-theme-resources: node scripts/build-theme-resources.js, create-new-theme: node scripts/create-new-theme.js,换句话说开发者平时只需要维护theme.jsonCSS 变量文件与 Material UI 可消费的扁平 JSON 都是自动生成、可随时重建的中间产物。主题的存放位置与目录结构所有主题存放在 newIDE/app/src/UI/Theme 目录下每个主题拥有一个独立的子文件夹其中包含两个核心文件文件作用index.js生成描述主题的 JavaScript 对象供编辑器使用包括类名、应用于 Material-UI 的值同时负责导入编译生成的 CSS 文件theme.json存储主题的详细样式颜色、宽度等以默认浅色主题为例newIDE/app/src/UI/Theme/DefaultLightTheme/index.js 的完整内容如下import { createGdevelopTheme } from ../CreateTheme; import styles from ./DefaultLightThemeVariables.json; import ./DefaultLightThemeVariables.css; export default createGdevelopTheme({ styles, rootClassNameIdentifier: DefaultLightTheme, paletteType: light, });从中可以看到两个关键事实该index.js同时导入了两个由构建脚本自动生成的文件DefaultLightThemeVariables.json扁平样式对象供 Material UI 与自定义组件使用与DefaultLightThemeVariables.cssCSS 变量通过主题类作用于界面。主题对象由createGdevelopTheme工厂函数创建rootClassNameIdentifier声明了挂在界面区块上的主题类名paletteType标记主题是light还是dark色调。而创建新主题时使用的模板 newIDE/app/scripts/theme-templates/index.js 则展示了另一代 API 形态$THEME_ID是占位符会被脚本替换为实际主题标识import { createGdevelopTheme } from ../CreateTheme; import styles from ./$THEME_IDVariables.json; import ./$THEME_IDVariables.css; export default createGdevelopTheme(styles, $THEME_ID, dark);theme.json 的结构详解一份真实的主题配置theme.json是主题的“图纸”。它以嵌套 JSON形式组织所有样式 token顶层按语义划分了多个命名空间。以仓库中真实的 newIDE/app/src/UI/Theme/DefaultLightTheme/theme.json 为例顶层主要区块如下顶层区块语义典型子项示例theme编辑器全局样式primary/secondary/success/info/warning/error/premium品牌与状态色、hover、surface、dialog、text、link、switch、search-bar、selection、tabs、tooltip、snackbar、text-field、toggle-field、notification、list-item、closable-tabs等input输入控件样式border-bottom.colorevent-sheet事件表Events Sheet样式event-tree、conditions、actions、sub-instructions、instruction-parameter含base/number/object/behavior/operator/var/error等参数语法着色、link、drop-indicator等markdownMarkdown 渲染样式blockquote.border-left.color、link.colorsound-player音频播放器样式play-button.primary、wave-color、progress-colormosaic窗口分栏Mosaic样式title、layout、toolbartable表格样式border、text、header、row.odd/row.even/row.selected每个样式值都是一个对象通常包含value字段颜色可用十六进制#4F28CD、rgba(...)或rgb(...)形式并常附comment字段说明其取自设计系统调色板的哪个档位例如primary: { dark: { value: #37238F, comment: Palette/Purple/60 }, color: { value: #4F28CD, comment: Palette/Purple/50 }, light: { value: #7046EC, comment: Palette/Purple/40 }, text-contrast-color: { value: #FAFAFA, comment: Palette/Grey/00 } }theme.json中还可以引用其他 token 的值Style Dictionary 的别名引用语法例如drop-indicator.can-drop.color写为{gdevelop.color.light-blue.value}、sub-instructions.border写为1px solid {event-sheet.sub-instructions.border-color.value}便于保持 token 之间的联动关系。除了各主题自己的theme.json构建脚本还会合并一份全局基础 tokennewIDE/app/src/UI/Theme/Global/styles.json其中定义了所有主题共用的gdevelop命名空间如color.light-blue、color.blue、color.dark-blue、color.purple、color.contrast-text、color.selection以及classic-font-family、modern-font-family两套字体族。也就是说每个主题的最终样式 全局基础 token 主题自身的覆盖。构建流程源码解析build-theme-resources 做了什么官方文档要求修改theme.json后必须运行以下命令重新编译npm run build-theme-resources该命令实际执行的是 newIDE/app/scripts/build-theme-resources.js。其核心逻辑如下源码级解读读取主题注册表调用readThemeRegistry()实现见 newIDE/app/scripts/lib/ReadThemeRegistry.js通过正则匹配 newIDE/app/src/UI/Theme/ThemeRegistry.js 中形如[Theme Name]: ThemeId,的条目得到「显示名 → 标识符」的注册列表。逐个主题调用 Style Dictionary 构建对每个注册的主题执行style.extend({...}).buildAllPlatforms()其中source数组固定为两份输入Global/styles.json全局基础样式与主题文件夹/theme.json主题专属覆盖css平台使用css转换组与css/variables格式输出到主题名Variables.cssjs平台使用js转换组与json/flat格式输出到主题名Variables.json即扁平化的样式对象。注册自定义 actionset_theme_class构建完成后脚本会把生成的 CSS 文件中的:root选择器整体替换为. 主题类名如.DefaultLightTheme。这正是文档中所说“通过把主题类应用到应用的特定区块上”来实现样式生效的技术细节——主题类名来源于各主题index.js中声明的rootClassNameIdentifier。因此整个数据流是Global/styles.json 主题/theme.json │ (Style Dictionary) ▼ 主题Variables.css (CSS 自定义属性:root → .主题类) → 由 index.js 导入作用于界面 主题Variables.json (扁平对象) → 供 Material UI 与自定义组件消费创建新主题create-new-theme 一站式脚手架官方文档给出的创建命令是npm run create-new-theme Theme Name该命令的执行入口是 newIDE/app/scripts/create-new-theme.js其工作流程与源码逻辑如下名称规范化若传入的名称以Theme结尾不区分大小写会先去掉尾部的Theme随后移除空格并追加Theme生成主题标识符。例如输入Foo Bar或Foo Bar Theme都会得到主题文件夹名FooBarTheme。冲突检查如果目标文件夹src/UI/Theme/主题标识符已存在脚本会报错❌ Theme xxx already exists并退出。创建目录与文件新建主题文件夹并从模板复制两份文件newIDE/app/scripts/theme-templates/theme.json默认值主题配置newIDE/app/scripts/theme-templates/index.js将其中$THEME_ID占位符替换为实际主题标识符替换后即变成导入FooBarThemeVariables.css/json的index.js。更新主题注册表将新主题追加到 newIDE/app/src/UI/Theme/ThemeRegistry.js。该文件本身就是由脚本自动生成的头部带注释// This file is generated by create-new-theme.js script内容包含对每个主题index.js的import以及themes导出对象。重新编译全部主题脚本最后自动调用build-theme-resources.js一次性重新构建所有主题的资源包括新建的这个无需再手动执行。因此npm run create-new-theme一次性完成了「创建文件夹 → 生成index.js/theme.json→ 更新根目录注册表 → 重新编译所有主题」的全部工作这正是官方文档所描述的“It will also update files in the root directory, as well as recompile all themes (including the new one)”。内置主题一览ThemeRegistry 与主题选择当前仓库内置了 8 套主题在 newIDE/app/src/UI/Theme/ThemeRegistry.js 中注册如下显示名注册表键主题标识符 / 文件夹GDevelop default DarkDefaultDarkThemeGDevelop default LightDefaultLightThemeBlue DarkBlueDarkThemeNordNordThemeSolarized DarkSolarizedDarkThemeOne DarkOneDarkThemeRosé PineRosePineThemeDeep BlueDeepBlueTheme其中 newIDE/app/src/UI/Theme/RosePineTheme 还附带了自己的README.md说明文档。可以看到注册表中的“显示名”与“文件夹名”并不要求一致如Rosé PinevsRosePineTheme二者通过注册表映射这也是为什么ReadThemeRegistry.js要专门解析这一对键值。如果你希望创作一套全新风格的主题最省事的路径就是参考 RosePineTheme 等已有主题的theme.json结构 → 运行npm run create-new-theme 名称生成骨架 → 修改theme.json中的色值与尺寸 → 运行npm run build-theme-resources重新编译 → 在编辑器中切换主题预览效果。编辑主题的标准工作流与注意事项修改既有主题而非新建的推荐工作流是# 1. 编辑主题目录下的 theme.json改颜色、宽度等样式值 # 2. 重新编译样式为 .css 与 .json npm run build-theme-resources官方文档特别强调每次改动后都必须重新运行该命令因为编辑器运行时直接消费的是编译产物Variables.css与Variables.json而非theme.json本身。实操中还需注意几点保持 token 命名一致性theme.json的键名结构直接决定生成的 CSS 变量名与扁平 JSON 字段名改动键名需要同步检查Global文件夹下样式表中对相应 CSS 变量的引用。全局样式表是变量消费方CSS 自定义属性的实际使用位置在 newIDE/app/src/UI/Theme/Global 下的Animation.css、EventsSheet.css、Font.css、Markdown.css、Mosaic.css、Scrollbar.css、Snackbar.css、Table.css等样式表中主题类被应用到界面区块后这些样式表中的变量引用即告生效。构建脚本可独立运行build-theme-resources也会被import-resources等更上层的 npm 脚本调用见 newIDE/app/package.json说明它是 IDE 资源准备管线中的基础环节。主题类名与调色板paletteTypelight/dark与rootClassNameIdentifier在index.js中声明若新建主题是从旧模板复制而来建议参照 DefaultLightTheme/index.js 采用带rootClassNameIdentifier与paletteType的新式createGdevelopTheme调用以获得更明确的主题标识与明暗语义。小结GDevelop 的主题系统是一个典型的「声明式 token 自动化编译」设计开发者只需面向嵌套的theme.json声明样式build-theme-resources借助 Style Dictionary 产出 CSS 自定义属性与扁平 JSON 双份资源分别服务于全局样式表与 Material UI/自定义组件create-new-theme则把新建主题的文件夹生成、模板填充、注册表更新与全量重编译整合为一条命令。理解这套数据流后无论是微调内置主题配色还是从零打造一套全新风格的编辑器皮肤都只需围绕theme.json展开即可。【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GDevelop 5 主题系统完全指南：基于 theme.json 与 Style Dictionary 的编辑器主题开发
GDevelop 5 主题系统完全指南基于 theme.json 与 Style Dictionary 的编辑器主题开发【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop主题Themes是 GDevelop 5 编辑器位于 newIDE 目录中一套统一的颜色与样式集合负责让整个编辑器的视觉风格保持一致。本篇指南以官方文档 newIDE/README-themes.md 为骨架结合仓库中的真实源码构建脚本、主题模板、内置主题配置进行深入讲解。读完本文你将掌握 GDevelop 主题系统的整体架构theme.json→ CSS 自定义属性 扁平 JSON 双产物、create-new-theme与build-theme-resources两个 npm 脚本的完整用法与底层实现并能够独立创建、编辑和重新编译自己的主题。主题系统概览一份 theme.json两种消费方式GDevelop 的主题本质上是一个可编辑的单一事实来源single source of truth。所有主题细节颜色、宽度、圆角等样式都保存在一个theme.json文件中该文件会被用于生成两类产物一个.css文件将样式编译为CSS Custom PropertiesCSS 变量。这些属性通过把主题类theme class应用到应用的特定区块上而生效。想要了解这些属性在哪些地方被使用可以查看Global文件夹下的样式表。一个.json文件将样式编译为扁平对象其中每个样式是对象的一个字段。该文件会被Material UI 库以及自定义组件导入使用。这套编译工作由 Style Dictionary 中注册了对应的 npm 脚本build-theme-resources: node scripts/build-theme-resources.js, create-new-theme: node scripts/create-new-theme.js,换句话说开发者平时只需要维护theme.jsonCSS 变量文件与 Material UI 可消费的扁平 JSON 都是自动生成、可随时重建的中间产物。主题的存放位置与目录结构所有主题存放在 newIDE/app/src/UI/Theme 目录下每个主题拥有一个独立的子文件夹其中包含两个核心文件文件作用index.js生成描述主题的 JavaScript 对象供编辑器使用包括类名、应用于 Material-UI 的值同时负责导入编译生成的 CSS 文件theme.json存储主题的详细样式颜色、宽度等以默认浅色主题为例newIDE/app/src/UI/Theme/DefaultLightTheme/index.js 的完整内容如下import { createGdevelopTheme } from ../CreateTheme; import styles from ./DefaultLightThemeVariables.json; import ./DefaultLightThemeVariables.css; export default createGdevelopTheme({ styles, rootClassNameIdentifier: DefaultLightTheme, paletteType: light, });从中可以看到两个关键事实该index.js同时导入了两个由构建脚本自动生成的文件DefaultLightThemeVariables.json扁平样式对象供 Material UI 与自定义组件使用与DefaultLightThemeVariables.cssCSS 变量通过主题类作用于界面。主题对象由createGdevelopTheme工厂函数创建rootClassNameIdentifier声明了挂在界面区块上的主题类名paletteType标记主题是light还是dark色调。而创建新主题时使用的模板 newIDE/app/scripts/theme-templates/index.js 则展示了另一代 API 形态$THEME_ID是占位符会被脚本替换为实际主题标识import { createGdevelopTheme } from ../CreateTheme; import styles from ./$THEME_IDVariables.json; import ./$THEME_IDVariables.css; export default createGdevelopTheme(styles, $THEME_ID, dark);theme.json 的结构详解一份真实的主题配置theme.json是主题的“图纸”。它以嵌套 JSON形式组织所有样式 token顶层按语义划分了多个命名空间。以仓库中真实的 newIDE/app/src/UI/Theme/DefaultLightTheme/theme.json 为例顶层主要区块如下顶层区块语义典型子项示例theme编辑器全局样式primary/secondary/success/info/warning/error/premium品牌与状态色、hover、surface、dialog、text、link、switch、search-bar、selection、tabs、tooltip、snackbar、text-field、toggle-field、notification、list-item、closable-tabs等input输入控件样式border-bottom.colorevent-sheet事件表Events Sheet样式event-tree、conditions、actions、sub-instructions、instruction-parameter含base/number/object/behavior/operator/var/error等参数语法着色、link、drop-indicator等markdownMarkdown 渲染样式blockquote.border-left.color、link.colorsound-player音频播放器样式play-button.primary、wave-color、progress-colormosaic窗口分栏Mosaic样式title、layout、toolbartable表格样式border、text、header、row.odd/row.even/row.selected每个样式值都是一个对象通常包含value字段颜色可用十六进制#4F28CD、rgba(...)或rgb(...)形式并常附comment字段说明其取自设计系统调色板的哪个档位例如primary: { dark: { value: #37238F, comment: Palette/Purple/60 }, color: { value: #4F28CD, comment: Palette/Purple/50 }, light: { value: #7046EC, comment: Palette/Purple/40 }, text-contrast-color: { value: #FAFAFA, comment: Palette/Grey/00 } }theme.json中还可以引用其他 token 的值Style Dictionary 的别名引用语法例如drop-indicator.can-drop.color写为{gdevelop.color.light-blue.value}、sub-instructions.border写为1px solid {event-sheet.sub-instructions.border-color.value}便于保持 token 之间的联动关系。除了各主题自己的theme.json构建脚本还会合并一份全局基础 tokennewIDE/app/src/UI/Theme/Global/styles.json其中定义了所有主题共用的gdevelop命名空间如color.light-blue、color.blue、color.dark-blue、color.purple、color.contrast-text、color.selection以及classic-font-family、modern-font-family两套字体族。也就是说每个主题的最终样式 全局基础 token 主题自身的覆盖。构建流程源码解析build-theme-resources 做了什么官方文档要求修改theme.json后必须运行以下命令重新编译npm run build-theme-resources该命令实际执行的是 newIDE/app/scripts/build-theme-resources.js。其核心逻辑如下源码级解读读取主题注册表调用readThemeRegistry()实现见 newIDE/app/scripts/lib/ReadThemeRegistry.js通过正则匹配 newIDE/app/src/UI/Theme/ThemeRegistry.js 中形如[Theme Name]: ThemeId,的条目得到「显示名 → 标识符」的注册列表。逐个主题调用 Style Dictionary 构建对每个注册的主题执行style.extend({...}).buildAllPlatforms()其中source数组固定为两份输入Global/styles.json全局基础样式与主题文件夹/theme.json主题专属覆盖css平台使用css转换组与css/variables格式输出到主题名Variables.cssjs平台使用js转换组与json/flat格式输出到主题名Variables.json即扁平化的样式对象。注册自定义 actionset_theme_class构建完成后脚本会把生成的 CSS 文件中的:root选择器整体替换为. 主题类名如.DefaultLightTheme。这正是文档中所说“通过把主题类应用到应用的特定区块上”来实现样式生效的技术细节——主题类名来源于各主题index.js中声明的rootClassNameIdentifier。因此整个数据流是Global/styles.json 主题/theme.json │ (Style Dictionary) ▼ 主题Variables.css (CSS 自定义属性:root → .主题类) → 由 index.js 导入作用于界面 主题Variables.json (扁平对象) → 供 Material UI 与自定义组件消费创建新主题create-new-theme 一站式脚手架官方文档给出的创建命令是npm run create-new-theme Theme Name该命令的执行入口是 newIDE/app/scripts/create-new-theme.js其工作流程与源码逻辑如下名称规范化若传入的名称以Theme结尾不区分大小写会先去掉尾部的Theme随后移除空格并追加Theme生成主题标识符。例如输入Foo Bar或Foo Bar Theme都会得到主题文件夹名FooBarTheme。冲突检查如果目标文件夹src/UI/Theme/主题标识符已存在脚本会报错❌ Theme xxx already exists并退出。创建目录与文件新建主题文件夹并从模板复制两份文件newIDE/app/scripts/theme-templates/theme.json默认值主题配置newIDE/app/scripts/theme-templates/index.js将其中$THEME_ID占位符替换为实际主题标识符替换后即变成导入FooBarThemeVariables.css/json的index.js。更新主题注册表将新主题追加到 newIDE/app/src/UI/Theme/ThemeRegistry.js。该文件本身就是由脚本自动生成的头部带注释// This file is generated by create-new-theme.js script内容包含对每个主题index.js的import以及themes导出对象。重新编译全部主题脚本最后自动调用build-theme-resources.js一次性重新构建所有主题的资源包括新建的这个无需再手动执行。因此npm run create-new-theme一次性完成了「创建文件夹 → 生成index.js/theme.json→ 更新根目录注册表 → 重新编译所有主题」的全部工作这正是官方文档所描述的“It will also update files in the root directory, as well as recompile all themes (including the new one)”。内置主题一览ThemeRegistry 与主题选择当前仓库内置了 8 套主题在 newIDE/app/src/UI/Theme/ThemeRegistry.js 中注册如下显示名注册表键主题标识符 / 文件夹GDevelop default DarkDefaultDarkThemeGDevelop default LightDefaultLightThemeBlue DarkBlueDarkThemeNordNordThemeSolarized DarkSolarizedDarkThemeOne DarkOneDarkThemeRosé PineRosePineThemeDeep BlueDeepBlueTheme其中 newIDE/app/src/UI/Theme/RosePineTheme 还附带了自己的README.md说明文档。可以看到注册表中的“显示名”与“文件夹名”并不要求一致如Rosé PinevsRosePineTheme二者通过注册表映射这也是为什么ReadThemeRegistry.js要专门解析这一对键值。如果你希望创作一套全新风格的主题最省事的路径就是参考 RosePineTheme 等已有主题的theme.json结构 → 运行npm run create-new-theme 名称生成骨架 → 修改theme.json中的色值与尺寸 → 运行npm run build-theme-resources重新编译 → 在编辑器中切换主题预览效果。编辑主题的标准工作流与注意事项修改既有主题而非新建的推荐工作流是# 1. 编辑主题目录下的 theme.json改颜色、宽度等样式值 # 2. 重新编译样式为 .css 与 .json npm run build-theme-resources官方文档特别强调每次改动后都必须重新运行该命令因为编辑器运行时直接消费的是编译产物Variables.css与Variables.json而非theme.json本身。实操中还需注意几点保持 token 命名一致性theme.json的键名结构直接决定生成的 CSS 变量名与扁平 JSON 字段名改动键名需要同步检查Global文件夹下样式表中对相应 CSS 变量的引用。全局样式表是变量消费方CSS 自定义属性的实际使用位置在 newIDE/app/src/UI/Theme/Global 下的Animation.css、EventsSheet.css、Font.css、Markdown.css、Mosaic.css、Scrollbar.css、Snackbar.css、Table.css等样式表中主题类被应用到界面区块后这些样式表中的变量引用即告生效。构建脚本可独立运行build-theme-resources也会被import-resources等更上层的 npm 脚本调用见 newIDE/app/package.json说明它是 IDE 资源准备管线中的基础环节。主题类名与调色板paletteTypelight/dark与rootClassNameIdentifier在index.js中声明若新建主题是从旧模板复制而来建议参照 DefaultLightTheme/index.js 采用带rootClassNameIdentifier与paletteType的新式createGdevelopTheme调用以获得更明确的主题标识与明暗语义。小结GDevelop 的主题系统是一个典型的「声明式 token 自动化编译」设计开发者只需面向嵌套的theme.json声明样式build-theme-resources借助 Style Dictionary 产出 CSS 自定义属性与扁平 JSON 双份资源分别服务于全局样式表与 Material UI/自定义组件create-new-theme则把新建主题的文件夹生成、模板填充、注册表更新与全量重编译整合为一条命令。理解这套数据流后无论是微调内置主题配色还是从零打造一套全新风格的编辑器皮肤都只需围绕theme.json展开即可。【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考