@ue-shed/protocol 0.2.0 → 0.4.0

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.
@@ -0,0 +1,18 @@
1
+ # Niagara preview contract v1
2
+
3
+ These JSON Schemas are the language-neutral authority shared by `UEShedNiagara` and
4
+ `@ue-shed/niagara`.
5
+
6
+ `request.schema.json` describes the one request accepted by the commandlet. It carries no output
7
+ path: Unreal stages only beneath `Saved/UEShed/NiagaraPreviewStaging/<run-id>`.
8
+
9
+ `receipt.schema.json` describes completed producer render truth. The headless host must validate
10
+ identity, containment, frame order, byte limits, and PNG dimensions rather than trusting the
11
+ receipt. `manifest.schema.json` describes the immutable host-published run with per-frame hashes.
12
+
13
+ The alpha policy converts Unreal scene opacity to straight alpha and derives coverage from emissive
14
+ brightness for additive particles. Timing is deterministic within the requested engine execution;
15
+ the contract does not claim cross-GPU pixel identity.
16
+
17
+ Change this contract in authority order: JSON Schema and fixtures, conformant Effect codecs,
18
+ `UEShedNiagara`, then consumers.
@@ -0,0 +1,96 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://ue-shed.dev/contracts/niagara/preview/v1/common.schema.json",
4
+ "$defs": {
5
+ "runId": {
6
+ "type": "string",
7
+ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
8
+ },
9
+ "systemObjectPath": {
10
+ "type": "string",
11
+ "maxLength": 1024,
12
+ "pattern": "^/[A-Za-z0-9_]+/[A-Za-z0-9_./-]+\\.[A-Za-z0-9_]+$"
13
+ },
14
+ "settings": {
15
+ "type": "object",
16
+ "properties": {
17
+ "captureMode": { "enum": ["component_only", "full_scene"] },
18
+ "durationSeconds": { "type": "number", "minimum": 0.001, "maximum": 600 },
19
+ "frameCount": { "type": "integer", "minimum": 1, "maximum": 512 },
20
+ "height": { "type": "integer", "minimum": 1, "maximum": 4096 },
21
+ "simulationFramesPerSecond": { "type": "integer", "minimum": 1, "maximum": 480 },
22
+ "startSeconds": { "type": "number", "minimum": 0, "maximum": 3600 },
23
+ "width": { "type": "integer", "minimum": 1, "maximum": 4096 }
24
+ },
25
+ "additionalProperties": false
26
+ },
27
+ "effectiveSettings": {
28
+ "type": "object",
29
+ "required": [
30
+ "captureMode",
31
+ "durationSeconds",
32
+ "frameCount",
33
+ "frameIntervalSeconds",
34
+ "height",
35
+ "playbackFramesPerSecond",
36
+ "simulationFramesPerSecond",
37
+ "startSeconds",
38
+ "width"
39
+ ],
40
+ "properties": {
41
+ "captureMode": { "enum": ["component_only", "full_scene"] },
42
+ "durationSeconds": { "type": "number", "minimum": 0.001, "maximum": 600 },
43
+ "frameCount": { "type": "integer", "minimum": 1, "maximum": 512 },
44
+ "frameIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 },
45
+ "height": { "type": "integer", "minimum": 1, "maximum": 4096 },
46
+ "playbackFramesPerSecond": { "type": "number", "exclusiveMinimum": 0 },
47
+ "simulationFramesPerSecond": { "type": "integer", "minimum": 1, "maximum": 480 },
48
+ "startSeconds": { "type": "number", "minimum": 0, "maximum": 3600 },
49
+ "width": { "type": "integer", "minimum": 1, "maximum": 4096 }
50
+ },
51
+ "additionalProperties": false
52
+ },
53
+ "camera": {
54
+ "type": "object",
55
+ "required": [
56
+ "aspectRatio",
57
+ "fieldOfViewDegrees",
58
+ "location",
59
+ "orthoWidth",
60
+ "projection",
61
+ "rotation",
62
+ "usesCustomAspectRatio"
63
+ ],
64
+ "properties": {
65
+ "aspectRatio": { "type": "number", "exclusiveMinimum": 0 },
66
+ "fieldOfViewDegrees": { "type": "number", "minimum": 0, "maximum": 180 },
67
+ "location": { "$ref": "#/$defs/vector" },
68
+ "orthoWidth": { "type": "number", "minimum": 0 },
69
+ "projection": { "enum": ["orthographic", "perspective"] },
70
+ "rotation": { "$ref": "#/$defs/rotator" },
71
+ "usesCustomAspectRatio": { "type": "boolean" }
72
+ },
73
+ "additionalProperties": false
74
+ },
75
+ "vector": {
76
+ "type": "object",
77
+ "required": ["x", "y", "z"],
78
+ "properties": {
79
+ "x": { "type": "number" },
80
+ "y": { "type": "number" },
81
+ "z": { "type": "number" }
82
+ },
83
+ "additionalProperties": false
84
+ },
85
+ "rotator": {
86
+ "type": "object",
87
+ "required": ["pitch", "roll", "yaw"],
88
+ "properties": {
89
+ "pitch": { "type": "number" },
90
+ "roll": { "type": "number" },
91
+ "yaw": { "type": "number" }
92
+ },
93
+ "additionalProperties": false
94
+ }
95
+ }
96
+ }
@@ -0,0 +1,75 @@
1
+ {
2
+ "alphaPolicy": "scene_opacity_or_emissive_coverage_v1",
3
+ "artifacts": [
4
+ {
5
+ "bytes": 128,
6
+ "height": 64,
7
+ "index": 0,
8
+ "maximumRgb": 1,
9
+ "mimeType": "image/png",
10
+ "nonTransparentPixelFraction": 0.125,
11
+ "relativePath": "frames/frame_0000.png",
12
+ "sha256": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
+ "timeSeconds": 0,
14
+ "width": 64
15
+ },
16
+ {
17
+ "bytes": 144,
18
+ "height": 64,
19
+ "index": 1,
20
+ "maximumRgb": 0.8,
21
+ "mimeType": "image/png",
22
+ "nonTransparentPixelFraction": 0.25,
23
+ "relativePath": "frames/frame_0001.png",
24
+ "sha256": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
25
+ "timeSeconds": 0.5,
26
+ "width": 64
27
+ }
28
+ ],
29
+ "camera": {
30
+ "aspectRatio": 1,
31
+ "fieldOfViewDegrees": 90,
32
+ "location": { "x": 0, "y": -200, "z": 0 },
33
+ "orthoWidth": 512,
34
+ "projection": "perspective",
35
+ "rotation": { "pitch": 0, "roll": 0, "yaw": 0 },
36
+ "usesCustomAspectRatio": false
37
+ },
38
+ "colorSpace": "srgb",
39
+ "contract": {
40
+ "name": "ue-shed-niagara-preview-run",
41
+ "version": { "major": 1, "minor": 0 }
42
+ },
43
+ "diagnostics": [],
44
+ "effectiveSettings": {
45
+ "captureMode": "component_only",
46
+ "durationSeconds": 1,
47
+ "frameCount": 2,
48
+ "frameIntervalSeconds": 0.5,
49
+ "height": 64,
50
+ "playbackFramesPerSecond": 2,
51
+ "simulationFramesPerSecond": 60,
52
+ "startSeconds": 0,
53
+ "width": 64
54
+ },
55
+ "generatedAtUtc": "2026-08-20T00:00:01.000Z",
56
+ "producer": {
57
+ "engineVersion": "5.7.2-0+++UE5+Release-5.7",
58
+ "receiptContract": {
59
+ "name": "ue-shed-niagara-preview-receipt",
60
+ "version": { "major": 1, "minor": 0 }
61
+ }
62
+ },
63
+ "requestedSettings": {
64
+ "captureMode": "component_only",
65
+ "durationSeconds": 1,
66
+ "frameCount": 2,
67
+ "height": 64,
68
+ "simulationFramesPerSecond": 60,
69
+ "startSeconds": 0,
70
+ "width": 64
71
+ },
72
+ "runId": "11111111-1111-4111-8111-111111111111",
73
+ "status": "complete",
74
+ "systemObjectPath": "/Game/Fixture/Niagara/NS_Preview.NS_Preview"
75
+ }
@@ -0,0 +1,58 @@
1
+ {
2
+ "alphaPolicy": "scene_opacity_or_emissive_coverage_v1",
3
+ "camera": {
4
+ "aspectRatio": 1,
5
+ "fieldOfViewDegrees": 90,
6
+ "location": { "x": 0, "y": -200, "z": 0 },
7
+ "orthoWidth": 512,
8
+ "projection": "perspective",
9
+ "rotation": { "pitch": 0, "roll": 0, "yaw": 0 },
10
+ "usesCustomAspectRatio": false
11
+ },
12
+ "colorSpace": "srgb",
13
+ "contract": {
14
+ "name": "ue-shed-niagara-preview-receipt",
15
+ "version": { "major": 1, "minor": 0 }
16
+ },
17
+ "effectiveSettings": {
18
+ "captureMode": "component_only",
19
+ "durationSeconds": 1,
20
+ "frameCount": 2,
21
+ "frameIntervalSeconds": 0.5,
22
+ "height": 64,
23
+ "playbackFramesPerSecond": 2,
24
+ "simulationFramesPerSecond": 60,
25
+ "startSeconds": 0,
26
+ "width": 64
27
+ },
28
+ "engineVersion": "5.7.2-0+++UE5+Release-5.7",
29
+ "frames": [
30
+ {
31
+ "index": 0,
32
+ "maximumRgb": 1,
33
+ "nonTransparentPixelFraction": 0.125,
34
+ "relativePath": "frames/frame_0000.png",
35
+ "timeSeconds": 0
36
+ },
37
+ {
38
+ "index": 1,
39
+ "maximumRgb": 0.8,
40
+ "nonTransparentPixelFraction": 0.25,
41
+ "relativePath": "frames/frame_0001.png",
42
+ "timeSeconds": 0.5
43
+ }
44
+ ],
45
+ "generatedAtUtc": "2026-08-20T00:00:00.000Z",
46
+ "requestedSettings": {
47
+ "captureMode": "component_only",
48
+ "durationSeconds": 1,
49
+ "frameCount": 2,
50
+ "height": 64,
51
+ "simulationFramesPerSecond": 60,
52
+ "startSeconds": 0,
53
+ "width": 64
54
+ },
55
+ "runId": "11111111-1111-4111-8111-111111111111",
56
+ "status": "complete",
57
+ "systemObjectPath": "/Game/Fixture/Niagara/NS_Preview.NS_Preview"
58
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "contract": {
3
+ "name": "ue-shed-niagara-preview-request",
4
+ "version": { "major": 1, "minor": 0 }
5
+ },
6
+ "runId": "11111111-1111-4111-8111-111111111111",
7
+ "settings": {
8
+ "captureMode": "component_only",
9
+ "durationSeconds": 1,
10
+ "frameCount": 2,
11
+ "height": 64,
12
+ "simulationFramesPerSecond": 60,
13
+ "startSeconds": 0,
14
+ "width": 64
15
+ },
16
+ "systemObjectPath": "/Game/Fixture/Niagara/NS_Preview.NS_Preview"
17
+ }
@@ -0,0 +1,115 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://ue-shed.dev/contracts/niagara/preview/v1/manifest.schema.json",
4
+ "type": "object",
5
+ "required": [
6
+ "alphaPolicy",
7
+ "artifacts",
8
+ "camera",
9
+ "colorSpace",
10
+ "contract",
11
+ "diagnostics",
12
+ "effectiveSettings",
13
+ "generatedAtUtc",
14
+ "producer",
15
+ "requestedSettings",
16
+ "runId",
17
+ "status",
18
+ "systemObjectPath"
19
+ ],
20
+ "properties": {
21
+ "alphaPolicy": { "const": "scene_opacity_or_emissive_coverage_v1" },
22
+ "artifacts": {
23
+ "type": "array",
24
+ "minItems": 1,
25
+ "items": {
26
+ "type": "object",
27
+ "required": [
28
+ "bytes",
29
+ "height",
30
+ "index",
31
+ "maximumRgb",
32
+ "mimeType",
33
+ "nonTransparentPixelFraction",
34
+ "relativePath",
35
+ "sha256",
36
+ "timeSeconds",
37
+ "width"
38
+ ],
39
+ "properties": {
40
+ "bytes": { "type": "integer", "minimum": 1 },
41
+ "height": { "type": "integer", "minimum": 1, "maximum": 4096 },
42
+ "index": { "type": "integer", "minimum": 0 },
43
+ "maximumRgb": { "type": "number", "minimum": 0, "maximum": 1 },
44
+ "mimeType": { "const": "image/png" },
45
+ "nonTransparentPixelFraction": { "type": "number", "minimum": 0, "maximum": 1 },
46
+ "relativePath": {
47
+ "type": "string",
48
+ "pattern": "^frames/frame_[0-9]{4}\\.png$"
49
+ },
50
+ "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
51
+ "timeSeconds": { "type": "number", "minimum": 0 },
52
+ "width": { "type": "integer", "minimum": 1, "maximum": 4096 }
53
+ },
54
+ "additionalProperties": false
55
+ }
56
+ },
57
+ "camera": { "$ref": "common.schema.json#/$defs/camera" },
58
+ "colorSpace": { "const": "srgb" },
59
+ "contract": {
60
+ "type": "object",
61
+ "required": ["name", "version"],
62
+ "properties": {
63
+ "name": { "const": "ue-shed-niagara-preview-run" },
64
+ "version": {
65
+ "type": "object",
66
+ "required": ["major", "minor"],
67
+ "properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
68
+ "additionalProperties": false
69
+ }
70
+ },
71
+ "additionalProperties": false
72
+ },
73
+ "diagnostics": {
74
+ "type": "array",
75
+ "items": {
76
+ "type": "object",
77
+ "required": ["code", "message"],
78
+ "properties": {
79
+ "code": { "enum": ["nearly_black", "nearly_empty"] },
80
+ "message": { "type": "string", "minLength": 1 }
81
+ },
82
+ "additionalProperties": false
83
+ }
84
+ },
85
+ "effectiveSettings": { "$ref": "common.schema.json#/$defs/effectiveSettings" },
86
+ "generatedAtUtc": { "type": "string", "minLength": 1 },
87
+ "producer": {
88
+ "type": "object",
89
+ "required": ["engineVersion", "receiptContract"],
90
+ "properties": {
91
+ "engineVersion": { "type": "string", "minLength": 1 },
92
+ "receiptContract": {
93
+ "type": "object",
94
+ "required": ["name", "version"],
95
+ "properties": {
96
+ "name": { "const": "ue-shed-niagara-preview-receipt" },
97
+ "version": {
98
+ "type": "object",
99
+ "required": ["major", "minor"],
100
+ "properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
101
+ "additionalProperties": false
102
+ }
103
+ },
104
+ "additionalProperties": false
105
+ }
106
+ },
107
+ "additionalProperties": false
108
+ },
109
+ "requestedSettings": { "$ref": "common.schema.json#/$defs/settings" },
110
+ "runId": { "$ref": "common.schema.json#/$defs/runId" },
111
+ "status": { "const": "complete" },
112
+ "systemObjectPath": { "$ref": "common.schema.json#/$defs/systemObjectPath" }
113
+ },
114
+ "additionalProperties": false
115
+ }
@@ -0,0 +1,71 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://ue-shed.dev/contracts/niagara/preview/v1/receipt.schema.json",
4
+ "type": "object",
5
+ "required": [
6
+ "alphaPolicy",
7
+ "camera",
8
+ "colorSpace",
9
+ "contract",
10
+ "effectiveSettings",
11
+ "engineVersion",
12
+ "frames",
13
+ "generatedAtUtc",
14
+ "requestedSettings",
15
+ "runId",
16
+ "status",
17
+ "systemObjectPath"
18
+ ],
19
+ "properties": {
20
+ "alphaPolicy": { "const": "scene_opacity_or_emissive_coverage_v1" },
21
+ "camera": { "$ref": "common.schema.json#/$defs/camera" },
22
+ "colorSpace": { "const": "srgb" },
23
+ "contract": {
24
+ "type": "object",
25
+ "required": ["name", "version"],
26
+ "properties": {
27
+ "name": { "const": "ue-shed-niagara-preview-receipt" },
28
+ "version": {
29
+ "type": "object",
30
+ "required": ["major", "minor"],
31
+ "properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
32
+ "additionalProperties": false
33
+ }
34
+ },
35
+ "additionalProperties": false
36
+ },
37
+ "effectiveSettings": { "$ref": "common.schema.json#/$defs/effectiveSettings" },
38
+ "engineVersion": { "type": "string", "minLength": 1 },
39
+ "frames": {
40
+ "type": "array",
41
+ "minItems": 1,
42
+ "items": {
43
+ "type": "object",
44
+ "required": [
45
+ "index",
46
+ "maximumRgb",
47
+ "nonTransparentPixelFraction",
48
+ "relativePath",
49
+ "timeSeconds"
50
+ ],
51
+ "properties": {
52
+ "index": { "type": "integer", "minimum": 0 },
53
+ "maximumRgb": { "type": "number", "minimum": 0, "maximum": 1 },
54
+ "nonTransparentPixelFraction": { "type": "number", "minimum": 0, "maximum": 1 },
55
+ "relativePath": {
56
+ "type": "string",
57
+ "pattern": "^frames/frame_[0-9]{4}\\.png$"
58
+ },
59
+ "timeSeconds": { "type": "number", "minimum": 0 }
60
+ },
61
+ "additionalProperties": false
62
+ }
63
+ },
64
+ "generatedAtUtc": { "type": "string", "minLength": 1 },
65
+ "requestedSettings": { "$ref": "common.schema.json#/$defs/settings" },
66
+ "runId": { "$ref": "common.schema.json#/$defs/runId" },
67
+ "status": { "const": "complete" },
68
+ "systemObjectPath": { "$ref": "common.schema.json#/$defs/systemObjectPath" }
69
+ },
70
+ "additionalProperties": false
71
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://ue-shed.dev/contracts/niagara/preview/v1/request.schema.json",
4
+ "type": "object",
5
+ "required": ["contract", "runId", "settings", "systemObjectPath"],
6
+ "properties": {
7
+ "contract": {
8
+ "type": "object",
9
+ "required": ["name", "version"],
10
+ "properties": {
11
+ "name": { "const": "ue-shed-niagara-preview-request" },
12
+ "version": {
13
+ "type": "object",
14
+ "required": ["major", "minor"],
15
+ "properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
16
+ "additionalProperties": false
17
+ }
18
+ },
19
+ "additionalProperties": false
20
+ },
21
+ "runId": { "$ref": "common.schema.json#/$defs/runId" },
22
+ "settings": { "$ref": "common.schema.json#/$defs/settings" },
23
+ "systemObjectPath": { "$ref": "common.schema.json#/$defs/systemObjectPath" }
24
+ },
25
+ "additionalProperties": false
26
+ }