@ue-shed/protocol 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,7 +17,15 @@ visibility measurement: the plugin reports what it observed and does not assign
17
17
  original engine-produced classification. Minor version 4 adds one optional Clear companion to the
18
18
  same capture operation. Its request carries only an effective producer instruction (`isolate_target`
19
19
  or bounded `hide_explicit` actor paths); consumer policy, thresholds, and presentation remain
20
- outside the wire contract.
20
+ outside the wire contract. Minor version 5 adds the durable `actor_guid` subject locator. The GUID
21
+ is Unreal's authored actor GUID (`FGuid::UniqueObjectGuid`); a last-known actor path is diagnostic
22
+ evidence only and is never used as an identity fallback.
23
+
24
+ Producers accept every complete, schema-valid 1.x request through the highest minor they advertise.
25
+ They echo the accepted request minor in both success and failure responses. Missing, fractional,
26
+ negative, or future minors; unknown major versions; minor-feature contradictions; and excess fields
27
+ are rejected deterministically. Once a request supplies an operation ID and view ID, a structured
28
+ failure retains those identities even when contract negotiation fails.
21
29
 
22
30
  The editor resolves an actor-relative pose atomically from the actor's current transform. Its
23
31
  response records the resolved target, exact effective world pose, projection, bounded visibility
@@ -18,23 +18,53 @@
18
18
  "required": ["major", "minor"],
19
19
  "properties": {
20
20
  "major": { "const": 1 },
21
- "minor": { "type": "integer", "minimum": 0, "maximum": 4 }
21
+ "minor": { "type": "integer", "minimum": 0, "maximum": 5 }
22
22
  }
23
23
  }
24
24
  }
25
25
  },
26
- "operationId": { "type": "string", "format": "uuid" },
26
+ "operationId": {
27
+ "type": "string",
28
+ "format": "uuid",
29
+ "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
30
+ "not": { "const": "00000000-0000-0000-0000-000000000000" }
31
+ },
27
32
  "viewId": { "$ref": "#/$defs/safeId" },
28
33
  "expectedMapPath": { "type": "string", "minLength": 1 },
29
34
  "subject": {
30
35
  "oneOf": [
36
+ {
37
+ "type": "object",
38
+ "additionalProperties": false,
39
+ "required": ["kind", "actorGuid"],
40
+ "properties": {
41
+ "kind": { "const": "actor_guid" },
42
+ "actorGuid": {
43
+ "type": "string",
44
+ "pattern": "^[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{8}){3}$",
45
+ "not": { "const": "00000000-00000000-00000000-00000000" }
46
+ },
47
+ "lastKnownActorPath": {
48
+ "type": "string",
49
+ "minLength": 7,
50
+ "maxLength": 4096,
51
+ "pattern": "^/Game/"
52
+ },
53
+ "diagnosticLabel": { "type": "string", "minLength": 1 }
54
+ }
55
+ },
31
56
  {
32
57
  "type": "object",
33
58
  "additionalProperties": false,
34
59
  "required": ["kind", "actorPath"],
35
60
  "properties": {
36
61
  "kind": { "const": "actor_path" },
37
- "actorPath": { "type": "string", "minLength": 1 },
62
+ "actorPath": {
63
+ "type": "string",
64
+ "minLength": 7,
65
+ "maxLength": 4096,
66
+ "pattern": "^/Game/"
67
+ },
38
68
  "diagnosticLabel": { "type": "string", "minLength": 1 }
39
69
  }
40
70
  },
@@ -80,7 +110,7 @@
80
110
  "properties": {
81
111
  "contract": {
82
112
  "properties": {
83
- "version": { "properties": { "minor": { "enum": [2, 3, 4] } } }
113
+ "version": { "properties": { "minor": { "enum": [2, 3, 4, 5] } } }
84
114
  }
85
115
  }
86
116
  }
@@ -93,13 +123,32 @@
93
123
  "properties": {
94
124
  "contract": {
95
125
  "properties": {
96
- "version": { "properties": { "minor": { "const": 4 } } }
126
+ "version": { "properties": { "minor": { "enum": [4, 5] } } }
97
127
  }
98
128
  }
99
129
  }
100
130
  },
101
131
  "then": { "required": ["clearCompanion"] },
102
132
  "else": { "not": { "required": ["clearCompanion"] } }
133
+ },
134
+ {
135
+ "if": {
136
+ "properties": {
137
+ "subject": {
138
+ "required": ["kind"],
139
+ "properties": { "kind": { "const": "actor_guid" } }
140
+ }
141
+ }
142
+ },
143
+ "then": {
144
+ "properties": {
145
+ "contract": {
146
+ "properties": {
147
+ "version": { "properties": { "minor": { "const": 5 } } }
148
+ }
149
+ }
150
+ }
151
+ }
103
152
  }
