@ue-shed/protocol 0.1.0 → 0.3.0

package/contracts/cameras/map-tile/v1/plan.schema.json

@@ -0,0 +1,176 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/map-tile/v1/plan.schema.json",
+	"title": "UE Shed Map Capture Plan v1.0",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"capture",
+		"contract",
+		"gutterPixels",
+		"id",
+		"levels",
+		"output",
+		"project",
+		"requestedBounds",
+		"tilePixelSize"
+	],
+	"properties": {
+		"capture": { "$ref": "#/$defs/capturePolicy" },
+		"contract": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "version"],
+			"properties": {
+				"name": { "const": "ue-shed-map-capture-plan" },
+				"version": { "$ref": "#/$defs/version" }
+			}
+		},
+		"gutterPixels": { "type": "integer", "minimum": 0, "maximum": 32 },
+		"id": { "$ref": "#/$defs/id" },
+		"levels": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["coarsestUnitsPerPixel", "count"],
+			"properties": {
+				"coarsestUnitsPerPixel": { "type": "number", "exclusiveMinimum": 0 },
+				"count": { "type": "integer", "minimum": 1, "maximum": 24 }
+			}
+		},
+		"output": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["imageFormat", "publication"],
+			"properties": {
+				"imageFormat": { "const": "png" },
+				"publication": { "const": "local_immutable" }
+			}
+		},
+		"project": { "$ref": "#/$defs/project" },
+		"requestedBounds": { "$ref": "#/$defs/bounds" },
+		"tilePixelSize": { "type": "integer", "minimum": 64, "maximum": 4096 }
+	},
+	"$defs": {
+		"id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+		"version": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["major", "minor"],
+			"properties": { "major": { "const": 1 }, "minor": { "const": 0 } }
+		},
+		"bounds": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["minX", "minY", "maxX", "maxY"],
+			"properties": {
+				"minX": { "type": "number" },
+				"minY": { "type": "number" },
+				"maxX": { "type": "number" },
+				"maxY": { "type": "number" }
+			}
+		},
+		"project": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "mapPath"],
+			"properties": {
+				"id": { "$ref": "#/$defs/id" },
+				"mapPath": { "type": "string", "pattern": "^/[A-Za-z0-9_./-]+$" }
+			}
+		},
+		"dataLayers": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["mode"],
+					"properties": { "mode": { "const": "unchanged" } }
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["mode", "states"],
+					"properties": {
+						"mode": { "const": "explicit" },
+						"states": {
+							"type": "array",
+							"maxItems": 64,
+							"items": {
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["name", "state"],
+								"properties": {
+									"name": { "type": "string", "minLength": 1, "maxLength": 1024 },
+									"state": { "enum": ["unloaded", "loaded", "activated"] }
+								}
+							}
+						}
+					}
+				}
+			]
+		},
+		"capturePolicy": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["dataLayers", "orientation", "render", "z"],
+			"properties": {
+				"dataLayers": { "$ref": "#/$defs/dataLayers" },
+				"orientation": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["pitch", "roll", "yaw"],
+					"properties": {
+						"pitch": { "const": -90 },
+						"roll": { "const": 0 },
+						"yaw": { "const": 0 }
+					}
+				},
+				"render": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["effects", "lodPolicy", "profile"],
+					"properties": {
+						"effects": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["fog", "volumetricFog"],
+							"properties": {
+								"fog": { "type": "boolean" },
+								"volumetricFog": { "type": "boolean" }
+							}
+						},
+						"lodDistanceScaleByZoom": {
+							"type": "array",
+							"minItems": 1,
+							"maxItems": 24,
+							"items": { "type": "number", "minimum": 0.1, "maximum": 100 }
+						},
+						"lodPolicy": {
+							"enum": ["natural", "fixed_lod_zero", "per_level_distance_scale"]
+						},
+						"profile": {
+							"enum": [
+								"full_fidelity",
+								"seam_stable",
+								"scene_capture_defaults",
+								"observation"
+							]
+						}
+					},
+					"allOf": [
+						{
+							"if": {
+								"properties": {
+									"lodPolicy": { "const": "per_level_distance_scale" }
+								}
+							},
+							"then": { "required": ["lodDistanceScaleByZoom"] },
+							"else": { "not": { "required": ["lodDistanceScaleByZoom"] } }
+						}
+					]
+				},
+				"z": { "type": "number" }
+			}
+		}
+	}
+}

