games-development-ai/contracts/game-package.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://huijing.ai/contracts/game-package.schema.json",
  "title": "GamePackage",
  "description": "绘境AI 游戏包契约（契约 #4，owner=WS3+WS2）。生成链路（aigc/studio）的产出物，runtime 编译/预览/发布的输入物。贯穿 生成→编译→预览→发布→游戏流→试玩 全链路，是平台最核心的数据契约。",
  "type": "object",
  "required": ["schemaVersion", "gameId", "versionId", "templateId", "gameConfig", "assets", "manifest", "meta"],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": {
      "description": "本契约版本。新增字段不升版本；删除/重命名字段升版本。",
      "type": "string",
      "const": "1.0"
    },
    "gameId": {
      "description": "游戏全局唯一 ID（project.game_project.id）",
      "type": "string",
      "minLength": 1
    },
    "versionId": {
      "description": "游戏版本 ID（project.game_version.id）。资源 OSS 路径按 /games/{gameId}/versions/{versionId}/ 版本化。",
      "type": "string",
      "minLength": 1
    },
    "templateId": {
      "description": "玩法模板 ID（aigc 模板注册表）。MVP 取值范围 = 3-5 个 P0 模板，如 dodge/runner/clicker/puzzle/shooter（最终由产品拍板）。",
      "type": "string",
      "minLength": 1
    },
    "gameConfig": {
      "description": "可玩游戏配置（模板相关的玩法参数）。结构由各模板的 GameConfig JSON Schema 约束（contracts 后续批 templates/*.schema.json）；此处仅约定为对象并要求 templateId 自洽。runtime 编译前做静态 Schema 校验（门禁④）。",
      "type": "object"
    },
    "assets": {
      "description": "资源清单。每项资源 hash 命名长期缓存；编译期校验总大小（≤10MB）、首屏（≤2MB）。",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "type", "url", "hash", "bytes", "mime"],
        "additionalProperties": false,
        "properties": {
          "id": { "description": "资源在包内的逻辑 ID", "type": "string" },
          "type": { "description": "资源类型", "type": "string", "enum": ["image", "audio", "spine", "json", "font", "atlas"] },
          "url": { "description": "资源可访问 URL（MVP 本地 MinIO / 生产 OSS+CDN）", "type": "string", "format": "uri" },
          "hash": { "description": "资源内容 sha256（hex），用于完整性校验与 CDN 永久缓存命名", "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "bytes": { "description": "资源字节大小", "type": "integer", "minimum": 0 },
          "mime": { "description": "资源 MIME 类型", "type": "string" }
        }
      }
    },
    "manifest": {
      "description": "运行清单。runtime 据此加载与做完整性校验。",
      "type": "object",
      "required": ["runtimeVersion", "entry", "preloadPolicy", "bundleSize", "checksum"],
      "additionalProperties": false,
      "properties": {
        "runtimeVersion": { "description": "目标 HuijingGameSDK / Canvas Runtime 版本（semver）", "type": "string" },
        "entry": { "description": "入口文件相对路径", "type": "string" },
        "preloadPolicy": {
          "description": "三容器预加载策略：eager=进容器即加载 / lazy=可见时加载",
          "type": "string",
          "enum": ["eager", "lazy"]
        },
        "bundleSize": { "description": "包总字节（编译期门禁校验上限）", "type": "integer", "minimum": 0 },
        "checksum": { "description": "整包 sha256（hex），Manifest 完整性校验", "type": "string", "pattern": "^[a-f0-9]{64}$" }
      }
    },
    "meta": {
      "description": "展示与合规元信息（发布前检查清单门禁⑦校验）。",
      "type": "object",
      "required": ["title", "summary", "cover", "ageRating"],
      "additionalProperties": false,
      "properties": {
        "title": { "description": "标题", "type": "string", "minLength": 1, "maxLength": 60 },
        "summary": { "description": "简介", "type": "string", "maxLength": 500 },
        "cover": { "description": "封面图 URL（首屏卡片展示）", "type": "string", "format": "uri" },
        "tags": { "description": "标签", "type": "array", "items": { "type": "string" }, "maxItems": 10 },
        "ageRating": {
          "description": "适龄提示（发布前必填，门禁⑦）。all=全年龄 / 8+ / 12+ / 16+",
          "type": "string",
          "enum": ["all", "8+", "12+", "16+"]
        }
      }
    },
    "provenance": {
      "description": "可追溯来源（质量门禁与缓存命中用）。相同 promptHash 命中缓存可跳过 LLM 生成。",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "promptHash": { "description": "生成所用 Prompt 的 hash（产物缓存键）", "type": "string" },
        "model": { "description": "生成所用 LLM 标识（如 deepseek-chat / qwen-max）", "type": "string" },
        "traceId": { "description": "贯穿 生成→编译→加载→运行 的 trace_id", "type": "string" },
        "generatedAt": { "description": "生成时间（ISO 8601）", "type": "string", "format": "date-time" }
      }
    }
  }
}