https://github.com/oahc09/cocosairjs/ （欢迎支持共同完善）
最近，我在做 CocosAirJS：一套用 JavaScript/TypeScript 制作网页小游戏、互动特效和 3D 展示的运行时与开发工具。
它基于 Cocos 的 Web/TypeScript Runtime，把场景、材质、模型、动画、UI 和交互组织成一套 Code First 开发方式。开发者可以直接用 JavaScript 或 TypeScript 构建浏览器里的 2D/3D 内容；使用 AI Agent 开发时，也有对应的类型、示例、Skills 和调试工具可用。
我想做的事情很具体： 让一个交互想法，能够沿着代码、运行、观察、修改这条路径，逐步变成可操作、可维护的作品。
这样的作品可以是一个小游戏、一张会响应鼠标的材质卡片、一个能够切换外观的 3D 产品展示，也可以是一段由模型、光照、Shader 和 UI 共同组成的网页体验。
为什么做 CocosAirJS
做交互内容时，第一个画面通常只是开始。
一个模型显示出来以后，还需要旋转和缩放、点击选中、播放动画、切换材质、展示信息。一个游戏画出棋盘以后，还需要输入、规则、状态、音效、结算与重开。一个 Shader 效果调好以后，还要处理画布尺寸、资源加载、UI 配合和退出时的释放。
我希望这些工作能够放在一条连贯的开发路径里。
这也是 CocosAirJS 选择 Cocos Web 运行时作为技术基础的原因：它已有场景图、组件、2D/UI、动画、物理等系统。CocosAirJS 的工作，是围绕 Web 与代码开发重新组织这些能力，让开发者直接创建和操作运行时对象，并补充应用启动、资源加载、交互辅助和诊断工具。
熟悉 Cocos 的开发者，可以继续使用 Scene、Node、Component 这些概念；熟悉前端的开发者，可以从模块、类型和源码进入项目。
Code First 在这里意味着什么
在 CocosAirJS 中，可以直接通过代码创建 Scene、Node、Camera、Mesh、Material 和 Animation。场景结构与运行逻辑由源码表达，启动入口是 createAirApp() 。
这条开发路径不要求安装 [Cocos Creator]，也不要求先制作编辑器场景、Prefab 或经过编辑器资产导入流程。已有的 glTF/GLB 模型可以在运行时加载，程序化几何、内置材质和 UI 也可以直接创建。
工程的使用方式尽量贴近 Web 开发：
- 在 TypeScript/JavaScript 应用中依赖 SDK，配合 Vite 等工具开发。
- 将构建后的 ESM 模块放进网页，通过 import map 使用。
- 在引擎仓库中运行开发服务器，修改示例、观察画面并继续迭代。
对于普通前端应用，构建后的页面、脚本和资产可以交给静态服务器。应用运行不要求携带整份引擎源码；如果应用需要账号、联网服务或数据存储，再由应用自行接入相应服务。
我看重这种组织方式带来的可读性：场景怎么创建、资源从哪里加载、交互由谁处理、退出时释放什么，都尽量能在代码里找到明确的位置。
现在可以做出哪些内容
围绕 CocosAirJS，我正在把单项能力串成有完整操作过程的示例。当前示例目录已经覆盖下面这些方向。
| 内容方向 | 仓库中的代表案例 | 示例覆盖的开发内容 |
|---|---|---|
| 经典小游戏 | 俄罗斯方块、三消、坦克对战、横版动作射击、收集躲避 | 输入、玩法规则、计分、胜负、暂停与重开，以及 UI 和音效的配合 |
| 3D 产品展示 | Product Viewer | 模型加载、旋转缩放、选取部件、材质切换、信息面板和模型替换 |
| 角色与模型交互 | 角色展示、多实例模型交互 | glTF/GLB、骨骼和 Morph 动画、独立播放状态、拾取与反馈 |
| 材质与互动特效 | 全息效果、镭射卡、液态金属、薄膜、玻璃、溶解、光标轨迹 | Shader、纹理、材质参数与输入响应 |
| 氛围与程序化场景 | 霓虹夜城、夜间篝火、星空场景 | 场景组织、光照、雾、运动与颜色控制 |
| 多通道渲染 | 水面、HDR 色彩流程、渲染合成 | 离屏相机、颜色与深度纹理、采样、合成以及尺寸变化 |
例如，产品查看器的意义并不止于展示一个模型。它需要处理加载失败后的重试、模型被选中后的反馈、切换材质后的状态，以及换一个模型时对旧资源的释放。
这些步骤连起来以后，示例才更接近开发者实际会遇到的项目。
上述案例是引擎使用参考；开发者可以据此构建自己的产品展示、互动网页、可视化教学或游戏原型。具体产品的内容、玩法质量和业务系统仍由应用负责。
从渲染到交互的能力
场景、几何、材质与光照。 CocosAirJS 保留场景图和组件体系，提供相机、灯光、网格、材质、纹理、程序化几何等基础。可以用内置材质搭建画面，也可以通过 EffectAsset 与自定义 Shader 实现特定视觉效果。glTF 材质路径覆盖 PBR 以及已登记的 clearcoat、anisotropy、iridescence 等扩展，分别用于清漆、各向异性和虹彩等表现。
离屏渲染与屏幕效果。 针对需要多个渲染步骤的效果，项目提供渲染目标、颜色与深度附件、MSAA resolve、屏幕 Pass 等入口，并包含 Bloom、暗角等实现。这些能力可以用于水面、发光、画面合成等效果；所用格式与组合需要匹配实际设备能力。
模型与动画。 glTF/GLB 可以在运行时加载为引擎的网格、材质、骨骼和动画对象，支持骨骼蒙皮、Morph 与动画播放控制，也提供 Tween 等补间能力。压缩模型和纹理有相应的 decoder/provider 接入路径，使用 Draco、Meshopt 或 KTX2 等资产时，需要按部署说明准备解码或转码资源。
2D、UI 与文字。 项目包含 Sprite、Label、布局、按钮、Mask、Graphics、TiledMap 和 2D 粒子等能力，也在持续完善代码创建 UI 的辅助接口。文字、图标、打字机效果、像素对齐、图形绘制和纹理显示，可以与 3D 场景放在同一个应用里组织。
页面与渲染内容协同。 对适合使用普通网页控件的部分，可以通过 DOM overlay 与场景 UI 协作；对需要进入纹理流程的图形，可以采用对应的纹理与栅格化接口。这让输入框、说明面板和渲染内容可以各自使用合适的表达方式。
输入、媒体与物理。 Web 输入、音频和视频能力为内容增加操作与反馈。2D 物理使用纯 JavaScript Box2D；3D 可以选择 Cannon 进行刚体模拟，默认 builtin 后端提供离散碰撞检测。做一个有操作、有规则、有反馈的小游戏时，这些能力能够参与同一套运行流程。
资源与生命周期。 模型共享、实例销毁、场景切换、重新进入、事件监听与资源释放，也都属于工程需要处理的内容。CocosAirJS 为这些工作提供接口和检查工具，帮助开发者观察资源归属与运行状态。
围绕引擎还有哪些配套
我希望开发者拿到 CocosAirJS 后，能够从一个明确的入口开始，再逐步找到所需的知识和工具。
| 配套内容 | 开发时的作用 |
|---|---|
| Runtime 与 SDK | 提供 ESM 构建和 TypeScript 类型，接入应用工程或普通网页 |
| 中文手册与 API 资料 | 解释场景、材质、动画、UI、输入、物理与资源的使用方式及边界 |
| Examples Gallery | 按分类、效果和 API 查找示例，查看源码、学习目标与预期表现 |
| Agent Skills | 按任务选择相关子系统的知识、代码入口和验证方法 |
| DevTools 与运行时检查 | 由仓库开发环境提供，查看场景树、节点、资源、错误、性能摘要和当前画面 |
| 验证与对照实验 | 检查类型、构建、浏览器行为、资源生命周期，并研究开发任务中的问题 |
当前 Gallery 清单收录 187 个示例条目 ；Skills 目录组织了 22 个技能入口，包括统一路由与专项技能 。这些数字表示目录规模，示例内容和验证记录会随版本更新。
我更希望它们形成一种顺畅的使用方式：先找到接近目标的效果，再阅读实现，查到实际使用的 API，最后把自己的改动放回运行环境中检查。
为什么专门面向 AI Agent
AI Agent 参与图形项目时，需要面对几类具体问题：如何找到正确 API，如何组织场景与资源，如何理解运行错误，以及如何确认画面和交互符合要求。
CocosAirJS 从这些环节准备开发材料。
首先，场景和行为直接由代码表达。Agent 可以围绕源码进行创建、修改和修复。
其次，TypeScript 类型、分系统 Skills、示例和手册提供了相互关联的知识入口。任务涉及模型、UI、物理或渲染时，可以定位到相应的说明与实现。
再次，开发期工具可以观察实际运行状态。场景树中有没有目标节点，模型和材质是否绑定，资源是否已经销毁，运行过程中出现了什么错误，都有相应的检查路径。需要看画面时，也有当前帧截图能力。
这里的 Agent 调试工具由引擎仓库的开发服务器提供，在同一个开发页面内显式启用，不随默认 SDK 分发。Skills 需要按宿主的使用方式接入。它们为 Agent 提供工程材料和反馈接口，最终效果仍需要运行、观察和验证。
我希望“对 Agent 友好”能够落实到具体开发动作：有入口可查，有状态可看，有问题可定位，有结果可验证。
用真实项目反过来改进引擎
除了引擎本身，我还建立了配套的双引擎对照实验项目。
它尝试在 Agent、任务、预算和资产等条件可比的情况下，观察同类场景在不同引擎中的完成情况、开发成本和失败原因，也关注补充文档、示例以后会发生什么变化。
这些问题对 CocosAirJS 很有价值：某个效果难以完成，是缺少必要能力，还是接口表达不清？一个模型能加载却显示异常，是资产、材质、颜色空间还是运行配置的问题？反复调试的成本，有多少可以通过更好的文档和工具减少？
实验发现可以继续回到引擎、示例和 Skills 中，成为下一次改进的输入。实验设计和阶段性记录放在公开的配套仓库中。
适合什么样的开发者
如果你熟悉 JavaScript/TypeScript，希望在网页里加入模型、动画、特效或游戏玩法，CocosAirJS 提供了一条可以直接从代码进入的路径。
如果你熟悉 Cocos，希望保留场景、组件与运行时的开发习惯，同时尝试更直接的 Web 工程组织方式，也可以关注这个项目。
如果你正在使用 AI Agent 做交互原型，希望生成过程能够连接类型、示例、错误信息和画面检查，CocosAirJS 的工具与实验方法可能会带来参考。
对图形开发者而言，它也可以作为材质、Shader、模型加载和多通道效果的实验环境。
当前范围与接下来的方向
当前默认渲染后端是 WebGL2 ，主运行时面向浏览器。桌面 WebGPU 实验后端 已经接入，需要显式选择，支持范围按对应验收记录说明。
仓库还提供了独立的 Spark 集成，用于探索 3D Gaussian Splatting 。它按需构建，复用主引擎，当前属于仓库内的可选探索模块，不进入默认 SDK。
原生平台、小游戏平台和 Creator 编辑器不在这套 Web 运行时的交付范围。项目自有代码采用 MIT，内嵌第三方组件遵循各自许可，具体条件以项目许可说明为准。
接下来，我会继续围绕真实应用完善接口、示例、文档与验证，把开发中反复出现的问题逐个处理清楚，也会持续分享具体作品与实现过程。
CocosAirJS 想提供的，是一套让开发者和 AI Agent 都能从代码出发，把想法做成可交互 Web 内容的运行时与开发工具。
如果你正在做类似的小游戏、互动页面、3D 展示或图形实验，欢迎交流：你最想先做哪一种内容，开发过程中最容易卡在哪一步？