package/contracts/cameras/provisioning/v1/README.md

@@ -4,9 +4,11 @@
 camera is a transient runtime realization, identified by a generated `ProvisionedCameraId`; it is
 never a durable Map Review camera record.
 
-Each request carries an explicit correlation to either a framing candidate or a durable Review View.
-The compatibility decoder accepts the former candidate-only request shape for already-installed
-clients, but new clients emit only `schemaVersion: 2` and the `correlation` union.
+Each request carries an expected map and an explicit correlation to a framing candidate, a durable
+Review View, or a Map Capture Plan. A camera selects either perspective field of view or
+orthographic width through a discriminated projection. The compatibility decoder accepts the
+candidate-only and `schemaVersion: 2` perspective request shapes for already-installed clients, but
+new clients emit only `schemaVersion: 3`.
 
 The editor returns the same correlation for every provisioned camera. Array index remains a live
 frame transport position, never durable identity.

package/contracts/cameras/provisioning/v1/fixtures/provision-request-valid.json

@@ -1,14 +1,23 @@
 {
-	"schemaVersion": 2,
+	"schemaVersion": 3,
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
 	"previewFps": 5,
 	"cameras": [
 		{
 			"correlation": { "type": "framing_candidate", "candidateId": "context_three_quarter" },
-			"fieldOfViewDegrees": 60,
+			"projection": { "type": "perspective", "fieldOfViewDegrees": 60 },
 			"location": { "x": 1200, "y": -1400, "z": 700 },
 			"rotation": { "pitch": -12, "yaw": 135, "roll": 0 },
 			"width": 320,
 			"height": 180
+		},
+		{
+			"correlation": { "type": "map_capture_plan", "mapCapturePlanId": "fixture-overview" },
+			"projection": { "type": "orthographic", "orthoWidth": 4096 },
+			"location": { "x": 0, "y": 0, "z": 5000 },
+			"rotation": { "pitch": -90, "yaw": 0, "roll": 0 },
+			"width": 640,
+			"height": 360
 		}
 	]
 }

package/contracts/cameras/provisioning/v1/provision-request.schema.json

@@ -4,68 +4,149 @@
 	"title": "UE Shed provisioned camera request v1",
 	"type": "object",
 	"additionalProperties": false,
