GDevelop GDJS 双套文档的本地构建指南：TypeDoc 生成引擎 API 手册、Doxygen 生成平台参考
【免费下载链接】GDevelop🎮 Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop
本指南以 GDevelop 仓库中的 GDJS/docs/README.md 为核心，讲解如何从源码在本机生成 GDJS 的两套官方文档：由 TypeDoc 从 TypeScript 引擎源码生成的GDJS Runtime（游戏引擎）文档，以及由 Doxygen 从 C++ 平台代码生成的GDJS Platform（IDE 侧）文档。读完本文，你将掌握完整的依赖安装、命令执行、输出目录定位与配置项含义，并能理解文档内容与gdjs运行时命名空间的源码对应关系。
GDJS 双引擎架构与两套文档的定位
GDevelop 的 HTML5/JavaScript 游戏平台（GDJS）在 GDJS/README.md 中被明确划分为两个组成部分：
- GDJS Runtime（游戏引擎）：位于
GDJS/Runtime目录，是用 TypeScript 编写的、真正在浏览器中驱动游戏运行的引擎，即玩家设备上执行的那部分代码。 - GDJS Platform（IDE 平台）：位于
GDJS/GDJS（C++ 目录）及GDJS/Extensions等目录，负责把 GDevelop 编辑器中的事件（Events）转译为 JavaScript、以及导出游戏等 IDE 侧功能。
与之对应，文档也分成两套独立产物，分别由两种文档工具生成：
| 文档产物 | 服务对象 | 生成工具 | 输入源码 | 配置依据 |
|---|---|---|---|---|
| GDJS Runtime 文档 | 游戏引擎（TS 运行时） | TypeDoc | GDJS/Runtime/**（入口 GDJS/Runtime/gd.ts） | GDJS/docs/typedoc.json |
| GDJS Platform 文档 | IDE 平台（C++） | Doxygen | GDJS/GDJS/**（C++ 源码） | GDJS/docs/doxyfile |
注意命名细节：Runtime 文档对应在线站点的 "GDJS Runtime Documentation"，Platform 文档对应 "GDJS Documentation"。这一对应关系与两份配置文件中的输出路径设置一致（见下文），是理解构建流程的关键。
生成 GDJS Runtime（游戏引擎）文档：TypeDoc 实操
前置条件与命令
生成引擎文档的前提是仓库根目录GDJS下已经安装好 Node.js 依赖（TypeDoc 及 TypeScript 相关工具链已在 GDJS/package.json 的devDependencies中声明）。完整流程为：
cd <GDevelop repository>/GDJS npm install npm run generate-doc其中npm run generate-doc实际执行的是 GDJS/package.json 中定义的脚本：
"generate-doc": "typedoc --options docs/typedoc.json --plugin typedoc-plugin-reference-excluder"即通过--options指定 GDJS/docs/typedoc.json 作为 TypeDoc 配置，并加载typedoc-plugin-reference-excluder插件（该插件用于在生成时剔除特定引用，插件补丁见 GDJS/patches）。
输出位置
按照 GDJS/docs/typedoc.json 中的out字段：
"out": "../../docs/GDJS Runtime Documentation"TypeDoc 以GDJS/docs目录为基准向上两级，将 HTML 文档输出到仓库根目录的docs/GDJS Runtime Documentation。注意：此处 GDJS/docs/README.md 正文中“输出到docs/GDJS Documentation”的描述与typedoc.json实际配置相反，构建时应以配置文件为准。
typedoc.json 关键配置解读
GDJS/docs/typedoc.json 完整控制了 Runtime 文档的内容边界与形态，核心项如下：
entryPoints与entryPointStrategy：入口指向../Runtime/gd.ts，策略为expand，即从入口文件出发展开其 import 依赖，把整个运行时类库纳入文档。externalPattern：排除Runtime/Cordova/、Runtime/Electron/、Runtime/FacebookInstantGames/与tests/，这些平台适配目录和测试代码不进入 API 手册。exclude/excludeExternals/excludeInternal：进一步剔除GDJS/tests/**、外部库与标记为@internal的符号。name与readme：文档标题为 “GDevelop JavaScript game engine”，首页内容直接复用 GDJS/docs/typedoc-main-page.md。validation.invalidLink：开启链接校验，确保文档中的{@link gdjs.RuntimeScene}等交叉引用均能解析到真实符号。excludedFunctionOrMethod：跳过以下划线开头的内部函数（如_unregisterCallback），保持 API 手册面向使用者而非引擎开发者。gaID：内置 Google Analytics 统计 ID，用于官方在线部署时的访问统计。
文档首页与核心类指引
生成文档的首页（GDJS/docs/typedoc-main-page.md）为使用者在游戏中编写 JavaScript 提供了快速入口：在 GDevelop 中插入“JavaScript 事件”即可直接调用引擎，文档重点推荐四类核心对象：
gdjs.RuntimeScene：与场景交互（场景加载、卸载、暂停、事件执行前后的回调均围绕它展开）。gdjs.RuntimeObject：场景中对象实例的基类。gdjs.RuntimeBehavior：附着在对象上的行为基类。gdjs.Variable及容器gdjs.VariablesContainer：存储游戏、场景与对象上的变量。
这些类的入口都集中在gdjs命名空间下——GDJS/Runtime/gd.ts 开头即声明 “Thegdjsnamespace contains all classes and objects of the game engine”，文档中展示的注册机制（如gdjs.registerObject、gdjs.registerBehavior）与场景生命周期回调（registerRuntimeSceneLoadedCallback、registerRuntimeScenePreEventsCallback、registerRuntimeScenePostEventsCallback等）都能在 GDJS/Runtime/gd.ts 中找到对应源码，是理解“文档即源码注释”的最佳样例。
生成 GDJS Platform（IDE 侧）文档：Doxygen 实操
前置条件与命令
Platform 文档面向 C++ 平台代码，需先安装 Doxygen，随后在GDJS/docs目录直接执行：
cd <GDevelop repository>/GDJS/docs doxygenDoxygen 会自动读取当前目录下的 GDJS/docs/doxyfile（Doxyfile 1.8.4 格式，UTF-8 编码）并完成解析、生成。
输出位置
doxyfile 第 55 行指定：
OUTPUT_DIRECTORY = "../../docs/GDJS Documentation"即以GDJS/docs为基准向上两级，输出到仓库根目录的docs/GDJS Documentation，HTML_OUTPUT = .表示 HTML 直接生成在该目录根部（index.html即文档首页）。
doxyfile 关键配置解读
这份近 1900 行的配置是 Platform 文档行为的完整契约，与构建结果直接相关的核心项包括：
- 项目标识：
PROJECT_NAME = "GDevelop JS Platform"，PROJECT_BRIEF = "Platform for developing HTML5/Javascript based games with GDevelop"，Logo 使用images/glogo.png。 - 输入范围：
INPUT = "../GDJS"（即GDJS/GDJS的 C++ 目录），RECURSIVE = YES递归收录子目录；EXCLUDE = "../GDJS/mongoose"剔除嵌入的第三方 HTTP 库。 - 预处理控制：
PREDEFINED = GD_IDE_ONLY=1 WXUNUSED()=，配合MACRO_EXPANSION = YES与EXPAND_ONLY_PREDEF = YES，只展开这两个宏，保证只暴露 IDE 场景（GD_IDE_ONLY）相关代码，并清理 wxWidgets 风格的未使用参数宏。 - 输出形态：仅生成 HTML（
GENERATE_HTML = YES），关闭 LaTeX/RTF/Man/XML 输出以节省构建时间；SEARCHENGINE = YES启用客户端搜索。 - 页面与样式：
HTML_EXTRA_STYLESHEET = DoxygenStyle.css定制样式；HTML_EXTRA_FILES列出 16 张随文档发布的图片（安装编译器、新建工程、CMake 使用等教程配图）；MARKDOWN_SUPPORT = YES允许在注释中混合使用 Markdown。 - 图与索引：
HAVE_DOT = NO（未强制依赖 Graphviz），ALPHABETICAL_INDEX = YES生成字母索引（COLS_IN_ALPHA_INDEX = 5），GENERATE_TREEVIEW = NO。
文档内容的覆盖范围
与 TypeDoc 面向gdjs命名空间不同，Doxygen 文档描述的是 IDE 侧的 C++ 平台层，即 GDJS/README.md 所称的 “Exporter and classes doing transpilation from events to JavaScript”。它涵盖场景与对象元数据、代码生成器（GDJS/GDJS/Events、GDJS/GDJS/Extensions等目录）、导出流程等，是开发自定义扩展与平台集成的参考资料。
两种文档工具的分工与选择
从 GDJS/README.md 的分工描述出发，可以总结出两套文档各自的服务对象：
- 想在游戏中使用 JavaScript、或为游戏编写自定义扩展的游戏开发者，查阅TypeDoc 生成的 Runtime 文档，重点关注
gdjs.RuntimeScene、gdjs.RuntimeObject、gdjs.RuntimeBehavior、gdjs.Variable等类，以及 GDJS/docs/typedoc-main-page.md 首页提供的 JavaScript 事件用法。 - 想修改引擎本身、参与 GDJS 平台 C++ 层开发（事件转译、导出器）的引擎/平台开发者，查阅Doxygen 生成的 Platform 文档，同时可结合 GDJS/README.md 中的开发指引（
npm run build、npm run check-types、测试入口在GDJS/tests）深入源码。
两套文档的源码注释源头也可以对照阅读：Runtime 侧的类型注释集中在 GDJS/Runtime 目录，Platform 侧的 Doxygen 注释分布在GDJS/GDJS各 C++ 头文件中。
构建后的验证与常见注意点
- 确认依赖齐全：Runtime 文档生成依赖 npm 依赖安装成功（
npm install）；Platform 文档生成依赖系统已安装 Doxygen，且doxygen命令在PATH中。 - 核对输出目录：TypeDoc 输出在
docs/GDJS Runtime Documentation，Doxygen 输出在docs/GDJS Documentation，二者均以仓库根docs/为共同目的地，若目录已存在会被增量覆盖。 - 注意 README 与配置的出入：
GDJS/docs/README.md正文中两处输出路径描述与typedoc.json/doxyfile中的实际out/OUTPUT_DIRECTORY互相调换，以配置文件为准可避免找错目录。 - 链接校验：TypeDoc 配置开启了
validation.invalidLink，若源码中{@link}引用的符号缺失，生成过程会给出校验提示，是检查引擎文档注释完整性的有效手段。 - 区分两套产物：二者同名前缀（GDJS Documentation / GDJS Runtime Documentation）极易混淆，发布或部署在线文档前先确认 HTML 首页（
index.html）内容与预期工具一致。
【免费下载链接】GDevelop🎮 Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
