remix-upload-asset

上传游戏资源工作流

概述

通过 REST API 将任意文件（图像、音频、3D 模型）上传为托管的游戏资源。 返回一个永久 URL，可在游戏 HTML 中引用。

前提条件

• Remix 平台上必须已存在游戏（需要游戏 ID）。
• 必须设置 REMIX_API_KEY 环境变量。

步骤

1. 检查是否已有游戏 ID

重要：先检查，不要创建新游戏。

如任务上下文或之前的工具结果中提供了 gameId，请使用它。

否则，请读取最近的 .remix-cli.json。旧项目可能仍使用 .remix-mcp.json。如果其中任一文件包含 gameId，请复用它。

只有当这些来源中都没有 gameId 时，才应按照 upload-game 工作流创建一个。

2. 上传资源

以 multipart 表单数据的形式发送文件：

POST https://api.remix.gg/v1/games/{gameId}/assets
Authorization: Bearer $REMIX_API_KEY
Content-Type: multipart/form-data

Form fields:
  file       (required) — the binary file to upload
  assetName  (optional) — custom display name; defaults to the filename

允许的扩展名： .jpg、.jpeg、.png、.webp、.mp3、.wav、 .hdr、.glb、.gltf

最大文件大小： 5 MB

响应：

{
  "success": true,
  "data": {
    "gameId": "...",
    "asset": {
      "url": "https://..."
    }
  }
}

使用 data.asset.url 作为资源的托管 URL。

3. 在游戏 HTML 中使用 URL

在游戏代码中引用返回的 URL。示例：

<img src="https://returned-asset-url.png" width="64" height="64" />

const img = new Image();
img.src = "https://returned-asset-url.png";
img.onload = () => ctx.drawImage(img, x, y, w, h);

const audio = new Audio("https://returned-asset-url.mp3");
audio.play();

4.（可选）列出所有资源

获取游戏已上传的所有资源：

GET https://api.remix.gg/v1/games/{gameId}/assets
Authorization: Bearer $REMIX_API_KEY

提示

• 使用描述性文件名。 使用清晰的文件名，例如 player-idle.png 或 jump-sfx.mp3 ——文件名会成为默认资源名称。
• 在游戏开始前预加载资源。 在启动游戏循环前等待 onload / canplaythrough 事件，以避免资源缺失。
• 单个文件不要超过 5 MB。 上传前压缩图像和音频。 尽可能使用 .webp 格式的图像和 .mp3 格式的音频。
• 每个资源都要重复操作。 对游戏所需的每个文件执行步骤 2-3。