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": "游戏源源项目工件:agents 在固定架构上填的唯一结构化产物;改源不改打包产物(GamePackage 产物 schema 不变)。【2026-06-21 oneOf 升级·HJ-AGI-003 Phase1】判别式 schemaVersion:1.0=gamedef legacy 声明式表示(冻结只读,A-model 退役 gamedef 后不再产出;存量按 schemaVersion 分支读,不受影响)/ 2.0=A-model 多文件代码工件(固定 plumbing + LLM 写的表达性多文件 src/)。注:本 schema 限 Tier0/1 线;tier2 真 Phaser 引擎工程的源项目契约另立一份独立 schema(tier2-source-project.schema.json)、不复用本路。两开发线交汇的 keystone 契约(后端线产出/落库,引擎线消费)。",
  "type": "object",
  "required": ["schemaVersion"],
  "oneOf": [
    { "$ref": "#/$defs/sourceProjectV1" },
    { "$ref": "#/$defs/sourceProjectV2" }
  ],
  "$defs": {
    "sourceProjectV1": {
      "type": "object",
      "description": "1.0 gamedef legacy:轻量声明式领域模型(冻结只读,不再产出;存量自包含 bundle 仍可玩)。",
      "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": { "$ref": "#/$defs/profile" },
        "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" }
      }
    },
    "sourceProjectV2": {
      "type": "object",
      "description": "2.0 A-model:多文件代码工件。固定零表达性 plumbing(entry/main/index) + LLM 写的表达性多文件 src/(core/render/game/host-config/balance/assets)。逃离 gamedef 的 JSON 框死——一切玩法/渲染/数值/wiring 都是真 JS。",
      "required": ["schemaVersion", "sourceHash", "profile", "files", "entry", "globalName"],
      "additionalProperties": false,
      "properties": {
        "schemaVersion": { "const": "2.0", "description": "A-model 源工件契约版本" },
        "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "源(规范化 files)sha256(可寻址/幂等键)" },
        "buildInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "sha256(sourceHash + buildProfile);确定性构建缓存命中键" },
        "profile": { "$ref": "#/$defs/profile" },
        "files": {
          "type": "object",
          "description": "多文件源:相对路径(相对 game 根)→ 文件文本内容。含 LLM 写的表达性代码(src/{core,render,game,host-config,balance,assets}.js)+ 固定 plumbing(entry.js/src/main.js/index.html)。",
          "minProperties": 1,
          "propertyNames": { "pattern": "^[A-Za-z0-9_./-]+$" },
          "additionalProperties": { "type": "string" }
        },
        "entry": { "type": "string", "minLength": 1, "description": "esbuild 入口文件相对路径(如 entry.js)" },
        "globalName": { "const": "__GameBundle", "description": "iife 全局名:对齐 SAA 九门契约(index 调 __GameBundle.bootGameHost)" },
        "plugins": { "type": "array", "items": { "type": "string" }, "description": "本款用到的插件键名(host-config 注入;诊断/审计用)" },
        "assets": { "type": "array", "items": { "$ref": "#/$defs/assetSpec" }, "description": "六类资产规格/引用(design assetSpec → asset 节点;A-model 同用此枚举)" },
        "config": { "type": "object", "description": "平衡参数(数值/难度/速度)——确定性 modify 改这里免 LLM" }
      }
    },
    "profile": {
      "type": "object",
      "description": "维度无关三维(否则剧情/TRPG 类绷断,见 execution §10.2/§5.9);1.0/2.0 共用",
      "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 质量门(替九门)" }
      }
    },
    "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", "clickable", "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;四处同引同一枚举);1.0/2.0 共用",
      "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 可插拔" }
      }
    }
  }
}