games-development-ai/contracts/play-loop/actor-view-v4.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://wanxiang.ai/contracts/play-loop/actor-view-v4.schema.json",
  "title": "ActorViewV4",
  "description": "ActorView/4。普通场景保持 ActorView/3 投影；标准 Match-3 只增加匿名 pair 候选，不暴露分类、置信度、solver 或裁决。",
  "type": "object",
  "required": [
    "schemaVersion", "projectionVersion", "brief", "currentFrameRef", "currentFrameHash",
    "viewport", "legalSelections", "visualTargetCatalog", "history", "protocolErrors",
    "remainingBudget", "virtualTimeMs", "objectiveProgress", "interactionCandidates"
  ],
  "properties": {
    "schemaVersion": { "const": "playtest/3" },
    "projectionVersion": { "const": "ActorView/4" },
    "brief": { "type": "string", "minLength": 1 },
    "currentFrameRef": {
      "type": "string",
      "pattern": "^frames/(frame-initial|action-[1-9][0-9]*-(pre|post))\\.png$"
    },
    "currentFrameHash": { "$ref": "#/$defs/sha256" },
    "viewport": {
      "type": "object",
      "required": ["width", "height", "dpr"],
      "properties": { "width": { "const": 390 }, "height": { "const": 844 }, "dpr": { "const": 1 } },
      "additionalProperties": false
    },
    "legalSelections": { "$ref": "#/$defs/legalSelections" },
    "visualTargetCatalog": { "$ref": "#/$defs/visualTargetCatalog" },
    "history": { "type": "array", "maxItems": 64, "items": { "$ref": "#/$defs/historyEntry" } },
    "protocolErrors": { "type": "array", "maxItems": 16, "items": { "$ref": "#/$defs/protocolError" } },
    "remainingBudget": { "type": "integer", "minimum": 0 },
    "virtualTimeMs": { "type": "integer", "minimum": 0 },
    "objectiveProgress": {
      "anyOf": [{ "$ref": "#/$defs/objectiveProgress" }, { "type": "null" }]
    },
    "interactionCandidates": {
      "anyOf": [
        { "type": "null" },
        { "$ref": "#/$defs/interactionCandidates" }
      ]
    }
  },
  "additionalProperties": false,
  "$defs": {
    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
    "cell": {
      "type": "object",
      "required": ["row", "column"],
      "properties": {
        "row": { "type": "integer", "minimum": 1, "maximum": 12 },
        "column": { "type": "integer", "minimum": 1, "maximum": 12 }
      },
      "additionalProperties": false
    },
    "legalSelections": {
      "type": "object",
      "required": ["types", "safeKeys", "actionBudgetMs", "waitMs"],
      "properties": {
        "types": {
          "type": "array", "minItems": 1, "maxItems": 5,
          "items": { "enum": ["tap", "drag", "key", "wait", "swap_pair"] }, "uniqueItems": true
        },
        "safeKeys": {
          "type": "array", "maxItems": 11, "uniqueItems": true,
          "items": {
            "enum": [
              "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight",
              "KeyW", "KeyA", "KeyS", "KeyD", "Enter", "Escape", "Space"
            ]
          }
        },
        "actionBudgetMs": { "const": 600 },
        "waitMs": { "const": [100, 600] }
      },
      "additionalProperties": false
    },
    "visibleTarget": {
      "oneOf": [
        {
          "type": "object",
          "required": ["id", "kind", "allowedGestures"],
          "properties": {
            "id": { "type": "string", "pattern": "^r[0-9]{2}$" },
            "kind": { "const": "region" },
            "allowedGestures": {
              "type": "array", "minItems": 1, "maxItems": 2,
              "items": { "enum": ["tap", "drag"] }, "uniqueItems": true
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["id", "kind", "allowedGestures", "dimensions", "subAnchors"],
          "properties": {
            "id": { "type": "string", "pattern": "^l[0-9]{2}$" },
            "kind": { "const": "lattice" },
            "allowedGestures": {
              "type": "array", "minItems": 1, "maxItems": 2,
              "items": { "enum": ["tap", "drag"] }, "uniqueItems": true
            },
            "dimensions": { "$ref": "#/$defs/dimensions" },
            "subAnchors": { "$ref": "#/$defs/subAnchors" }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["id", "kind", "allowedGestures", "dimensions", "subAnchors", "fallbackOnly"],
          "properties": {
            "id": { "const": "g01" },
            "kind": { "const": "spatial_grid" },
            "allowedGestures": {
              "type": "array", "minItems": 1, "maxItems": 2,
              "items": { "enum": ["tap", "drag"] }, "uniqueItems": true
            },
            "dimensions": {
              "type": "object", "required": ["rows", "columns"],
              "properties": { "rows": { "const": 17 }, "columns": { "const": 8 } },
              "additionalProperties": false
            },
            "subAnchors": { "$ref": "#/$defs/subAnchors" },
            "fallbackOnly": { "const": true }
          },
          "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
    },
    "subAnchors": {
      "const": [
        "center", "north", "south", "east", "west",
        "northwest", "northeast", "southwest", "southeast"
      ]
    },
    "visualTargetCatalog": {
      "type": "object",
      "required": ["schemaVersion", "sourceFrameRef", "sourceFrameHash", "targetSetHash", "targets"],
      "properties": {
        "schemaVersion": { "const": "VisualTargetSet/1" },
        "sourceFrameRef": { "type": "string", "minLength": 1 },
        "sourceFrameHash": { "$ref": "#/$defs/sha256" },
        "targetSetHash": { "$ref": "#/$defs/sha256" },
        "targets": { "type": "array", "minItems": 1, "maxItems": 29, "items": { "$ref": "#/$defs/visibleTarget" } }
      },
      "additionalProperties": false
    },
    "historyEntry": {
      "type": "object",
      "required": [
        "actionId", "selection", "normalized", "valid", "retryCount", "preFrameRef",
        "preFrameHash", "preEventSeq", "virtualTimeBudgetMs", "postFrameRef",
        "postFrameHash", "postEventSeq", "causalGameResponse", "gameEvents", "protocolErrors"
      ],
      "properties": {
        "actionId": { "type": "string", "pattern": "^action-[1-9][0-9]*$" },
        "selection": { "$ref": "actor-selection-v2.schema.json" },
        "normalized": { "$ref": "playtest-evidence.schema.json#/$defs/action" },
        "valid": { "type": "boolean" },
        "retryCount": { "type": "integer", "minimum": 0, "maximum": 2 },
        "preFrameRef": { "$ref": "playtest-evidence.schema.json#/$defs/frameRef" },
        "preFrameHash": { "$ref": "#/$defs/sha256" },
        "preEventSeq": { "type": "integer", "minimum": 0 },
        "virtualTimeBudgetMs": { "type": "integer", "minimum": 0 },
        "postFrameRef": { "$ref": "playtest-evidence.schema.json#/$defs/frameRef" },
        "postFrameHash": { "$ref": "#/$defs/sha256" },
        "postEventSeq": { "type": "integer", "minimum": 0 },
        "causalGameResponse": { "type": "boolean" },
        "gameEvents": { "type": "array", "items": { "$ref": "game-event.schema.json" } },
        "protocolErrors": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "protocolError": {
      "type": "object", "required": ["code", "message"],
      "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } },
      "additionalProperties": false
    },
    "objectiveObligation": {
      "type": "object",
      "required": ["id", "title", "seenStepTitles", "missingStepTitles", "status"],
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "title": { "type": "string" },
        "seenStepTitles": { "type": "array", "items": { "type": "string" } },
        "missingStepTitles": { "type": "array", "items": { "type": "string" } },
        "status": { "enum": ["unobserved", "partial", "observed"] }
      },
      "additionalProperties": false
    },
    "objectiveProgress": {
      "type": "object",
      "required": ["candidateOnly", "snapshotSeq", "hash", "obligations"],
      "properties": {
        "candidateOnly": { "const": true },
        "snapshotSeq": { "type": "integer", "minimum": 1 },
        "hash": { "$ref": "#/$defs/sha256" },
        "obligations": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/objectiveObligation" } }
      },
      "additionalProperties": false
    },
    "candidateEndpoint": {
      "type": "object", "required": ["cell"],
      "properties": { "cell": { "$ref": "#/$defs/cell" } },
      "additionalProperties": false
    },
    "match3Candidate": {
      "type": "object",
      "required": ["candidateId", "latticeId", "pair"],
      "properties": {
        "candidateId": { "type": "string", "pattern": "^ms[0-9]{2,3}$" },
        "latticeId": { "type": "string", "pattern": "^l[0-9]{2}$" },
        "pair": {
          "type": "array", "minItems": 2, "maxItems": 2,
          "items": { "$ref": "#/$defs/candidateEndpoint" }
        }
      },
      "additionalProperties": false
    },
    "interactionCandidates": {
      "type": "object", "required": ["match3Swaps"],
      "properties": {
        "match3Swaps": {
          "type": "object", "required": ["candidateSetHash", "candidates"],
          "properties": {
            "candidateSetHash": { "$ref": "#/$defs/sha256" },
            "candidates": { "type": "array", "minItems": 1, "maxItems": 264, "items": { "$ref": "#/$defs/match3Candidate" } }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  }
}