games-development-ai/contracts/play-loop/visual-target-set.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://wanxiang.ai/contracts/play-loop/visual-target-set.schema.json",
  "title": "VisualTargetSetV1",
  "description": "VisualTargetSet/1。支持 opencv-visual-targets@1.0.1 与受信 match3-producer-seeded-targets@1.0.0；guide 与绑定 manifest 是独立制品。",
  "type": "object",
  "required": [
    "schemaVersion", "sourceFrameRef", "sourceFrameHash", "viewport",
    "generator", "targets", "targetSetHash"
  ],
  "properties": {
    "schemaVersion": { "const": "VisualTargetSet/1" },
    "sourceFrameRef": { "type": "string", "minLength": 1 },
    "sourceFrameHash": { "$ref": "#/$defs/sha256" },
    "viewport": { "$ref": "#/$defs/viewport" },
    "generator": { "$ref": "#/$defs/generator" },
    "targets": {
      "type": "array",
      "minItems": 1,
      "maxItems": 29,
      "items": {
        "oneOf": [
          { "$ref": "#/$defs/regionTarget" },
          { "$ref": "#/$defs/latticeTarget" },
          { "$ref": "#/$defs/spatialGridTarget" }
        ]
      }
    },
    "targetSetHash": { "$ref": "#/$defs/sha256" }
  },
  "additionalProperties": false,
  "$defs": {
    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
    "viewport": {
      "type": "object",
      "required": ["width", "height"],
      "properties": {
        "width": { "const": 390 },
        "height": { "const": 844 }
      },
      "additionalProperties": false
    },
    "generator": {
      "oneOf": [
        { "$ref": "#/$defs/opencvGenerator" },
        { "$ref": "#/$defs/producerSeededGenerator" }
      ]
    },
    "opencvGenerator": {
      "type": "object",
      "required": ["id", "version", "configHash"],
      "properties": {
        "id": { "const": "opencv-visual-targets" },
        "version": { "const": "1.0.1" },
        "configHash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "producerSeededGenerator": {
      "type": "object",
      "required": ["id", "version", "configHash"],
      "properties": {
        "id": { "const": "match3-producer-seeded-targets" },
        "version": { "const": "1.0.0" },
        "configHash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "bounds": {
      "type": "object",
      "required": ["x", "y", "width", "height"],
      "properties": {
        "x": { "type": "integer", "minimum": 0, "maximum": 389 },
        "y": { "type": "integer", "minimum": 0, "maximum": 843 },
        "width": { "type": "integer", "minimum": 1, "maximum": 390 },
        "height": { "type": "integer", "minimum": 1, "maximum": 844 }
      },
      "additionalProperties": false
    },
    "point": {
      "type": "object",
      "required": ["x", "y"],
      "properties": {
        "x": { "type": "integer", "minimum": 0, "maximum": 389 },
        "y": { "type": "integer", "minimum": 0, "maximum": 843 }
      },
      "additionalProperties": false
    },
    "dimensions": {
      "type": "object",
      "required": ["rows", "columns"],
      "properties": {
        "rows": { "type": "integer", "minimum": 3, "maximum": 12 },
        "columns": { "type": "integer", "minimum": 3, "maximum": 12 }
      },
      "additionalProperties": false
    },
    "allowedGestures": {
      "type": "array",
      "minItems": 1,
      "maxItems": 2,
      "items": { "enum": ["tap", "drag"] }
    },
    "cell": {
      "type": "object",
      "required": ["row", "column"],
      "properties": {
        "row": { "type": "integer", "minimum": 1, "maximum": 12 },
        "column": { "type": "integer", "minimum": 1, "maximum": 12 }
      },
      "additionalProperties": false
    },
    "metrics": {
      "type": "object",
      "required": [
        "coveragePermille", "maxAxisResidualMilliPx", "sizeCvPermille", "spacingCvPermille"
      ],
      "properties": {
        "coveragePermille": { "type": "integer", "minimum": 700, "maximum": 1000 },
        "maxAxisResidualMilliPx": { "type": "integer", "minimum": 0, "maximum": 3000 },
        "sizeCvPermille": { "type": "integer", "minimum": 0, "maximum": 150 },
        "spacingCvPermille": { "type": "integer", "minimum": 0, "maximum": 120 }
      },
      "additionalProperties": false
    },
    "regionTarget": {
      "type": "object",
      "required": [
        "id", "kind", "bounds", "safePoint", "allowedGestures",
        "proposalSource", "proposalScore"
      ],
      "properties": {
        "id": { "type": "string", "pattern": "^r[0-9]{2}$" },
        "kind": { "const": "region" },
        "bounds": { "$ref": "#/$defs/bounds" },
        "safePoint": { "$ref": "#/$defs/point" },
        "allowedGestures": { "$ref": "#/$defs/allowedGestures" },
        "proposalSource": { "enum": ["contour", "connected_component"] },
        "proposalScore": { "type": "integer", "minimum": 0 }
      },
      "additionalProperties": false
    },
    "latticeTarget": {
      "type": "object",
      "required": [
        "id", "kind", "bounds", "allowedGestures", "dimensions",
        "rowCenters", "columnCenters", "observedCells", "metrics", "subAnchors"
      ],
      "properties": {
        "id": { "type": "string", "pattern": "^l[0-9]{2}$" },
        "kind": { "const": "lattice" },
        "bounds": { "$ref": "#/$defs/bounds" },
        "allowedGestures": { "$ref": "#/$defs/allowedGestures" },
        "dimensions": { "$ref": "#/$defs/dimensions" },
        "rowCenters": {
          "type": "array", "minItems": 3, "maxItems": 12,
          "items": { "type": "integer", "minimum": 0, "maximum": 843 }
        },
        "columnCenters": {
          "type": "array", "minItems": 3, "maxItems": 12,
          "items": { "type": "integer", "minimum": 0, "maximum": 389 }
        },
        "observedCells": {
          "type": "array", "minItems": 9, "maxItems": 144,
          "description": "OpenCV 模式为直接支撑轴推断的观测子集；producer 模式为经过当前 PNG shell 支撑扫描的 canonical cell 集合。",
          "items": { "$ref": "#/$defs/cell" }
        },
        "geometrySource": {
          "type": "object",
          "required": [
            "mode", "capabilityId", "capabilityVersion",
            "capabilityConfigHash", "geometryHash"
          ],
          "properties": {
            "mode": { "const": "producer_capability" },
            "capabilityId": { "const": "match3-producer-profile" },
            "capabilityVersion": { "const": "1.0.0" },
            "capabilityConfigHash": { "$ref": "#/$defs/sha256" },
            "geometryHash": { "$ref": "#/$defs/sha256" }
          },
          "additionalProperties": false
        },
        "metrics": { "$ref": "#/$defs/metrics" },
        "subAnchors": {
          "const": [
            "center", "north", "south", "east", "west",
            "northwest", "northeast", "southwest", "southeast"
          ]
        }
      },
      "additionalProperties": false
    },
    "spatialGridTarget": {
      "type": "object",
      "required": [
        "id", "kind", "bounds", "allowedGestures", "dimensions", "subAnchors", "fallbackOnly"
      ],
      "properties": {
        "id": { "const": "g01" },
        "kind": { "const": "spatial_grid" },
        "bounds": { "$ref": "#/$defs/bounds" },
        "allowedGestures": { "$ref": "#/$defs/allowedGestures" },
        "dimensions": {
          "type": "object",
          "required": ["rows", "columns"],
          "properties": {
            "rows": { "const": 17 },
            "columns": { "const": 8 }
          },
          "additionalProperties": false
        },
        "subAnchors": {
          "const": [
            "center", "north", "south", "east", "west",
            "northwest", "northeast", "southwest", "southeast"
          ]
        },
        "fallbackOnly": { "const": true }
      },
      "additionalProperties": false
    }
  }
}