Communitygithub.com

3D游戏资产

当3D游戏需要具体、可识别的GLB资产,而非仅基本几何体时使用此技能。本技能拥有端到端工作流:选择路线、生成小型聚焦资产集、写入/读取asset_manifest.json,并将GLB文件接入游戏并包含备用方案。

3D游戏资产 是什么?

该技能专为AI智能体(如Claude Code、Cursor)设计,用于在3D游戏开发中自动生成和管理GLB格式的游戏资产。它支持两种主要生成路线:Tripo(快速文本到模型)和Gemini参考图(通过参考图像控制角色外观),并包含自动备用方案以保持游戏可玩性。技能能根据游戏提示自动识别关键实体(如玩家、敌人、收集品)并生成1-3个核心资产,同时管理asset_manifest.json清单并集成运行时类。它的核心优势是自动化的端到端工作流、内建错误处理(如API不可用、余额不足时自动降级)以及清晰的备用几何体回退机制,使开发者能专注于游戏逻辑而非资产生成与集成。

兼容平台~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add 674345386/agent-skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

3D游戏资产 是做什么的?

当3D游戏需要具体、可识别的GLB资产,而非仅基本几何体时使用此技能。本技能拥有端到端工作流:选择路线、生成小型聚焦资产集、写入/读取asset_manifest.json,并将GLB文件接入游戏并包含备用方案。

必需行为

  • 如果游戏提示包含明确或隐含的实体,如玩家、角色、敌人、收集品、载具、武器、障碍物、Boss、吉祥物、关键道具或环境物体,当工具可用时,GLB生成是一个必需阶段。
  • 默认仅生成1-3个关键资产。优先处理玩家/主要角色,然后才是对游戏玩法至关重要的敌人、收集品、载具、障碍物或关键道具。不要生成装饰性填充物。
  • 仅将基本Three.js几何体用作资产等待期间的临时占位符,以及GLB加载失败时的运行时备用方案。
  • 除非用户明确要求,否则不要重新生成已有资产。如果asset_manifest.json已有可加载资产,请复用它。
  • 避免版权角色、品牌名称、标志和名人肖像。改写为原创设计。

路线选择

使用tripo作为快速路线:直接通过文本提示调用Tripo3D文本到模型。这最适合通用道具、敌人、收集品、载具、障碍物和快速迭代。

当视觉控制重要时使用gemini_reference:Gemini先创建纯白背景参考图像,然后Tripo图像到模型创建GLB。当用户提及Gemini、Nano Banana、T-pose、白色背景、参考图像、图像到模型、角色设计表、风格一致性,或当需要控制关键角色轮廓时,优先选择此路线。

仅当你对服务器根据提示自行选择感到满意时使用auto。如有疑问,请自行选择路线并显式传递。

环境

生成客户端与此技能捆绑在scripts/game-assets-mcp.mjs(Node >= 20,零依赖)。它连接到默认远程资产API,地址为http://54.81.110.182:3001。

  • GAME_ASSETS_API_URL — 可选,用于覆盖资产API基础URL
  • GAME_ASSETS_API_TOKEN — 每个用户的访问令牌

如果缺少令牌且服务需要身份验证,请在生成前要求用户设置GAME_ASSETS_API_TOKEN。仅当用户需要覆盖默认服务时才询问GAME_ASSETS_API_URL。切勿询问Tripo或Gemini API密钥;它们保存在服务器端。

工具工作流

如果你的会话中有名为mcp__game_assets__*的MCP工具可用,请优先使用它们。否则通过Bash运行捆绑客户端。两者都暴露相同的两个操作。

  1. 如果尚不知道当前工作区路径,运行pwd。
  2. 如果计划生成3个或更多资产,或者这是本线程中的首次资产生成,检查就绪状态(<skill-dir>是本技能的目录):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
  1. 生成1-3个资产(批量最大4个)。将参数作为一个JSON对象传递:
node <skill-dir>/scripts/game-assets-mcp.mjs generate --cwd "$(pwd)" --params '{
  "gamePrompt": "...",
  "route": "tripo",
  "assets": [{ "id": "...", "role": "player", "name": "...", "prompt": "..." }]
}'
  • route:tripo、gemini_reference或auto。
  • assets:1-3个对象,包含稳定的kebab-case格式id、role、name、prompt,可选地包含assetKind。
  • force:仅在用户明确要求重新生成资产时使用。
  • 命令在轮询远程任务时阻塞(通常每批1-3分钟)并打印JSON结果;退出码1表示批处理失败。
  1. 命令返回后,从cwd读取asset_manifest.json。将该文件视为真相来源。
  2. 使用Three.js的GLTFLoader将manifest.assets接入游戏代码。
  3. 为每个生成的资产保留本地基本几何体备用方案。游戏必须在GLB加载失败时仍可玩。

示例--params JSON:

{
  "cwd": "/absolute/path/to/project",
  "gamePrompt": "3D runner with an astronaut cat collecting crystals and dodging patrol robots",
  "route": "gemini_reference",
  "assets": [
    {
      "id": "astronaut-cat",
      "role": "player",
      "name": "Astronaut Cat",
      "assetKind": "character",
      "prompt": "original low-poly astronaut cat hero, round helmet, compact readable silhouette, blue and white suit, friendly arcade game character"
    },
    {
      "id": "energy-crystal",
      "role": "collectible",
      "name": "Energy Crystal",
      "assetKind": "prop",
      "prompt": "bright cyan faceted energy crystal pickup, clean silhouette, game collectible"
    }
  ]
}

运行时集成规则

  • 使用THREE.Box3().setFromObject()规范化每个加载的GLB:缩放到目标大小,水平居中,将底部放置在y = 0,并应用稳定的朝向偏移。
  • 将视觉与游戏逻辑碰撞盒分开。碰撞应使用稳定的游戏逻辑尺寸,而非原始模型边界或网格原点。
  • 如果manifest.assets包含rigged、rigType或animations,在声称存在原生动画之前先检查加载的gltf.animations。
  • 当存在原生剪辑时,创建一个THREE.AnimationMixer,通过不区分大小写的子字符串(如idle、walk、run、jump)映射剪辑,并每帧调用mixer.update(delta)。
  • 如果没有原生剪辑,使用整体组摆动/倾斜/旋转或显式标记的程序化剪辑作为后备动画。
  • 在README.md中添加一个名为3D Asset Pipeline或3D 素材流水线的简短章节,描述生成了哪些资产、使用了哪条路线以及使用了什么运行时动画源。

失败处理

  • 资产API不可达(就绪检查报告unreachable):说明远程模型生成不可用,要求用户检查默认资产服务、网络访问以及是否需要GAME_ASSETS_API_TOKEN;仅当覆盖默认服务时才询问GAME_ASSETS_API_URL。保留基本几何体备用方案并继续开发可玩游戏。
  • 服务器缺少Gemini密钥导致gemini_reference路线失败:如果可接受,切换到tripo,或告知用户服务器操作员必须配置Gemini密钥。
  • Tripo余额不足:不要循环重试。保留备用方案并在README中记录跳过的阶段。
  • 部分成功:使用成功生成的资产,其余资产使用备用几何体。

相关技能