@ue-shed/protocol 0.5.1 → 0.6.0

package/contracts/cameras/map-tile/v1/README.md

@@ -14,14 +14,28 @@ capture Z does not define detail. The editor renders `gutterPixels` beyond each
 units-per-pixel and crops back to `tilePixelSize` before PNG encoding. Consumers use clamp-to-edge
 sampling inside each published tile.
 
-`captureBackend` is an optional execution hint, not part of the portable plan. Its default
-`scene_capture_tiles` behavior remains the v1 tile operation. The experimental
-`viewport_high_resolution` value requires one complete zoom level of at most 64 tiles; Unreal
-renders that level through the active Level Editor viewport's High Resolution Screenshot path and
-then cuts the resulting image into the requested tiles.
+`captureBackend` is an optional execution hint, not part of the portable plan. The default is
+`lit_camera_tiles`, requiring `cameras.lit-map-tile-capture.v1` and an unlocked rendering editor
+viewport. It accepts `full_fidelity` with natural LOD. `overviewBounds` supplies the complete run's
+framing for shared exposure calibration; when omitted the first batch's extent is used. Optional
+`capture.render.exposureEV100` pins the camera exposure range instead of calibrating automatically.
+
+Call `BeginMapTileCapture(RequestJson)` to start a batch, then
+`PollMapTileCapture(RunId, OperationId)` until `capture-operation.schema.json` reports `finished`.
+The terminal `response` uses the existing capture-response schema. Polling renews a 120-second
+inactivity lease. A run retains viewport, exposure, and scene-freeze ownership between batches;
+call `EndMapTileCapture(RunId)` in a finalizer on success, failure, and cancellation. End returns
+`{ "released": boolean }`; an unrelated run ID cannot release the owner. Only one batch runs at a
+time, and a run's map and capture policy cannot change between batches.
+
+Explicit `scene_capture_tiles` and `viewport_high_resolution` use the synchronous `CaptureMapTiles`
+operation. The latter requires one complete zoom level of at most 64 tiles. The former retains
+SceneCapture profiles and per-level LOD distance scales. Both reject manual exposure rather than
+silently ignoring it. Synchronous `CaptureMapTiles` rejects the default Lit backend and directs
+clients to the asynchronous lifecycle.
 
 The editor accepts no output path. It stages only below `Saved/UEShed/MapTileStaging`, reports every
-tile outcome and map package dirty state, and restores transient state before returning. The host
+tile outcome and map package dirty state, and restores transient state when run ownership ends. The host
 must validate staging containment, hash artifacts, and atomically publish only a manifest whose
 state is `complete` and whose tile inventory is exhaustive. Partial and cancelled attempts remain
 diagnostic evidence and are never discoverable as completed runs.

package/contracts/cameras/map-tile/v1/capture-operation.schema.json

@@ -0,0 +1,69 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/map-tile/v1/capture-operation.schema.json",
+	"title": "UE Shed asynchronous map tile operation v1",
+	"oneOf": [
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["state", "operationId", "completedTiles"],
+			"properties": {
+				"state": {
+					"const": "running"
+				},
+				"operationId": {
+					"$ref": "plan.schema.json#/$defs/id"
+				},
+				"completedTiles": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 64
+				},
+				"phase": {
+					"enum": ["exposure_warmup", "tile_warmup", "capturing"]
+				},
+				"elapsedMs": {
+					"type": "number",
+					"minimum": 0
+				},
+				"totalTiles": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 64
+				},
+				"currentTile": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["zoom", "row", "column"],
+					"properties": {
+						"zoom": {
+							"type": "integer",
+							"minimum": 0
+						},
+						"row": {
+							"type": "integer",
+							"minimum": 0
+						},
+						"column": {
+							"type": "integer",
+							"minimum": 0
+						}
+					}
+				}
+			}
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["state", "response"],
+			"properties": {
+				"state": {
+					"const": "finished"
+				},
+				"response": {
+					"$ref": "capture-response.schema.json"
+				}
+			}
+		}
+	]
+}

package/contracts/cameras/map-tile/v1/capture-request.schema.json

