Cocos Creator 引擎模块体系解析Public Modules、cc 合成模块与模块扩展完整指南【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine本指南以 docs/contribution/modules.md 为核心系统讲解 Cocos Creator 引擎cocos-engine的模块化设计/exports下的公共模块如何界定用户可见的 API 边界、cc合成模块的生成原理、Editor-only 模块的定位以及从新增一个导出到创建一个全新公共模块的完整操作流程。阅读本文后你将掌握引擎 API 暴露机制、cc.config.json 中 feature 配置的每个字段含义以及如何为引擎添加新模块并使其在 Cocos Creator 编辑器的项目设置中可被用户选择。模块体系总览公共模块、私有模块与 Editor-only 模块Cocos Creator 引擎的模块体系分为三层边界非常清晰层级目录可见性公共模块Public modules/exports对用户可见用户代码可直接import { xxx } from cc私有模块Private modules/cocos、/pal等仅引擎内部可见即使被公共模块传递引用也不会暴露给用户Editor-only 模块/editor/exports仅对 Cocos Creator 编辑器可见属于编辑器与引擎的桥接层只有公共模块导出的绑定binding对用户可见。这是引擎 API 面public surface的唯一出口用户在任何构建产物中能访问到的符号都必须经由某个公共模块的export语句传递出来。其他模块——即使被公共模块直接或间接导入——都属于引擎内部实现细节不在对外 API 契约之内。从目录结构看仓库根目录的 exports/ 下目前有 47 个公共模块文件覆盖 2D/3D 渲染、动画、物理、音视频、粒子、UI、tween、spine、terrain 等引擎全部能力域而 cocos/ 下的全部业务实现、pal/ 下的平台抽象层都处于私有边界之内。cc合成模块如何汇聚所有公共模块对用户而言最常见的导入语句是import { Node } from cc。这里的cc并不是仓库中真实存在的某个.ts文件而是一个人工合成的模块artificial module它把用户选中的多个公共模块的导出汇总到一起/* The source of module cc, for explanation purpose only */ for (const module in selected-modules) { export * from module; }关键点在于selected-modules的选取cc并不是无条件导出全部 47 个公共模块而是只导出用户在项目设置中选定启用的那些公共模块。这意味着不同项目构建出的cc模块内容可以不同未启用的模块对应的代码可以通过引擎构建流程被剔除实现按需打包、控制产物体积。引擎内部对该机制还有一个重要佐证在 cc.config.json 的constants区段中定义了USE_3D、USE_UI_SKEW、USE_XR、USE_SORTING_2D等开关常量它们正是由用户勾选对应 feature 后注入的构建期常量用于在源码中控制相关代码路径的启用与否。仅对编辑器公开的模块Modules public only to Editor与面向用户的公共模块并列引擎还维护了第二类对外模块/editor/exports目录下的模块仅对 Cocos Creator 编辑器公开。editor/exports/ 目录下目前包含 15 个模块例如2d-misc.ts、animation-clip-migration.ts、material.ts、custom-pipeline.ts、populate-internal-constants.ts等。这些模块服务于编辑器的资产处理、数据迁移、管线配置等引擎与编辑器协作的场景并不会进入最终用户的cc命名空间。例如 editor/exports/2d-misc.ts 仅暴露了一个earcut工具函数export { earcut } from ../../cocos/2d/assembler/graphics/webgl/earcut;从 cc.config.json 的includes字段可以进一步印证两类模块的边界该字段将以下目录纳入引擎编译输入./exports/**/*.{ts,js,json}, ./editor/exports/**/*.{ts,js,json}, ./cocos/**/*.{ts,js,json}, ./pal/**/*.{ts,js,json}向公共模块添加导出Add module export当需要向用户暴露一个新 API 时核心规则只有一条把它直接或通过传递导出transitively export进任意一个公共模块。原文档以Mesh为例演示了两种做法。需要说明的是当前仓库中Mesh的实际声明位置是 cocos/3d/assets/mesh.ts并通过 cocos/3d/assets/index.ts 中的export { Mesh } from ./mesh;对外暴露下面的示例沿用原文档的思路但路径以仓库实际结构为准。方式一在公共模块中直接导出假设要把某个类暴露到/exports/base模块直接在该模块文件中追加一行即可// At /exports/base.ts export { Mesh } from ../cocos/3d/assets/mesh;方式二在引擎内部模块中导出由公共模块传递由于 exports/base.ts 通过export * from ../cocos/core导出cocos/core而cocos/core又会继续向下传递导出见 cocos/core/index.ts 中连续的export *语句因此你也可以把新符号直接挂在链路中任意一层的模块入口上让传递导出机制把它带到公共模块// At /cocos/core/assets/index.ts export { Mesh } from ./mesh;两种方式选其一的判断标准是尽量把导出位置放在语义归属正确的模块层避免在exports顶层直接 re-export 导致入口文件膨胀。从 exports/base.ts 的实现可以看到引擎自身的做法——顶层公共模块只做粗粒度的聚合export * from ../cocos/core、export * from ../cocos/rendering等具体符号的细化导出都在下层模块完成export * from ../cocos/core; export * from ../cocos/rendering; export * from ../cocos/scene-graph; export * from ../cocos/misc; export * from ../cocos/game; export * from ../cocos/asset/assets; export * from ../cocos/asset/asset-manager; export * from ../cocos/input/types; export * from ../cocos/input;以 exports/2d.ts 为代表的轻量公共模块则只有一个透传语句export * from ../cocos/2d;全部符号都来自cocos/2d模块树。创建全新公共模块Create public module如果新 API 不适合放进任何现有公共模块就需要创建一个全新的公共模块。创建过程分两步在/exports下新增模块文件这就是创建公共模块的全部源码动作通过两份配置文件把模块接入构建与编辑器 UI具体包括在 cc.config.json 的features数组中新增一个元素。feature 代表一个可能被用户勾选的功能集其modules字段指明该 feature 启用时应包含哪些公共模块每个元素是公共模块不带扩展名的文件名。该 JSON 文件已关联 schema 文件 cc.config.schema.json所有可配置字段及其约束都在其中定义在 render-config.json 中配置该 feature 在编辑器中的展示形态名称、描述、默认值、依赖关系等其关联的 schema 文件是 editor/engine-features/schema.json。下面结合 schema 定义逐字段详解两份配置。cc.config.json 的 Feature 字段详解根据 cc.config.schema.json 中Feature的定义每个 feature 支持以下字段字段类型必填含义modulesstring[]是该 feature 启用时纳入的公共模块 ID。模块 ID 即其在/exports/下的无扩展名相对路径dependentAssetsstring[]否该 feature 依赖的资源 UUID 列表dependentModulesstring[]否该 feature 依赖的模块 ID 列表模块级依赖dependentScriptsstring[]否该 feature 依赖的脚本 UUID 列表intrinsicFlagsobject否启用该 feature 时注入的构建期标志值是布尔值isNativeOnlyboolean否是否为原生平台独占 feature默认falseoverrideConstantsobject否启用时覆盖的构建期常量值可为 number/boolean被覆盖的常量必须已在cc.config.json的constants区段中定义实际配置示例来自 cc.config.jsonphysics-physx: { modules: [physics-physx, physics-framework], dependentAssets: [ba21476f-2866-4f81-9c4d-6e359316e448] }, ui-skew: { modules: [ui-skew], overrideConstants: { USE_UI_SKEW: true }, dependentModules: [2d] }, skeletal-animation: { modules: [animation, skeletal-animation] }可以观察到几个典型模式复合 featurephysics-physx同时包含两个公共模块物理后端 物理框架skeletal-animation同时包含动画与骨骼动画两个模块常量覆盖ui-skew通过overrideConstants把USE_UI_SKEW置为true3d把USE_3D置为true这些常量会在constants区段参与构建期求值依赖声明rich-text、mask、graphics等都声明dependentModules: [2d]保证 2D 基础模块一定被包含纯资产/纯脚本 feature如occlusion-query、debug-renderer、custom-pipeline-builtin-scripts的modules为空数组仅通过dependentAssets/dependentScripts/intrinsicFlags发挥作用。schema.json还要求 feature 对象additionalProperties: false即不接受任何未在 schema 中声明的字段配置拼写错误会在编译期/校验阶段被拦截。render-config.json编辑器端的展示与行为配置render-config.json 控制 feature 在 Cocos Creator 编辑器项目设置中的呈现方式。根据其 schemaeditor/engine-features/schema.json与 TypeScript 类型定义editor/engine-features/types.tsIFeatureItem支持以下核心字段字段类型含义label/descriptionstring显示名称与悬停提示支持 i18n 格式如i18n:ENGINE.features.core.labeldefaultboolean是否默认启用readonlyboolean为true时用户无法在项目设置中修改开关hiddenboolean为true时不在项目设置中显示如meshopt、render-pipelinerequiredboolean必选模块旧项目升级后会强制选中否则保持未选中categorystring归属分组对应同级categories字段中声明的目录graphics / 2d / 3d / animation / networkdependenciesstring[]依赖的其他 feature勾选本模块时依赖自动勾选反向亦然enginePluginboolean是否默认打包进各小游戏引擎插件包体较大的模块默认不打包envConditionstring限定生效环境支持宏组合如$HTML5 || $MINIGAME || $RUNTIME_BASED为空则任意环境可用fallbackstring环境不满足envCondition时自动回退到的 feature 名仅配了envCondition才有效isNativeModuleboolean是否为原生模块wasm/asmjs勾选后构建面板显示原生代码打包模式配置cmakeConfigstring原生端对应的 CMake 宏名如USE_PHYSICS_PHYSX、USE_SPINE_3_8选择结果会写入原生工程的 cmake 配置flagsobject勾选该模块后可展开的附加配置项ui-type支持checkbox/select如各物理/骨骼库的LOAD_*_MANUALLY手动加载开关实际示例physicsfeature 是一个分组型 featureIFeatureGroup通过options收纳physics-ammo、physics-cannon、physics-physx、physics-builtin四个可互斥选择的物理后端并为 ammo 与 physx 各配置了一个LOAD_*_MANUALLY复选开关physics: { label: i18n:ENGINE.features.physics.label, description: i18n:ENGINE.features.physics.description, category: 3d, dependencies: [3d], options: { physics-ammo: { default: true, isNativeModule: true, flags: { LOAD_BULLET_MANUALLY: { label: i18n:ENGINE.features.flags.bullet.loadManual.label, description: i18n:ENGINE.features.flags.bullet.loadManual.description, default: false, ui-type: checkbox } } } } }再如physics-2d-box2d-jsb展示了envCondition与fallback的组合用法——该模块只在$NATIVE环境出现非原生环境自动回退到physics-2d-box2d-wasmphysics-2d-box2d-jsb: { isNativeModule: true, cmakeConfig: USE_BOX2D_JSB, label: i18n:ENGINE.features.physics_2d_box2d_jsb.label, description: i18n:ENGINE.features.physics_2d_box2d_jsb.description, envCondition: $NATIVE, fallback: physics-2d-box2d-wasm }schema.json与types.ts之间由 editor/engine-features/generate-schema.js 维护一致性——它通过typescript-json-schema工具从types.ts的ModuleRenderConfig接口自动生成schema.json因此修改types.ts后重新运行该脚本即可同步 schema。延伸moduleOverrides 与构建期常量如何支撑模块化在 cc.config.json 中与features并列的还有两个对模块化体系至关重要的配置区段理解它们有助于把模块与构建期裁剪串成完整闭环moduleOverrides模块重定向根据test表达式匹配构建环境把某个模块/文件重定向到另一实现。最典型的是平台适配{ test: context.buildTimeConstants.HTML5, isVirtualModule: true, overrides: { pal/minigame: pal/minigame/non-minigame.ts, pal/audio: pal/audio/web/player.ts, pal/system-info: pal/system-info/web/system-info.ts } }以及原生平台把渲染、场景图、资产等模块替换为 JSB 实现如cocos/rendering/index.ts: cocos/rendering/index.jsb.ts、Spine 版本切换SPINE_3_8/SPINE_4_2各自映射不同的 spine 库实现等。isVirtualModule: true表示被替换的目标是虚拟模块入口test表达式可引用context.buildTimeConstants中定义的各类常量。constants构建期常量定义了HTML5、NATIVE、MINIGAME、RUNTIME_BASED、EDITOR、BUILD、DEV、DEBUG、JSB等平台与环境判定常量以及USE_3D、USE_XR等功能开关。常量值支持eval()表达式例如NATIVE的值是$ANDROID || $IOS || $MAC || ...的布尔表达式也支持dynamic: true表示在编辑器/预览/测试环境中运行时动态判定以及ccGlobal: true表示同时导出为全局CC_XXXX常量兼容 Cocos 2.x。moduleOverrides的test与 feature 的intrinsicFlags/overrideConstants正是这些常量在模块选择层面的应用入口。此外引擎还通过treeShake.noSideEffectFiles声明无副作用文件列表、optimizeDecorators声明构建期可优化的装饰器集合fieldDecorators与editorDecorators这些机制与模块体系共同构成了引擎按需编译 精细裁剪的完整链路。小结Cocos Creator 引擎的模块体系可以概括为一条清晰的责任链/exports是用户可见性的唯一判定依据——只有公共模块的导出才进入cccc是聚合用户选定公共模块的合成模块配合 feature 配置实现按需打包/editor/exports提供编辑器专用 API与用户 API 面完全隔离暴露新 API 只需就近导出优先在语义归属正确的下层模块导出让传递导出机制完成上浮创建新公共模块 新增exports文件 配置cc.config.json的features 配置render-config.json的编辑器展示schema 文件cc.config.schema.json、editor/engine-features/schema.json保证两份配置的合法性底层的moduleOverrides与constants机制则为模块在不同平台、不同功能开关下的精准裁剪提供了实现保障。【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考