games-development-ai/contracts/agent-loop/source-project.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://wanxiang.ai/contracts/agent-loop/source-project.schema.json",
  "title": "SourceProject",
  "description": "游戏源项目工件:cheap agents 在固定架构上填的唯一结构化产物;改源不改打包产物(GamePackage 产物 schema 不变);Opus 设计、长期版本化升级。两开发线交汇的 keystone 契约(后端线产出/落库,引擎线 2D 适配器消费)。详见 docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md §5.1。",
  "type": "object",
  "required": ["schemaVersion", "sourceHash", "profile", "gameDefinition"],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": { "const": "1.0", "description": "源项目契约版本(独立于 GamePackage 版本)" },
    "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "源 JSON 规范化后 sha256(可寻址/幂等键)" },
    "buildInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "sha256(sourceHash + buildProfile);确定性构建缓存命中键" },
    "profile": {
      "type": "object",
      "description": "维度无关三维(否则剧情/TRPG 类绷断,见 execution §10.2/§5.9)",
      "required": ["tickModel", "inputModel", "progressModel"],
      "additionalProperties": false,
      "properties": {
        "tickModel": { "enum": ["realtime", "turn-based", "event"], "description": "时间模型:决定适配器是否挂 update 循环" },
        "inputModel": { "enum": ["continuous", "discrete-choice", "text-command"] },
        "progressModel": { "enum": ["metric", "narrative"], "description": "narrative → 走 narrative-designer-reviewer 质量门(替九门)" }
      }
    },
    "gameDefinition": {
      "type": "object",
      "description": "轻量声明式领域模型(非 AAA ECS:无 system 调度器/无 archetype 存储/无 query DSL)",
      "required": ["entities", "scenes", "rules"],
      "additionalProperties": false,
      "properties": {
        "entities": { "type": "array", "items": { "$ref": "#/$defs/entity" } },
        "components": { "type": "array", "items": { "$ref": "#/$defs/component" }, "description": "组件定义(声明式属性:渲染/碰撞/物理)" },
        "behaviors": { "type": "array", "items": { "$ref": "#/$defs/behavior" }, "description": "行为模块(逻辑,维度无关,读参数操作实体;真逻辑代码由核心代码 agent 产出经构建编译进 __GameBundle)" },
        "scenes": { "type": "array", "items": { "$ref": "#/$defs/scene" }, "description": "关卡构成(数据驱动)" },
        "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" }, "description": "胜负条件(数据驱动)" }
      }
    },
    "assets": { "type": "array", "items": { "$ref": "#/$defs/assetSpec" }, "description": "六类资产规格/引用(asset 节点写入)" },
    "config": { "type": "object", "description": "平衡参数(数值/难度/速度)——数据驱动,确定性 modify 改这里免 LLM" }
  },
  "$defs": {
    "entity": {
      "type": "object",
      "description": "实体:transform(2D 用 xy/z=0,3D 用 xyz,同字段两维成立)+ 组件引用",
      "required": ["id", "transform"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "transform": {
          "type": "object",
          "required": ["position"],
          "additionalProperties": false,
          "properties": {
            "position": {
              "type": "object",
              "required": ["x", "y"],
              "additionalProperties": false,
              "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number", "default": 0 } }
            },
            "rotation": { "type": "number" },
            "scale": { "type": "number", "default": 1 }
          }
        },
        "components": { "type": "array", "items": { "type": "string" }, "description": "引用 components[].id" }
      }
    },
    "component": {
      "type": "object",
      "required": ["id", "kind"],
      "additionalProperties": true,
      "properties": { "id": { "type": "string" }, "kind": { "enum": ["render", "collision", "physics", "custom"] } }
    },
    "behavior": {
      "type": "object",
      "required": ["id", "trigger"],
      "additionalProperties": true,
      "properties": { "id": { "type": "string" }, "trigger": { "enum": ["init", "update", "input", "collision", "timer"] } }
    },
    "scene": {
      "type": "object",
      "required": ["id", "entityRefs"],
      "additionalProperties": true,
      "properties": { "id": { "type": "string" }, "entityRefs": { "type": "array", "items": { "type": "string" } } }
    },
    "rule": {
      "type": "object",
      "required": ["id", "condition", "outcome"],
      "additionalProperties": true,
      "properties": { "id": { "type": "string" }, "condition": { "type": "string" }, "outcome": { "enum": ["win", "lose", "score", "advance"] } }
    },
    "assetSpec": {
      "type": "object",
      "description": "六类资产规格/引用(对齐 v2 review C5;四处同引同一枚举)",
      "required": ["id", "category", "ref"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string" },
        "category": { "enum": ["sprite", "character", "effect", "scene", "ui", "music"], "description": "六类:图元/角色/特效/场景/界面/音乐" },
        "ref": { "type": "string", "description": "平台 assetId/ref 为主" },
        "url": { "type": "string", "format": "uri", "description": "只读镜像 URL" },
        "provider": { "type": "string", "default": "mmx-cli", "description": "provider 可插拔" }
      }
    }
  }
}