@@ -19,8 +19,9 @@
 	"properties": {
 		"capture": { "$ref": "plan.schema.json#/$defs/capturePolicy" },
 		"captureBackend": {
-			"enum": ["scene_capture_tiles", "viewport_high_resolution"]
+			"enum": ["lit_camera_tiles", "scene_capture_tiles", "viewport_high_resolution"]
 		},
+		"overviewBounds": { "$ref": "plan.schema.json#/$defs/bounds" },
 		"contract": {
 			"type": "object",
 			"additionalProperties": false,

package/contracts/cameras/map-tile/v1/fixtures/capture-operation-finished-valid.json

@@ -0,0 +1,41 @@
+{
+	"state": "finished",
+	"response": {
+		"actualMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+		"contract": {
+			"name": "ue-shed-map-tile-capture",
+			"version": {
+				"major": 1,
+				"minor": 0
+			}
+		},
+		"correlationId": "fixture-correlation",
+		"dirtyState": {
+			"before": false,
+			"after": false
+		},
+		"durationMs": 27.5,
+		"operationId": "fixture-operation",
+		"results": [
+			{
+				"bytes": 1234,
+				"captureDurationMs": 20.25,
+				"height": 256,
+				"key": {
+					"zoom": 0,
+					"row": 0,
+					"column": 0
+				},
+				"stagedPath": "C:/Project/Saved/UEShed/MapTileStaging/fixture-run/Z00/R000_C000.png",
+				"status": "captured",
+				"width": 256
+			}
+		],
+		"status": "completed",
+		"tileCounts": {
+			"failed": 0,
+			"requested": 1,
+			"succeeded": 1
+		}
+	}
+}

package/contracts/cameras/map-tile/v1/fixtures/capture-operation-progress-valid.json

@@ -0,0 +1,13 @@
+{
+	"state": "running",
+	"operationId": "fixture-operation",
+	"completedTiles": 0,
+	"phase": "tile_warmup",
+	"elapsedMs": 1234,
+	"totalTiles": 4,
+	"currentTile": {
+		"zoom": 0,
+		"row": 0,
+		"column": 0
+	}
+}

package/contracts/cameras/map-tile/v1/fixtures/capture-operation-running-valid.json

@@ -0,0 +1,5 @@
+{
+	"state": "running",
+	"operationId": "fixture-operation",
+	"completedTiles": 0
+}

package/contracts/cameras/map-tile/v1/fixtures/capture-request-lit-valid.json

@@ -0,0 +1,59 @@
+{
+	"capture": {
+		"dataLayers": {
+			"mode": "unchanged"
+		},
+		"orientation": {
+			"pitch": -90,
+			"roll": 0,
+			"yaw": 0
+		},
+		"render": {
+			"effects": {
+				"fog": false,
+				"volumetricFog": false
+			},
+			"lodPolicy": "natural",
+			"profile": "full_fidelity",
+			"exposureEV100": -5
+		},
+		"z": 5000
+	},
+	"captureBackend": "lit_camera_tiles",
+	"contract": {
+		"name": "ue-shed-map-tile-capture",
+		"version": {
+			"major": 1,
+			"minor": 0
+		}
+	},
+	"correlationId": "fixture-correlation",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"gutterPixels": 2,
+	"operationId": "fixture-operation",
+	"planId": "fixture-overview",
+	"runId": "fixture-run",
+	"tilePixelSize": 256,
+	"tiles": [
+		{
+			"key": {
+				"zoom": 0,
+				"row": 0,
+				"column": 0
+			},
+			"unitsPerPixel": 4,
+			"worldBounds": {
+				"minX": 1024,
+				"minY": -1024,
+				"maxX": 2048,
+				"maxY": 0
+			}
+		}
+	],
+	"overviewBounds": {
+		"minX": 1024,
+		"minY": -1024,
+		"maxX": 2048,
+		"maxY": 0
+	}
+}

package/contracts/cameras/map-tile/v1/fixtures/readiness-blocked.json

@@ -0,0 +1,11 @@
+{
+	"schemaVersion": 1,
+	"backend": "lit_camera_tiles",
+	"ready": false,
+	"blockers": [
+		{
+			"code": "viewport_locked",
+			"message": "Unlock the viewport."
+		}
+	]
+}

package/contracts/cameras/map-tile/v1/fixtures/readiness-ready.json

@@ -0,0 +1,7 @@
+{
+	"schemaVersion": 1,
+	"backend": "lit_camera_tiles",
+	"ready": true,
+	"actualMapPath": "/Game/Fixture/Map",
+	"blockers": []
+}

package/contracts/cameras/map-tile/v1/fixtures/selection-ready.json

@@ -0,0 +1,21 @@
+{
+	"schemaVersion": 1,
+	"status": "ready",
+	"mapPath": "/Game/Fixture/Map",
+	"bounds": {
+		"minX": -100,
+		"maxX": 100,
+		"minY": 50,
+		"maxY": 250,
+		"minZ": 0,
+		"maxZ": 400
+	},
+	"actors": [
+		{
+			"path": "/Game/Fixture/Map.A",
+			"label": "A",
+			"actorGuid": "00000001000000020000000300000004"
+		}
+	],
+	"skippedActorPaths": []
+}

package/contracts/cameras/map-tile/v1/fixtures/selection-unavailable.json

@@ -0,0 +1,6 @@
+{
+	"schemaVersion": 1,
+	"status": "unavailable",
+	"code": "selection_limit",
+	"message": "Select between 1 and 1024 actors."
+}

package/contracts/cameras/map-tile/v1/inspection.md

@@ -0,0 +1,16 @@
+# Capture inspection v1
+
+`InspectMapCaptureSelection` requires `cameras.capture-selection.v1`. It reads selection in the
+current editor world, rejects PIE and selections outside 1–1024 actors, and combines finite component
+bounds. `skippedActorPaths` identifies actors without usable bounds or in another world. Ready bounds
+must satisfy min <= max on every axis; planar/point selections are valid. Host plan fitting supplies
+positive XY extent. The operation neither modifies selection nor loads additional regions.
+
+`InspectMapCaptureReadiness(ExpectedMapPath)` requires `cameras.capture-readiness.v1` and applies to
+Lit capture. `ready` is true exactly when `blockers` is empty. It checks map identity, rendering,
+streaming, viewport locking/overrides, screenshot use, PIE and capture ownership. It does not reserve
+resources, load regions, or guarantee visual completeness. Capture execution repeats shared checks.
+
+The running operation's optional phase/elapsed/count/current-tile fields are telemetry for the current
+batch. `currentTile` is absent during whole-map exposure warmup. Existing responses without these
+fields remain valid. Terminal responses and publication rules are unchanged.

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

@@ -130,6 +130,7 @@
 					"additionalProperties": false,
 					"required": ["effects", "lodPolicy", "profile"],
 					"properties": {
+						"exposureEV100": { "type": "number", "minimum": -20, "maximum": 30 },
 						"effects": {
 							"type": "object",
 							"additionalProperties": false,

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

@@ -0,0 +1,39 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schemaVersion", "backend", "ready", "blockers"],
+	"properties": {
+		"schemaVersion": {
+			"const": 1
+		},
+		"backend": {
+			"const": "lit_camera_tiles"
+		},
+		"ready": {
+			"type": "boolean"
+		},
+		"actualMapPath": {
+			"type": "string",
+			"minLength": 1
+		},
+		"blockers": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["code", "message"],
+				"properties": {
+					"code": {
+						"type": "string",
+						"minLength": 1
+					},
+					"message": {
+						"type": "string",
+						"minLength": 1
+					}
+				}
+			}
+		}
+	}
+}

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