104
153
  ],
105
154
  "$defs": {
@@ -46,7 +46,28 @@
46
46
  "mapPackageDirtyAfter": { "type": "boolean" },
47
47
  "subjectProjection": { "$ref": "#/$defs/subjectProjection" },
48
48
  "visibility": { "$ref": "#/$defs/visibilityMeasurement" }
49
- }
49
+ },
50
+ "allOf": [
51
+ {
52
+ "if": {
53
+ "properties": {
54
+ "resolvedSubject": {
55
+ "required": ["kind"],
56
+ "properties": { "kind": { "const": "actor_guid" } }
57
+ }
58
+ }
59
+ },
60
+ "then": {
61
+ "properties": {
62
+ "contract": {
63
+ "properties": {
64
+ "version": { "properties": { "minor": { "const": 5 } } }
65
+ }
66
+ }
67
+ }
68
+ }
69
+ }
70
+ ]
50
71
  },
51
72
  {
52
73
  "type": "object",
@@ -73,7 +94,7 @@
73
94
  "status": { "const": "captured" },
74
95
  "operationId": { "type": "string", "minLength": 1 },
75
96
  "viewId": { "$ref": "#/$defs/safeId" },
76
- "resolvedSubject": { "$ref": "#/$defs/resolvedSubject" },
97
+ "resolvedSubject": { "$ref": "#/$defs/resolvedSubjectPrevious" },
77
98
  "effectiveWorldPose": { "$ref": "#/$defs/pose" },
78
99
  "mapPath": { "type": "string", "minLength": 1 },
79
100
  "stagingPath": { "type": "string", "minLength": 1 },
@@ -111,7 +132,7 @@
111
132
  "status": { "const": "captured" },
112
133
  "operationId": { "type": "string", "minLength": 1 },
113
134
  "viewId": { "$ref": "#/$defs/safeId" },
114
- "resolvedSubject": { "$ref": "#/$defs/resolvedSubject" },
135
+ "resolvedSubject": { "$ref": "#/$defs/resolvedSubjectPrevious" },
115
136
  "effectiveWorldPose": { "$ref": "#/$defs/pose" },
116
137
  "mapPath": { "type": "string", "minLength": 1 },
117
138
  "stagingPath": { "type": "string", "minLength": 1 },
@@ -216,7 +237,7 @@
216
237
  "required": ["major", "minor"],
217
238
  "properties": {
218
239
  "major": { "const": 1 },
219
- "minor": { "const": 4 }
240
+ "minor": { "enum": [4, 5] }
220
241
  }
221
242
  }
222
243
  }
@@ -267,7 +288,7 @@
267
288
  "required": ["major", "minor"],
268
289
  "properties": {
269
290
  "major": { "const": 1 },
270
- "minor": { "type": "integer", "minimum": 0, "maximum": 4 }
291
+ "minor": { "type": "integer", "minimum": 0, "maximum": 5 }
271
292
  }
272
293
  }
273
294
  }
@@ -316,6 +337,60 @@
316
337
  }
317
338
  },
