flutter-flame-3d

一个面向新手的 flame_3d 技能，帮助 Codex / AI coding agent 在 Flutter 中创建、讲解和调试 Flame 3D 项目。

这个仓库包含：

• flutter-flame-3d/
  • 技能本体
• dist/flutter-flame-3d.skill
  • 已打包好的分发文件

这个技能能做什么

• 从零生成一个最小可运行的 flame_3d 示例
• 用中文讲解 World3D、相机、灯光、primitive mesh、模型加载
• 参考官方 example 做“减法”，抽出适合新手的结构
• 处理常见问题：
  • 空白画面
  • 黑屏或物体过暗
  • 贴图不显示
  • .glb 模型不显示
  • Flutter GPU / Impeller 前置配置

目录说明

flutter-flame-3d/
├── README.md
├── dist/
│   └── flutter-flame-3d.skill
└── flutter-flame-3d/
    ├── SKILL.md
    ├── references/
    │   ├── beginner-quickstart.md
    │   ├── chinese-guide.md
    │   ├── official-patterns.md
    │   └── task-recipes.md
    └── assets/
        └── minimal-demo/

怎么使用

方式 1：直接使用技能目录

把 flutter-flame-3d/ 这个目录放到你的技能目录里即可。

例如：

cp -R flutter-flame-3d ~/.codex/skills/

如果你的环境不是 ~/.codex/skills，就复制到你自己的 skills 目录。

方式 2：使用打包好的 .skill 文件

仓库里已经包含现成包：

dist/flutter-flame-3d.skill

把这个文件导入到支持 .skill 的环境里即可。

触发这个技能的典型说法

下面这些请求适合触发这个技能：

• “帮我写一个 Flutter Flame 3D 入门示例”
• “用 flame_3d 做一个最小 3D 场景”
• “解释一下 World3D 和 CameraComponent3D”
• “为什么 flame_3d 画面是空白的”
• “帮我把官方 flame_3d example 精简成新手版”
• “帮我在 flame_3d 里加载 glb 模型”

技能内部内容

• SKILL.md
  • 技能入口，定义工作流、常见请求处理方式和默认交付标准
• references/beginner-quickstart.md
  • 最小可运行示例和基础前置配置
• references/chinese-guide.md
  • 中文新手讲解稿
• references/official-patterns.md
  • 官方 README、example、API 入口和常见坑位整理
• references/task-recipes.md
  • 常见任务配方：贴图、模型、跟随相机、简化官方 example
• assets/minimal-demo/
  • 一个可直接复用的最小 demo 模板

推荐使用方式

如果你是第一次用：

1. 先看 references/beginner-quickstart.md
2. 跑通最小 cube 场景
3. 再看 references/task-recipes.md
4. 最后才去碰 .glb 模型和更复杂的相机逻辑

如果你要面向中文新手教学：

1. 优先看 references/chinese-guide.md
2. 一次只讲一个概念
3. 先给完整可运行代码，再解释原因

上游来源

• Flame 仓库：
  • https://github.com/flame-engine/flame
• flame_3d 包目录：
  • https://github.com/flame-engine/flame/tree/main/packages/flame_3d

备注

flame_3d 当前仍然是实验性包，适合学习、原型和演示，不建议在没有额外验证的情况下直接作为生产方案。