@@ -0,0 +1,105 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"oneOf": [
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"schemaVersion",
+				"status",
+				"mapPath",
+				"bounds",
+				"actors",
+				"skippedActorPaths"
+			],
+			"properties": {
+				"schemaVersion": {
+					"const": 1
+				},
+				"status": {
+					"const": "ready"
+				},
+				"mapPath": {
+					"type": "string",
+					"minLength": 1
+				},
+				"bounds": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["minX", "maxX", "minY", "maxY", "minZ", "maxZ"],
+					"properties": {
+						"minX": {
+							"type": "number"
+						},
+						"maxX": {
+							"type": "number"
+						},
+						"minY": {
+							"type": "number"
+						},
+						"maxY": {
+							"type": "number"
+						},
+						"minZ": {
+							"type": "number"
+						},
+						"maxZ": {
+							"type": "number"
+						}
+					}
+				},
+				"actors": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["path", "label"],
+						"properties": {
+							"path": {
+								"type": "string",
+								"minLength": 1
+							},
+							"label": {
+								"type": "string"
+							},
+							"actorGuid": {
+								"type": "string",
+								"pattern": "^[0-9A-Fa-f]{32}$"
+							}
+						}
+					},
+					"minItems": 1,
+					"maxItems": 1024
+				},
+				"skippedActorPaths": {
+					"type": "array",
+					"items": {
+						"type": "string"
+					},
+					"maxItems": 1024
+				}
+			}
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["schemaVersion", "status", "code", "message"],
+			"properties": {
+				"schemaVersion": {
+					"const": 1
+				},
+				"status": {
+					"const": "unavailable"
+				},
+				"code": {
+					"type": "string",
+					"minLength": 1
+				},
+				"message": {
+					"type": "string",
+					"minLength": 1
+				}
+			}
+		}
+	]
+}

package/contracts/core/v1/producer-identity.schema.json

@@ -0,0 +1,44 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["engineVersion", "processId", "sessionId", "plugins"],
+	"properties": {
+		"engineVersion": {
+			"type": "string",
+			"minLength": 1
+		},
+		"processId": {
+			"type": "integer",
+			"minimum": 1
+		},
+		"sessionId": {
+			"type": "string",
+			"minLength": 1
+		},
+		"plugins": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["name", "version", "loadedModules"],
+				"properties": {
+					"name": {
+						"type": "string",
+						"minLength": 1
+					},
+					"version": {
+						"type": "string"
+					},
+					"loadedModules": {
+						"type": "array",
+						"items": {
+							"type": "string",
+							"minLength": 1
+						}
+					}
+				}
+			}
+		}
+	}
+}