318
339
  "resolvedSubject": {
340
+ "oneOf": [
341
+ {
342
+ "type": "object",
343
+ "additionalProperties": false,
344
+ "required": ["kind", "actorGuid", "actorPath", "transform"],
345
+ "properties": {
346
+ "kind": { "const": "actor_guid" },
347
+ "actorGuid": {
348
+ "type": "string",
349
+ "pattern": "^[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{8}){3}$",
350
+ "not": { "const": "00000000-00000000-00000000-00000000" }
351
+ },
352
+ "actorPath": { "type": "string", "minLength": 1 },
353
+ "transform": {
354
+ "type": "object",
355
+ "additionalProperties": false,
356
+ "required": ["location", "rotation"],
357
+ "properties": {
358
+ "location": { "$ref": "#/$defs/vector" },
359
+ "rotation": { "$ref": "#/$defs/rotation" }
360
+ }
361
+ }
362
+ }
363
+ },
364
+ {
365
+ "type": "object",
366
+ "additionalProperties": false,
367
+ "required": ["kind", "actorPath", "transform"],
368
+ "properties": {
369
+ "kind": { "const": "actor_path" },
370
+ "actorPath": { "type": "string", "minLength": 1 },
371
+ "transform": {
372
+ "type": "object",
373
+ "additionalProperties": false,
374
+ "required": ["location", "rotation"],
375
+ "properties": {
376
+ "location": { "$ref": "#/$defs/vector" },
377
+ "rotation": { "$ref": "#/$defs/rotation" }
378
+ }
379
+ }
380
+ }
381
+ },
382
+ {
383
+ "type": "object",
384
+ "additionalProperties": false,
385
+ "required": ["kind", "bounds"],
386
+ "properties": {
387
+ "kind": { "const": "oriented_bounds" },
388
+ "bounds": { "$ref": "#/$defs/bounds" }
389
+ }
390
+ }
391
+ ]
392
+ },
393
+ "resolvedSubjectPrevious": {
319
394
  "oneOf": [
320
395
  {
321
396
  "type": "object",
@@ -0,0 +1,53 @@
1
+ {
2
+ "contract": {
3
+ "name": "ue-shed-review-capture",
4
+ "version": { "major": 1, "minor": 5 }
5
+ },
6
+ "status": "captured",
7
+ "operationId": "capture-guid",
8
+ "viewId": "structure-guid-context",
9
+ "resolvedSubject": {
10
+ "kind": "actor_guid",
11
+ "actorGuid": "00000001-00000002-00000003-00000004",
12
+ "actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
13
+ "transform": {
14
+ "location": { "x": 100, "y": 200, "z": 300 },
15
+ "rotation": { "pitch": 0, "yaw": 45, "roll": 0 }
16
+ }
17
+ },
18
+ "effectiveWorldPose": {
19
+ "aspectRatio": "16:9",
20
+ "fieldOfViewDegrees": 70,
21
+ "projection": "perspective",
22
+ "location": { "x": 1200, "y": -900, "z": 700 },
23
+ "rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
24
+ },
25
+ "mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
26
+ "stagedArtifacts": [
27
+ {
28
+ "variant": "pure",
29
+ "stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-guid/pure.png"
30
+ }
31
+ ],
32
+ "clearCompanion": { "status": "not_requested" },
33
+ "width": 1280,
34
+ "height": 720,
35
+ "captureDurationMs": 21.5,
36
+ "mapPackageDirtyBefore": false,
37
+ "mapPackageDirtyAfter": false,
38
+ "subjectProjection": {
39
+ "status": "projected",
40
+ "viewportStatus": "fully_within_viewport",
41
+ "normalizedBounds": { "minX": 0.2, "minY": 0.2, "maxX": 0.8, "maxY": 0.8 },
42
+ "margins": { "left": 0.2, "right": 0.2, "top": 0.2, "bottom": 0.2 }
43
+ },
44
+ "visibility": {
45
+ "status": "assessed",
46
+ "method": { "method": "depth_compare", "version": 1 },
47
+ "visibleFraction": 1,
48
+ "sampleCount": 6400,
49
+ "assessmentDurationMs": 1.5,
50
+ "limitations": ["Bounded depth comparison."],
51
+ "occluders": []
52
+ }
53
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "contract": {
3
+ "name": "ue-shed-review-capture",
4
+ "version": { "major": 1, "minor": 5 }
5
+ },
6
+ "operationId": "55555555-5555-4555-8555-555555555555",
7
+ "viewId": "structure-guid-context",
8
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
9
+ "subject": {
10
+ "kind": "actor_guid",
11
+ "actorGuid": "00000001-00000002-00000003-00000004",
12
+ "lastKnownActorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
13
+ "diagnosticLabel": "ReviewSubject"
14
+ },
15
+ "viewpoint": {
16
+ "kind": "world_fixed",
17
+ "approvedPose": {
18
+ "aspectRatio": "16:9",
19
+ "fieldOfViewDegrees": 70,
20
+ "projection": "perspective",
21
+ "location": { "x": 100, "y": 200, "z": 300 },
22
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
23
+ }
24
+ },
25
+ "resolution": { "width": 1280, "height": 720 },
26
+ "assessment": { "method": "automatic" },
27
+ "clearCompanion": { "status": "not_requested" }
28
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "contract": { "name": "ue-shed-review-capture", "version": { "major": 1, "minor": 5 } },
3
+ "operationId": "55555555-5555-4555-8555-555555555555",
4
+ "viewId": "alternate-actor-guid",
5
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
6
+ "subject": {
7
+ "kind": "actor_guid",
8
+ "actorGuid": "12345678-1234-1234-1234-123456789abc"
9
+ },
10
+ "viewpoint": {
11
+ "kind": "world_fixed",
12
+ "approvedPose": {
13
+ "aspectRatio": "16:9",
14
+ "fieldOfViewDegrees": 70,
15
+ "projection": "perspective",
16
+ "location": { "x": 100, "y": 200, "z": 300 },
17
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
18
+ }
19
+ },
20
+ "resolution": { "width": 1280, "height": 720 },
21
+ "assessment": { "method": "automatic" },
22
+ "clearCompanion": { "status": "not_requested" }
23
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "contract": {
3
+ "name": "ue-shed-review-capture",
4
+ "version": { "major": 1, "minor": 2 }
5
+ },
6
+ "operationId": "55555555-5555-4555-8555-555555555555",
7
+ "viewId": "clear-on-old-minor",
8
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
9
+ "subject": {
10
+ "kind": "actor_path",
11
+ "actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject"
12
+ },
13
+ "viewpoint": {
14
+ "kind": "world_fixed",
15
+ "approvedPose": {
16
+ "aspectRatio": "16:9",
17
+ "fieldOfViewDegrees": 70,
18
+ "projection": "perspective",
19
+ "location": { "x": 100, "y": 200, "z": 300 },
20
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
21
+ }
22
+ },
23
+ "resolution": { "width": 1280, "height": 720 },
24
+ "assessment": { "method": "automatic" },
25
+ "clearCompanion": { "status": "not_requested" }
26
+ }
@@ -0,0 +1,24 @@
1
+ {
2
+ "contract": { "name": "ue-shed-review-capture", "version": { "major": 1, "minor": 5 } },
3
+ "operationId": "55555555-5555-4555-8555-555555555555",
4
+ "viewId": "empty-diagnostic-label",
5
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
6
+ "subject": {
7
+ "kind": "actor_guid",
8
+ "actorGuid": "00000001-00000002-00000003-00000004",
9
+ "diagnosticLabel": ""
10
+ },
11
+ "viewpoint": {
12
+ "kind": "world_fixed",
13
+ "approvedPose": {
14
+ "aspectRatio": "16:9",
15
+ "fieldOfViewDegrees": 70,
16
+ "projection": "perspective",
17
+ "location": { "x": 100, "y": 200, "z": 300 },
18
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
19
+ }
20
+ },
21
+ "resolution": { "width": 1280, "height": 720 },
22
+ "assessment": { "method": "automatic" },
23
+ "clearCompanion": { "status": "not_requested" }
24
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "contract": {
3
+ "name": "ue-shed-review-capture",
4
+ "version": { "major": 1, "minor": 6 }
5
+ },
6
+ "operationId": "55555555-5555-4555-8555-555555555555",
7
+ "viewId": "future-minor",
8
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
9
+ "subject": {
10
+ "kind": "actor_guid",
11
+ "actorGuid": "00000001-00000002-00000003-00000004"
12
+ },
13
+ "viewpoint": {
14
+ "kind": "world_fixed",
15
+ "approvedPose": {
16
+ "aspectRatio": "16:9",
17
+ "fieldOfViewDegrees": 70,
18
+ "projection": "perspective",
19
+ "location": { "x": 100, "y": 200, "z": 300 },
20
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
21
+ }
22
+ },
23
+ "resolution": { "width": 1280, "height": 720 },
24
+ "assessment": { "method": "automatic" },
25
+ "clearCompanion": { "status": "not_requested" }
26
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "contract": {
3
+ "name": "ue-shed-review-capture",
4
+ "version": { "major": 1, "minor": 4 }
5
+ },
6
+ "operationId": "55555555-5555-4555-8555-555555555555",
7
+ "viewId": "guid-on-old-minor",
8
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
9
+ "subject": {
10
+ "kind": "actor_guid",
11
+ "actorGuid": "00000001-00000002-00000003-00000004"
12
+ },
13
+ "viewpoint": {
14
+ "kind": "world_fixed",
15
+ "approvedPose": {
16
+ "aspectRatio": "16:9",
17
+ "fieldOfViewDegrees": 70,
18
+ "projection": "perspective",
19
+ "location": { "x": 100, "y": 200, "z": 300 },
20
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
21
+ }
22
+ },
23
+ "resolution": { "width": 1280, "height": 720 },
24
+ "assessment": { "method": "automatic" },
25
+ "clearCompanion": { "status": "not_requested" }
26
+ }
@@ -0,0 +1,24 @@
1
+ {
2
+ "contract": { "name": "ue-shed-review-capture", "version": { "major": 1, "minor": 5 } },
3
+ "operationId": "55555555-5555-4555-8555-555555555555",
4
+ "viewId": "malformed-last-known-path",
5
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
6
+ "subject": {
7
+ "kind": "actor_guid",
8
+ "actorGuid": "00000001-00000002-00000003-00000004",
9
+ "lastKnownActorPath": 42
10
+ },
11
+ "viewpoint": {
12
+ "kind": "world_fixed",
13
+ "approvedPose": {
14
+ "aspectRatio": "16:9",
15
+ "fieldOfViewDegrees": 70,
16
+ "projection": "perspective",
17
+ "location": { "x": 100, "y": 200, "z": 300 },
18
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
19
+ }
20
+ },
21
+ "resolution": { "width": 1280, "height": 720 },
22
+ "assessment": { "method": "automatic" },
23
+ "clearCompanion": { "status": "not_requested" }
24
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "contract": { "name": "ue-shed-review-capture", "version": { "major": 1, "minor": 5 } },
3
+ "operationId": "66666666-6666-4666-8666-666666666666",
4
+ "viewId": "nil-actor-guid",
5
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
6
+ "subject": {
7
+ "kind": "actor_guid",
8
+ "actorGuid": "00000000-00000000-00000000-00000000"
9
+ },
10
+ "viewpoint": {
11
+ "kind": "world_fixed",
12
+ "approvedPose": {
13
+ "aspectRatio": "16:9",
14
+ "fieldOfViewDegrees": 70,
15
+ "projection": "perspective",
16
+ "location": { "x": 100, "y": 200, "z": 300 },
17
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
18
+ }
19
+ },
20
+ "resolution": { "width": 1280, "height": 720 },
21
+ "assessment": { "method": "automatic" },
22
+ "clearCompanion": { "status": "not_requested" }
23
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "contract": { "name": "ue-shed-review-capture", "version": { "major": 1, "minor": 5 } },
3
+ "operationId": "00000000-0000-0000-0000-000000000000",
4
+ "viewId": "nil-operation-id",
5
+ "expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
6
+ "subject": {
7
+ "kind": "actor_guid",
8
+ "actorGuid": "00000001-00000002-00000003-00000004"
9
+ },
10
+ "viewpoint": {
11
+ "kind": "world_fixed",
12
+ "approvedPose": {
13
+ "aspectRatio": "16:9",
14
+ "fieldOfViewDegrees": 70,
15
+ "projection": "perspective",
16
+ "location": { "x": 100, "y": 200, "z": 300 },
17
+ "rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
18
+ }
19
+ },
20
+ "resolution": { "width": 1280, "height": 720 },
21
+ "assessment": { "method": "automatic" },
22
+ "clearCompanion": { "status": "not_requested" }
23
+ }
@@ -1,9 +1,10 @@
1
1
  {
2
2
  "contract": {
3
3
  "name": "ue-shed-review-selection",
4
- "version": { "major": 1, "minor": 0 }
4
+ "version": { "major": 1, "minor": 1 }
5
5
  },
6
6
  "status": "selected",
7
+ "actorGuid": "00000001-00000002-00000003-00000004",
7
8
  "actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
8
9
  "displayName": "ReviewSubject",
9
10
  "mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
@@ -10,6 +10,11 @@
10
10
  "properties": {
11
11
  "contract": { "$ref": "#/$defs/contract" },
12
12
  "status": { "const": "selected" },
13
+ "actorGuid": {
14
+ "type": "string",
15
+ "pattern": "^[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{8}){3}$",
16
+ "not": { "const": "00000000-00000000-00000000-00000000" }
17
+ },
13
18
  "actorPath": { "type": "string", "minLength": 1 },
14
19
  "displayName": { "type": "string", "minLength": 1 },
15
20
  "mapPath": { "type": "string", "minLength": 1 },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ue-shed/protocol",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
4
4
  "description": "Runtime schemas and versioned wire contracts for UE Shed integrations.",
5
5
  "homepage": "https://github.com/ue-shed/ue-shed#readme",
6
6
  "bugs": {