-	"required": ["schemaVersion", "previewFps", "cameras"],
+	"required": ["schemaVersion", "expectedMapPath", "previewFps", "cameras"],
 	"properties": {
-		"schemaVersion": { "const": 2 },
+		"schemaVersion": { "const": 3 },
+		"expectedMapPath": {
+			"type": "string",
+			"minLength": 1,
+			"maxLength": 1024,
+			"pattern": "^/[A-Za-z0-9_./-]+$"
+		},
 		"previewFps": { "type": "integer", "minimum": 1, "maximum": 10 },
 		"cameras": {
 			"type": "array",
 			"minItems": 1,
 			"maxItems": 32,
 			"items": {
-				"type": "object",
-				"additionalProperties": false,
-				"required": [
-					"correlation",
-					"fieldOfViewDegrees",
-					"location",
-					"rotation",
-					"width",
-					"height"
-				],
-				"properties": {
-					"correlation": {
-						"oneOf": [
-							{
-								"type": "object",
-								"additionalProperties": false,
-								"required": ["type", "candidateId"],
-								"properties": {
-									"type": { "const": "framing_candidate" },
-									"candidateId": {
-										"type": "string",
-										"minLength": 1,
-										"maxLength": 128,
-										"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
-									}
-								}
-							},
-							{
-								"type": "object",
-								"additionalProperties": false,
-								"required": ["type", "reviewViewId"],
-								"properties": {
-									"type": { "const": "review_view" },
-									"reviewViewId": {
-										"type": "string",
-										"minLength": 1,
-										"maxLength": 128,
-										"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
-									}
-								}
-							}
-						]
+				"oneOf": [
+					{
+						"$ref": "#/$defs/perspectiveCamera"
 					},
-					"fieldOfViewDegrees": { "type": "number", "minimum": 5, "maximum": 170 },
-					"location": { "$ref": "#/$defs/vector" },
-					"rotation": { "$ref": "#/$defs/rotation" },
-					"width": { "type": "integer", "minimum": 64, "maximum": 2560 },
-					"height": { "type": "integer", "minimum": 64, "maximum": 1440 }
-				}
+					{
+						"$ref": "#/$defs/orthographicCamera"
+					}
+				]
 			}
 		}
 	},
 	"$defs": {
+		"cameraFields": {
+			"type": "object",
+			"required": ["correlation", "projection", "location", "rotation", "width", "height"],
+			"properties": {
+				"correlation": { "$ref": "#/$defs/correlation" },
+				"location": { "$ref": "#/$defs/vector" },
+				"rotation": { "$ref": "#/$defs/rotation" },
+				"width": { "type": "integer", "minimum": 64, "maximum": 2560 },
+				"height": { "type": "integer", "minimum": 64, "maximum": 1440 }
+			}
+		},
+		"perspectiveCamera": {
+			"allOf": [
+				{ "$ref": "#/$defs/cameraFields" },
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": [
+						"correlation",
+						"projection",
+						"location",
+						"rotation",
+						"width",
+						"height"
+					],
+					"properties": {
+						"correlation": { "$ref": "#/$defs/correlation" },
+						"projection": { "$ref": "#/$defs/perspectiveProjection" },
+						"location": { "$ref": "#/$defs/vector" },
+						"rotation": { "$ref": "#/$defs/rotation" },
+						"width": { "type": "integer", "minimum": 64, "maximum": 2560 },
+						"height": { "type": "integer", "minimum": 64, "maximum": 1440 }
+					}
+				}
+			]
+		},
+		"orthographicCamera": {
+			"allOf": [
+				{ "$ref": "#/$defs/cameraFields" },
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": [
+						"correlation",
+						"projection",
+						"location",
+						"rotation",
+						"width",
+						"height"
+					],
+					"properties": {
+						"correlation": { "$ref": "#/$defs/correlation" },
+						"projection": { "$ref": "#/$defs/orthographicProjection" },
+						"location": { "$ref": "#/$defs/vector" },
+						"rotation": { "$ref": "#/$defs/rotation" },
+						"width": { "type": "integer", "minimum": 64, "maximum": 2560 },
+						"height": { "type": "integer", "minimum": 64, "maximum": 1440 }
+					}
+				}
+			]
+		},
+		"perspectiveProjection": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["type", "fieldOfViewDegrees"],
+			"properties": {
+				"type": { "const": "perspective" },
+				"fieldOfViewDegrees": { "type": "number", "minimum": 5, "maximum": 170 }
+			}
+		},
+		"orthographicProjection": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["type", "orthoWidth"],
+			"properties": {
+				"type": { "const": "orthographic" },
+				"orthoWidth": { "type": "number", "exclusiveMinimum": 0 }
+			}
+		},
+		"correlation": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["type", "candidateId"],
+					"properties": {
+						"type": { "const": "framing_candidate" },
+						"candidateId": { "$ref": "#/$defs/identifier" }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["type", "reviewViewId"],
+					"properties": {
+						"type": { "const": "review_view" },
+						"reviewViewId": { "$ref": "#/$defs/identifier" }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["type", "mapCapturePlanId"],
+					"properties": {
+						"type": { "const": "map_capture_plan" },
+						"mapCapturePlanId": { "$ref": "#/$defs/identifier" }
+					}
+				}
+			]
+		},
+		"identifier": {
+			"type": "string",
+			"minLength": 1,
+			"maxLength": 128,
+			"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+		},
 		"vector": {
 			"type": "object",
 			"additionalProperties": false,

package/contracts/cameras/v1/README.md

@@ -20,9 +20,9 @@ frames from an old session are disposable.
 |     40 | f64     | Unreal world seconds at capture request              |
 |     48 | f64     | producer monotonic milliseconds at capture request   |
 |     56 | f64     | GPU readback latency in milliseconds                 |
-|     64 | u8[16]  | producer ID                                          |
-|     80 | u8[16]  | session ID                                           |
-|     96 | u8[16]  | camera ID                                            |
+|     64 | u32[4]  | producer FGuid words, each little-endian             |
+|     80 | u32[4]  | session FGuid words, each little-endian              |
+|     96 | u32[4]  | camera FGuid words, each little-endian               |
 |    112 | u32     | cumulative readback/staging drops                    |
 |    116 | u32     | cumulative latest-frame transport replacements       |
 |    120 | u32     | reserved, zero                                       |
@@ -31,3 +31,6 @@ frames from an old session are disposable.
 The payload is top-to-bottom, tightly packed BGRA8. Live buffers are bounded and latest-frame-wins;
 sequence gaps are expected and observable. The control plane owns camera listing, schedule tuning,
 pause/focus, and health. This binary stream never carries durable evidence.
+
+To compare an ID with Unreal's `FGuid::ToString(EGuidFormats::Digits)` output, read the four
+little-endian `u32` words and concatenate them as four zero-padded, eight-digit hexadecimal values.

package/contracts/editor-world/v1/README.md

@@ -0,0 +1,10 @@
+# Unreal editor world-control contract v1
+
+This contract lets a trusted external client open one explicit `/Game/` map in Unreal Editor
+without player input. The operation never saves, discards, or prompts over dirty work. It returns
+`already_open` when the target is current and otherwise rejects active play sessions, dirty world
+packages, missing maps, and failed loads as typed outcomes.
+
+`request.schema.json` and `response.schema.json` are the language-neutral authority shared by
+`@ue-shed/protocol` and `UEShedCoreEditor`. The companion advertises
+`editor.world-control.v1` and its reflected object path before clients may invoke the operation.

package/contracts/editor-world/v1/request.schema.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/editor-world/v1/request.schema.json",
+	"title": "UE Shed editor world open request v1.0",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["contract", "operationId", "targetMapPath"],
+	"properties": {
+		"contract": { "$ref": "response.schema.json#/$defs/contract" },
+		"operationId": {
+			"type": "string",
+			"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+		},
+		"targetMapPath": { "$ref": "response.schema.json#/$defs/gameMapPath" }
+	}
+}

package/contracts/editor-world/v1/response.schema.json

@@ -0,0 +1,93 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/editor-world/v1/response.schema.json",
+	"title": "UE Shed editor world open response v1.0",
+	"oneOf": [
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["after", "before", "contract", "operationId", "outcome", "targetMapPath"],
+			"properties": {
+				"after": { "$ref": "#/$defs/snapshot" },
+				"before": { "$ref": "#/$defs/snapshot" },
+				"contract": { "$ref": "#/$defs/contract" },
+				"operationId": { "$ref": "#/$defs/operationId" },
+				"outcome": { "enum": ["opened", "already_open"] },
+				"targetMapPath": { "$ref": "#/$defs/gameMapPath" }
+			}
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"after",
+				"before",
+				"code",
+				"contract",
+				"message",
+				"operationId",
+				"outcome",
+				"recovery",
+				"retrySafe",
+				"targetMapPath"
+			],
+			"properties": {
+				"after": { "$ref": "#/$defs/snapshot" },
+				"before": { "$ref": "#/$defs/snapshot" },
+				"code": {
+					"enum": [
+						"dirty_world",
+						"invalid_request",
+						"map_not_found",
+						"open_failed",
+						"play_session_active",
+						"unavailable"
+					]
+				},
+				"contract": { "$ref": "#/$defs/contract" },
+				"message": { "type": "string" },
+				"operationId": { "$ref": "#/$defs/operationId" },
+				"outcome": { "const": "rejected" },
+				"recovery": { "type": "string" },
+				"retrySafe": { "type": "boolean" },
+				"targetMapPath": { "$ref": "#/$defs/gameMapPath" }
+			}
+		}
+	],
+	"$defs": {
+		"contract": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "version"],
+			"properties": {
+				"name": { "const": "unreal-editor-world-control" },
+				"version": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["major", "minor"],
+					"properties": { "major": { "const": 1 }, "minor": { "const": 0 } }
+				}
+			}
+		},
+		"mapPath": { "type": "string", "pattern": "^/[A-Za-z0-9_./-]+$" },
+		"gameMapPath": { "type": "string", "pattern": "^/Game/[A-Za-z0-9_./-]+$" },
+		"operationId": {
+			"type": "string",
+			"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+		},
+		"snapshot": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["dirtyWorldPackages", "playSessionActive"],
+			"properties": {
+				"dirtyWorldPackages": {
+					"type": "array",
+					"maxItems": 256,
+					"items": { "$ref": "#/$defs/mapPath" }
+				},
+				"mapPath": { "$ref": "#/$defs/mapPath" },
+				"playSessionActive": { "type": "boolean" }
+			}
+		}
+	}
+}