unreal-engine-mcp-server 0.6.0-beta-c → 0.6.0-beta-e

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.
Files changed (102) hide show
  1. package/CHANGELOG.md +148 -9
  2. package/README.md +2 -2
  3. package/dist/gateway/gateway-manifest.generated.json +838 -133
  4. package/dist/proxy/native-proxy.js +6 -5
  5. package/dist/server/gateway/gateway-execute-dispatch.js +2 -1
  6. package/dist/server/gateway/gateway-execute-envelope.js +5 -1
  7. package/dist/server/gateway/gateway-execute-lookup.js +1 -1
  8. package/dist/server/gateway/gateway-execute.js +17 -4
  9. package/dist/server/gateway/gateway-schema-validate.js +13 -2
  10. package/dist/server/gateway/gateway-task-results.d.ts +6 -0
  11. package/dist/server/gateway/gateway-task-results.js +40 -0
  12. package/dist/server/tool-registry-manage-tools.js +4 -1
  13. package/dist/tools/catalog/capabilities/generated/canonical-registry.generated.d.ts +2 -2
  14. package/dist/tools/catalog/capabilities/generated/canonical-registry.generated.js +2 -2
  15. package/dist/tools/catalog/capabilities/generated/canonical-registry.generated.json +4079 -618
  16. package/dist/tools/catalog/capabilities/generated/capability-cost-index.generated.d.ts +1 -1
  17. package/dist/tools/catalog/capabilities/generated/capability-cost-index.generated.js +18 -1
  18. package/dist/tools/catalog/capabilities/generated/parent-tool-definitions.generated.js +1546 -212
  19. package/dist/tools/catalog/capabilities/records/aggregate.d.ts +1 -1
  20. package/dist/tools/catalog/capabilities/records/aggregate.js +1 -1
  21. package/dist/tools/catalog/capabilities/records/build-environment/spline.data.js +4 -3
  22. package/dist/tools/catalog/capabilities/records/build-environment/water.data.js +8 -5
  23. package/dist/tools/catalog/capabilities/records/control-actor/advanced-records.js +29 -8
  24. package/dist/tools/catalog/capabilities/records/control-actor/search-records.js +2 -2
  25. package/dist/tools/catalog/capabilities/records/control-actor/spawn-records.js +13 -5
  26. package/dist/tools/catalog/capabilities/records/control-actor/state-records.js +2 -1
  27. package/dist/tools/catalog/capabilities/records/control-actor/transform-records.js +27 -9
  28. package/dist/tools/catalog/capabilities/records/control-editor/asset.js +4 -1
  29. package/dist/tools/catalog/capabilities/records/control-editor/camera.js +5 -1
  30. package/dist/tools/catalog/capabilities/records/control-editor/command.js +5 -1
  31. package/dist/tools/catalog/capabilities/records/control-editor/input.js +2 -1
  32. package/dist/tools/catalog/capabilities/records/control-editor/screenshot.js +2 -1
  33. package/dist/tools/catalog/capabilities/records/control-editor/session.js +8 -1
  34. package/dist/tools/catalog/capabilities/records/control-editor/timing.js +5 -3
  35. package/dist/tools/catalog/capabilities/records/core/builder.d.ts +1 -0
  36. package/dist/tools/catalog/capabilities/records/core/builder.js +1 -0
  37. package/dist/tools/catalog/capabilities/records/folds/build-environment.folds.js +2 -2
  38. package/dist/tools/catalog/capabilities/records/folds/control-actor.folds.js +2 -2
  39. package/dist/tools/catalog/capabilities/records/folds/manage-asset.folds.js +8 -8
  40. package/dist/tools/catalog/capabilities/records/folds/manage-audio.folds.js +5 -5
  41. package/dist/tools/catalog/capabilities/records/folds/manage-blueprint.folds.js +2 -2
  42. package/dist/tools/catalog/capabilities/records/folds/manage-effect.folds.js +3 -3
  43. package/dist/tools/catalog/capabilities/records/folds/manage-sequence.folds.js +6 -6
  44. package/dist/tools/catalog/capabilities/records/folds/system-control.folds.js +2 -2
  45. package/dist/tools/catalog/capabilities/records/gameplay/animation-physics/animation-properties.js +7 -5
  46. package/dist/tools/catalog/capabilities/records/gameplay/animation-physics/authoring-1.data.js +86 -1
  47. package/dist/tools/catalog/capabilities/records/gameplay/animation-physics/authoring-2.data.js +7 -2
  48. package/dist/tools/catalog/capabilities/records/gameplay/manage-effect/effect-properties.js +7 -6
  49. package/dist/tools/catalog/capabilities/records/gameplay/manage-effect/effect.data.js +38 -27
  50. package/dist/tools/catalog/capabilities/records/inspect/component-actor.data.js +1 -1
  51. package/dist/tools/catalog/capabilities/records/inspect/object-property.data.js +188 -10
  52. package/dist/tools/catalog/capabilities/records/inspect/properties.d.ts +1 -0
  53. package/dist/tools/catalog/capabilities/records/inspect/properties.js +2 -1
  54. package/dist/tools/catalog/capabilities/records/inspect/runtime.data.js +2 -1
  55. package/dist/tools/catalog/capabilities/records/inspect/stats.data.js +6 -2
  56. package/dist/tools/catalog/capabilities/records/manage-asset/asset-advanced.js +46 -0
  57. package/dist/tools/catalog/capabilities/records/manage-asset/asset-lifecycle.js +2 -2
  58. package/dist/tools/catalog/capabilities/records/manage-asset/asset-query.js +4 -3
  59. package/dist/tools/catalog/capabilities/records/manage-asset/builder.d.ts +3 -0
  60. package/dist/tools/catalog/capabilities/records/manage-asset/builder.js +3 -0
  61. package/dist/tools/catalog/capabilities/records/manage-asset/content-sources.js +3 -1
  62. package/dist/tools/catalog/capabilities/records/manage-asset/material-create.js +17 -2
  63. package/dist/tools/catalog/capabilities/records/manage-asset/material-graph.js +7 -5
  64. package/dist/tools/catalog/capabilities/records/manage-asset/material-params.js +5 -5
  65. package/dist/tools/catalog/capabilities/records/manage-audio/authoring.data.js +15 -5
  66. package/dist/tools/catalog/capabilities/records/manage-audio/runtime.data.js +1 -0
  67. package/dist/tools/catalog/capabilities/records/manage-blueprint/functions-events.js +3 -2
  68. package/dist/tools/catalog/capabilities/records/manage-blueprint/graph-batch.js +2 -2
  69. package/dist/tools/catalog/capabilities/records/manage-blueprint/graph-pins.js +6 -2
  70. package/dist/tools/catalog/capabilities/records/manage-blueprint/properties.js +4 -2
  71. package/dist/tools/catalog/capabilities/records/manage-blueprint/scs-components.js +7 -2
  72. package/dist/tools/catalog/capabilities/records/manage-blueprint/variables-metadata.js +8 -2
  73. package/dist/tools/catalog/capabilities/records/manage-blueprint/widget-animation.js +14 -4
  74. package/dist/tools/catalog/capabilities/records/manage-blueprint/widget-lifecycle.js +13 -5
  75. package/dist/tools/catalog/capabilities/records/manage-blueprint/widget-panels.js +1 -1
  76. package/dist/tools/catalog/capabilities/records/manage-sequence/cinematic.js +12 -3
  77. package/dist/tools/catalog/capabilities/records/manage-sequence/helpers.js +2 -2
  78. package/dist/tools/catalog/capabilities/records/manage-sequence/mrq.js +23 -4
  79. package/dist/tools/catalog/capabilities/records/manage-sequence/timeline-bindings.js +2 -2
  80. package/dist/tools/catalog/capabilities/records/manage-sequence/timeline-lifecycle.js +7 -2
  81. package/dist/tools/catalog/capabilities/records/manage-sequence/timeline-playback.js +9 -5
  82. package/dist/tools/catalog/capabilities/records/manage-sequence/timeline-state-ranges.js +19 -0
  83. package/dist/tools/catalog/capabilities/records/manage-sequence/timeline-tracks.js +10 -5
  84. package/dist/tools/catalog/capabilities/records/manage-tools/index.js +30 -2
  85. package/dist/tools/catalog/capabilities/records/system-control/console.js +3 -1
  86. package/dist/tools/catalog/capabilities/records/system-control/system-ops.js +122 -10
  87. package/dist/tools/catalog/capabilities/records/utility/output-glossary.js +11 -0
  88. package/dist/tools/catalog/capabilities/records/utility/utility-schema-pins.js +6 -3
  89. package/dist/tools/catalog/capabilities/records/world/manage-geometry.optimize.data.js +29 -0
  90. package/dist/tools/catalog/capabilities/records/world/manage-geometry.primitives.data.js +2 -1
  91. package/dist/tools/catalog/capabilities/records/world/properties.js +2 -2
  92. package/dist/tools/catalog/capabilities/semantic/envelope.d.ts +1 -1
  93. package/dist/tools/catalog/capabilities/semantic/errors.d.ts +1 -1
  94. package/dist/tools/catalog/unreal-gateway-definition.js +2 -2
  95. package/dist/utils/responses/gateway-reply-compaction.d.ts +6 -0
  96. package/dist/utils/responses/gateway-reply-compaction.js +264 -0
  97. package/dist/utils/responses/response-content.d.ts +0 -1
  98. package/dist/utils/responses/response-content.js +0 -172
  99. package/dist/utils/responses/response-validator.d.ts +1 -1
  100. package/dist/utils/responses/response-validator.js +39 -8
  101. package/package.json +2 -2
  102. package/server.json +2 -2
@@ -58,6 +58,52 @@ export const ASSET_ADVANCED_RECORDS = [
58
58
  'It is not known yet which slot holds which part of the mesh (inspect.inspect_object with objectKind=mesh lists every slot with the triangle count and bounds of its geometry).',
59
59
  ],
60
60
  examples: [ex('Give an imported mesh its own materials, one slot by name and one by index', { assetPath: '/Game/Meshes/SM_Rider', materials: [{ slot: 'hull', materialPath: '/Game/Materials/M_Hull' }, { slot: 9, materialPath: '/Game/Materials/M_Claw' }] }, { success: true, assetPath: '/Game/Meshes/SM_Rider', assetType: 'StaticMesh', applied: 2, changed: 2, refused: [], saved: true })] }),
61
+ r('set_mesh_collision', 'asset', 'Set the collision of a static mesh asset: one box, sphere or capsule fitted to its bounds, its own render triangles (complex), or none; every placed copy is rebuilt to match and the mesh is saved.', schema({
62
+ assetPath: str('Static mesh asset path under /Game; engine meshes are refused (duplicate one into /Game first).'),
63
+ collisionType: { type: 'string', enum: ['box', 'sphere', 'capsule', 'complex', 'none'], description: 'box, sphere or capsule: one shape fitted to the mesh bounds (a capsule stands upright along Z) replaces its simple collision. complex: the render triangles are the collision, exact for terrain-like or concave meshes but costlier. none: no collision, so pawns and traces pass through.' },
64
+ save: bool('Save the mesh after the change. Defaults to true.'),
65
+ }, ['assetPath', 'collisionType']), schema({
66
+ success: bool('Operation succeeded.'),
67
+ assetPath: ASSET_PATH,
68
+ collisionType: str('The collision the mesh has now.'),
69
+ shapeCount: num('Simple collision shapes the mesh holds after the call (0 for complex and none).'),
70
+ componentsRefreshed: num('Placed copies of the mesh in open worlds whose collision was rebuilt to match.'),
71
+ saved: bool('Whether the mesh was saved.'),
72
+ details: { type: 'object', 'x-unreal-reflection-boundary': true, description: 'Operation details.' },
73
+ }, ['success']), WRITE, WRITE_POLICY, MEDIUM, { topics: ['mesh collision', 'static mesh collision', 'add box collision', 'complex as simple', 'remove collision', 'player falls through mesh', 'walk on imported mesh'],
74
+ whenToUse: [
75
+ 'An imported or Fab mesh has no simple collision, so pawns fall through it or walk through it.',
76
+ 'A decorative mesh (grass, flowers, small debris) must stop blocking the player.',
77
+ 'A terrain-like or concave mesh must collide exactly with its own triangles (complex).',
78
+ ],
79
+ whenNotToUse: [
80
+ 'A dynamic mesh actor needs collision generated (use manage_geometry.configure_mesh_collision).',
81
+ 'Only one placed copy should stop colliding (use control_actor.set_actor_collision).',
82
+ 'It must be checked whether a placed mesh blocks at all (use inspect.raycast_world).',
83
+ ],
84
+ examples: [ex('Make an imported rock standable with one box', { assetPath: '/Game/Meshes/SM_Rock', collisionType: 'box' }, { success: true, assetPath: '/Game/Meshes/SM_Rock', collisionType: 'box', shapeCount: 1, componentsRefreshed: 3, saved: true })] }),
85
+ r('export_mesh', 'asset', 'Export a static or skeletal mesh asset (or an animation sequence, on its preview mesh) to a file through the editor\'s own exporters: glb (default: one self-contained glTF binary), gltf (JSON with its buffers and textures beside it), fbx or obj. It is written under Saved/Exports unless outputPath says otherwise; the reply gives the path, the size, the files written beside it and any exporter warnings.', schema({
86
+ assetPath: str('Asset to export, e.g. /Game/Meshes/SM_Rock or /Engine/BasicShapes/Cube. A skeletal mesh is written with its skeleton; an animation sequence is written on its skeleton\'s preview mesh.'),
87
+ format: { type: 'string', enum: ['glb', 'gltf', 'fbx', 'obj'], description: 'File format; default glb, or the extension outputPath ends in. glb and gltf are scaled to meters with materials converted to glTF PBR; fbx and obj keep centimeters.' },
88
+ outputPath: str('Where to write, inside the project, project-relative or absolute: a file (Saved/Exports/Rocks/SM_Rock.glb) or a folder, which gets <asset name>.<format>. A file already there is replaced.'),
89
+ }, ['assetPath']), schema({
90
+ success: bool('Operation succeeded.'),
91
+ assetPath: str('The asset exported.'),
92
+ format: str('The format written.'),
93
+ path: str('Absolute path of the file written.'),
94
+ bytes: num('Its size in bytes.'),
95
+ otherFiles: arrObj('Files the export wrote beside it, each {name, bytes}: a gltf\'s .bin buffers and textures, obj\'s UV and collision variants.'),
96
+ details: { type: 'object', 'x-unreal-reflection-boundary': true, description: 'Operation details.' },
97
+ }, ['success']), READ, READ_POLICY, MEDIUM, { topics: ['export mesh', 'export gltf', 'export glb', 'export fbx', 'export obj', 'save mesh to file', 'mesh to blender', 'export model'],
98
+ whenToUse: [
99
+ 'A mesh must leave the editor as a file: for Blender or another DCC tool, a web viewer, a mesh checker or a 3D printer.',
100
+ 'An animation must be looked at or checked outside Unreal (export the sequence as glb).',
101
+ ],
102
+ whenNotToUse: [
103
+ 'A file must come into the project (use asset.import).',
104
+ 'Only the mesh\'s soundness must be checked (use inspect.check_mesh, which needs no file).',
105
+ ],
106
+ examples: [ex('Export a mesh as glTF binary', { assetPath: '/Engine/BasicShapes/Cube' }, { success: true, assetPath: '/Engine/BasicShapes/Cube.Cube', format: 'glb', path: 'X:/Games/MyGame/Saved/Exports/Cube.glb', bytes: 41764 })] }),
61
107
  r('add_material_parameter', 'asset', 'Add a parameter to a material.', schema({ assetPath: str('Material asset path.'), parameterName: str('Parameter name.'), parameterType: str('Parameter type.'), value: { description: 'Parameter value.' } }, ['assetPath', 'parameterName']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A new scalar, vector, texture or static-switch parameter must be introduced on a material or material function.'],
62
108
  whenNotToUse: [
63
109
  'An existing parameter needs a new value on a material instance (use material.set_material_parameter).',
@@ -116,11 +116,11 @@ export const ASSET_LIFECYCLE_RECORDS = [
116
116
  whenToUse: ['Assets must be found across the project by name, class, folder or asset-registry tag.'],
117
117
  whenNotToUse: ['Actors placed in the open level must be found (use control_actor.find).'],
118
118
  examples: [ex('Search materials by name', { searchText: 'M_Rock', classNames: ['Material'], packagePaths: ['/Game/Materials'], recursivePaths: true, limit: 25 }, { success: true, assets: [{ name: 'M_Rock', path: '/Game/Materials/M_Rock.M_Rock', class: 'Material', packagePath: '/Game/Materials' }], folders: [], totalCount: 1, count: 1, limit: 25, offset: 0, hasMore: false, nextOffset: 1, cursor: null, nextCursor: null })] }),
119
- r('find_text', 'asset', 'Find where a piece of text appears: Blueprint graph literals and comments, variable and component defaults (a reference to another asset matches by its path, so a sound name finds the component that plays it), widget texts, DataTable rows, String Table entries, and the actors of the open level.', schema({
119
+ r('find_text', 'asset', 'Find where a piece of text appears: Blueprint graph nodes by title (every call of a function, by its name as the graph shows it), literals, assets picked on pins and comments, variable and component defaults (a reference to another asset matches by its path, so a sound name finds the node or component that plays it), widget texts, DataTable rows, String Table entries, and the actors of the open level.', schema({
120
120
  searchText: str('Text to search for.'),
121
121
  packagePaths: arr('Package paths to search within.'),
122
122
  caseSensitive: bool('Match letter case (default false).'),
123
- includeLevel: bool('Also search the actors and components of the open level (default true).'),
123
+ includeLevel: bool('Also search the actors and components of the open level: true or false outright; omitted, only when that level lies under packagePaths (always with the default /Game).'),
124
124
  limit: boundedLimit(500, 50)
125
125
  }, ['searchText']), schema({
126
126
  success: bool('Operation succeeded.'),
@@ -13,7 +13,7 @@ const ANALYZE_GRAPH_OK = schema({
13
13
  success: bool('Operation succeeded.'),
14
14
  assetPath: ASSET_PATH,
15
15
  assetClass: str('Concrete UClass name of the analyzed asset.'),
16
- graphType: str('Graph kind analyzed: Material, Blueprint, or None.'),
16
+ graphType: str('Graph kind analyzed: Material, Blueprint, None, or the class of an asset whose graph another action reads (see nextCall).'),
17
17
  nodeCount: num('Material expression nodes in the graph.'),
18
18
  parameterCount: num('Material parameter expressions in the graph.'),
19
19
  textureSampleCount: num('Texture sample expressions in the graph.'),
@@ -27,7 +27,8 @@ const ANALYZE_GRAPH_OK = schema({
27
27
  totalNodes: num('Total nodes across every Blueprint graph.'),
28
28
  graphCount: num('Number of graphs in the Blueprint.'),
29
29
  graphs: arrObj('Per-graph breakdown (name, nodeCount).'),
30
- message: str('Explanation when the asset type carries no graph.'),
30
+ message: str('Explanation when the asset type carries no graph, or which action reads it.'),
31
+ nextCall: { type: 'object', 'x-unreal-reflection-boundary': true, description: 'A MetaSound, Niagara or Behavior Tree asset: the execute call of the action that reads its graph.' },
31
32
  }, ['success']);
32
33
  export const ASSET_QUERY_RECORDS = [
33
34
  r('get_dependencies', 'asset', 'List the packages an asset uses, or with referencers the packages that use it. Direct packages only; lookup "graph" walks dependencies recursively.', schema({
@@ -42,7 +43,7 @@ export const ASSET_QUERY_RECORDS = [
42
43
  r('get_source_control_state', 'asset', 'Retrieve source-control state for an asset.', schema({ assetPath: ASSET_PATH, assetPaths: arr('Several asset paths to query in one call.'), recursive: bool('Also report every /Game package the assets depend on, transitively (up to 512).') }, [], ['assetPath', 'assetPaths']), OK, READ, READ_POLICY, LOW, { whenToUse: ['Before editing, it must be known whether assets are checked out, modified or held by someone else.'],
43
44
  whenNotToUse: ['Assets must be checked out or submitted (use asset.source_control).'],
44
45
  examples: [ex('Check whether a mesh is checked out', { assetPath: '/Game/Meshes/SM_Crate' }, { success: true })] }),
45
- r('analyze_graph', 'asset', 'Analyze the node graph inside a material or Blueprint asset.', schema({ assetPath: ASSET_PATH }, ['assetPath']), ANALYZE_GRAPH_OK, READ, READ_POLICY, MEDIUM, { whenToUse: ['A material or Blueprint must be summarised: node counts, parameters, blend mode or graph count.'],
46
+ r('analyze_graph', 'asset', 'Analyze the node graph inside a material or Blueprint asset; a MetaSound, Niagara or Behavior Tree asset answers with the nextCall that reads its graph.', schema({ assetPath: ASSET_PATH }, ['assetPath']), ANALYZE_GRAPH_OK, READ, READ_POLICY, MEDIUM, { whenToUse: ['A material or Blueprint must be summarised: node counts, parameters, blend mode or graph count.'],
46
47
  whenNotToUse: ['One Blueprint\'s variables, functions or components are wanted (use blueprint.get_blueprint).'],
47
48
  examples: [ex('Inspect a material\'s expression graph', { assetPath: '/Game/Materials/M_Base' }, { success: true, graphType: 'Material', nodeCount: 4, parameterCount: 2, blendMode: 'BLEND_Opaque' })] }),
48
49
  r('get_asset_graph', 'asset', 'Retrieve the asset reference graph directly via the get_asset_graph bridge action.', schema({ assetPath: ASSET_PATH, maxDepth: num('Maximum traversal depth (clamped to 8).') }, ['assetPath']), GRAPH_OK, READ, READ_POLICY, MEDIUM, { whenToUse: ['The reference graph of an asset must be walked several levels deep in one call (depth is capped at 8).'],
@@ -2,6 +2,9 @@ import type { CapabilityAvailability, CapabilityBehaviorSource, CapabilityCost,
2
2
  export { bool, num, str } from '../shared/schema-props.js';
3
3
  export declare const MATERIAL_PARAMETER_LIST: JsonObject;
4
4
  export declare const MATERIAL_PARAMETER_ASSETS: JsonObject;
5
+ export declare const MATERIAL_DOMAIN: JsonObject;
6
+ export declare const BLEND_MODE: JsonObject;
7
+ export declare const SHADING_MODEL: JsonObject;
5
8
  export declare const arr: (desc: string) => JsonObject;
6
9
  export declare const arrObj: (desc: string) => JsonObject;
7
10
  export declare const refObj: (desc: string) => JsonObject;
@@ -13,6 +13,9 @@ export const MATERIAL_PARAMETER_ASSETS = {
13
13
  'x-unreal-reflection-boundary': true,
14
14
  description: 'Several materials or material instances at once, in place of assetPath: each {assetPath, and parameters or parameterName with value}; the call\'s own save applies to every entry. Every entry is reported under assets, and the call fails naming any that did not apply.',
15
15
  };
16
+ export const MATERIAL_DOMAIN = { type: 'string', description: 'Material domain: Surface, DeferredDecal, LightFunction, Volume, PostProcess or UI (a widget, brush or font material). The Details panel label (User Interface) and the MD_ name work too.' };
17
+ export const BLEND_MODE = { type: 'string', description: 'Blend mode, such as Opaque, Masked, Translucent, Additive, Modulate or AlphaComposite. The Details panel label and the BLEND_ name work too.' };
18
+ export const SHADING_MODEL = { type: 'string', description: 'Shading model, such as DefaultLit, Unlit, Subsurface, ClearCoat or TwoSidedFoliage. The Details panel label and the MSM_ name work too.' };
16
19
  export const arr = (desc) => ({ type: 'array', items: { type: 'string' }, description: desc });
17
20
  export const arrObj = (desc) => ({ type: 'array', items: { type: 'object', 'x-unreal-reflection-boundary': true }, description: desc });
18
21
  export const refObj = (desc) => ({ type: 'object', 'x-unreal-reflection-boundary': true, description: desc });
@@ -1,5 +1,5 @@
1
1
  import { arr, arrObj, bool, boundedLimit, ex, HIGH, LOW, MEDIUM, num, READ, READ_POLICY, r, str, WRITE_POLICY } from './builder.js';
2
- import { schema } from '../shared/record-presets.js';
2
+ import { OUTPUT_HEADER, schema } from '../shared/record-presets.js';
3
3
  const MIGRATE_BEHAVIOR = {
4
4
  effect: 'write', idempotency: 'idempotent', longRunning: true,
5
5
  safeToRetry: true
@@ -81,6 +81,7 @@ export const CONTENT_SOURCE_RECORDS = [
81
81
  examples: [ex('Download a pack from a signed URL', { assetId: 'abc123', downloadUrl: 'https://example.invalid/signed' }, { success: false })] }),
82
82
  r('get_fab_listing_details', 'asset', 'Describe one Fab listing: what it is (description, tags, publisher, category, rating, licenses, price, publication date and a preview image) and what adding it would do (the format it imports, the build or file it fetches, its size, whether a build exists for the running engine, and why it would refuse), so a caller can choose between search hits and know before adding. Opens the Fab tab when it is closed and waits up to 15 seconds for its page to load (PAGE_NOT_READY after that) instead of failing on the first call; the account must be signed in there. It reads the listing and its asset-formats resources and claims nothing. canAddToProject says whether add_fab_asset_to_project can import the listing, and when it cannot, addBlockedCode and addBlockedReason say why: COMPLETE_PROJECT (a whole project cannot be added to an existing one: create it as a new project from Fab, then migrate its content), METAHUMAN_FORMAT (Fab hands a MetaHuman listing to a workflow the add does not drive) or NO_IMPORTABLE_FORMAT (it ships none of unreal-engine, gltf, glb, fbx, obj or usdz). Megascans listings are importable like any other, because the add claims the listing itself. addFormat is the format the add would import (unreal-engine first, else gltf, glb, fbx, obj, usdz). For a unreal-engine pack, versionName, pickedEngineVersion and engineMatch name the build it would take (the highest at or below the running engine, else the lowest above it), engineVersions lists every engine the pack declares and supportsRunningEngine says whether the running engine is one of them. For a source format, downloadFile, quality and qualities (Megascans offers raw, high, mid and low) name the file. downloadBytes is the size of exactly the file or build the add would fetch and is left out, with downloadSizeKnown false, when Fab publishes none, which is every pack: unknown is never reported as zero. formats lists every format with its files and their sizes. isFree is derived from price, because the listing\'s own isFree flag disagrees with it and is not reported. addWarnings lists what would surprise the caller: a pack with no build for the running engine, and a mesh file so large that the add refuses it until combineMeshes is chosen. The preview comes back as imageBase64, promoted into a real MCP image block rather than a URL, and is omitted rather than truncated past the reply cap. When a field cannot be read the response names the keys it did see, so a Fab schema change reports itself.', schema({ listingId: str('Fab listing uid. Restricted to [A-Za-z0-9_-], 64 characters max. fab_import_status also takes it, in place of operationId, to report the newest import of that listing.') }, ['listingId']), schema({
83
83
  success: bool('Listing was described.'),
84
+ details: OUTPUT_HEADER.details,
84
85
  listingId: str('Listing that was described.'),
85
86
  title: str('Listing title.'),
86
87
  listingType: str('Content kind, e.g. 3d-model or material.'),
@@ -158,6 +159,7 @@ export const CONTENT_SOURCE_RECORDS = [
158
159
  combineMeshes: bool('Only for source mesh formats (fbx, obj, gltf, glb, usdz) that Fab imports itself; ignored for Megascans and unreal-engine packs. Omit to leave Fab\'s behaviour alone: every mesh of a file is merged into ONE static mesh. false imports each mesh as its own asset: the adapter switches off Interchange\'s mesh combining on the pipelines Fab generated for this import, and the status read\'s combineMeshesApplied says whether that landed in time (COMBINE_UNSUPPORTED refuses the call when this engine gives no way to). true accepts the single merged mesh explicitly, which a scene-sized file (one mesh file of 50 MB or more) requires.')
159
160
  }, ['listingId']), schema({
160
161
  success: bool('True when Fab accepted the download. It does not mean content exists: poll fab_import_status for that.'),
162
+ details: OUTPUT_HEADER.details,
161
163
  listingId: str('Listing that was requested.'),
162
164
  accepted: bool('True when Fab accepted the workflow. Not the same as content existing.'),
163
165
  operationId: str('The background import. Pass it to asset.query_marketplace lookup=fab_import_status. On QUEUE_FULL it names the import at the head of the queue instead, and on ADD_ALREADY_RUNNING the open import of this listing.'),
@@ -1,4 +1,4 @@
1
- import { bool, ex, MATERIAL_PARAMETER_LIST, MEDIUM, r, str, WRITE, WRITE_POLICY } from './builder.js';
1
+ import { arrObj, BLEND_MODE, bool, ex, MATERIAL_DOMAIN, MATERIAL_PARAMETER_LIST, MEDIUM, r, SHADING_MODEL, str, WRITE, WRITE_POLICY } from './builder.js';
2
2
  import { schema } from '../shared/record-presets.js';
3
3
  const SAVE = bool('Save the asset afterwards. Defaults to true; pass false to keep it in memory only.');
4
4
  const PRESET_SETTINGS = {
@@ -11,7 +11,7 @@ const PRESET_SETTINGS = {
11
11
  const OK_PROPS = { success: bool('Operation succeeded.'), details: { type: 'object', 'x-unreal-reflection-boundary': true, description: 'Operation details.' } };
12
12
  const OK = schema(OK_PROPS, ['success']);
13
13
  export const MATERIAL_CREATE_RECORDS = [
14
- r('create_material', 'material', 'Create a new material asset.', schema({ name: str('Material name.'), path: str('Package path.'), materialDomain: str('Material domain.'), blendMode: str('Blend mode.'), shadingModel: str('Shading model.'), twoSided: bool('Two-sided flag.'), save: SAVE }, ['name']), OK, WRITE, WRITE_POLICY, MEDIUM, { whenToUse: ['A mesh, surface or effect needs a shader of its own and no material asset exists for it yet.', 'A translucent, unlit or two-sided material is wanted from the start (materialDomain, blendMode, shadingModel, twoSided).'],
14
+ r('create_material', 'material', 'Create a new material asset.', schema({ name: str('Asset name.'), path: str('Package path.'), materialDomain: MATERIAL_DOMAIN, blendMode: BLEND_MODE, shadingModel: SHADING_MODEL, twoSided: bool('Two-sided flag.'), save: SAVE }, ['name']), OK, WRITE, WRITE_POLICY, MEDIUM, { whenToUse: ['A mesh, surface or effect needs a shader of its own and no material asset exists for it yet.', 'A translucent, unlit or two-sided material is wanted from the start (materialDomain, blendMode, shadingModel, twoSided).'],
15
15
  whenNotToUse: ['A variation of an existing material with different parameter values is wanted (use material.create_material_instance).', 'An existing material must be copied as it is (use asset.duplicate).'],
16
16
  topics: ['new material', 'make material', 'material asset', 'shader'],
17
17
  examples: [ex('Create an opaque lit surface material', { name: 'M_Base', path: '/Game/Materials', materialDomain: 'Surface', blendMode: 'Opaque', shadingModel: 'DefaultLit', twoSided: false, save: true }, { success: true })] }),
@@ -29,6 +29,21 @@ export const MATERIAL_CREATE_RECORDS = [
29
29
  r('create_material_function', 'material', 'Create a new material function asset.', schema({ name: str('Function name.'), path: str('Package path.'), save: SAVE, description: str('Function description.'), exposeToLibrary: bool('Expose in the material function library.') }, ['name']), OK, WRITE, WRITE_POLICY, MEDIUM, { whenToUse: ['A chunk of graph logic must be reused by several materials as one node, listed in the function library unless exposeToLibrary is false.'],
30
30
  whenNotToUse: ['The logic is used by one material only (build it in that material with material.add_material_node).'],
31
31
  examples: [ex('Create a reusable blend function', { name: 'MF_HeightBlend', path: '/Game/Materials/Functions', save: true }, { success: true })] }),
32
+ r('create_parameter_collection', 'material', 'Create a Material Parameter Collection, values every material that reads it shares, or add parameters to one and set their defaults.', schema({
33
+ name: str('Asset name.'), path: str('Package path.'), save: SAVE,
34
+ scalars: arrObj('Scalar parameters, each {name, default}: a name the collection lacks is added, one it has takes the new default (0 when a new one gives none).'),
35
+ vectors: arrObj('Vector parameters, each {name, default}: default as [r, g, b, a] or {r, g, b, a} (alpha 1 when omitted); a name the collection lacks is added, one it has takes the new default.'),
36
+ }, ['name']), schema({
37
+ ...OK_PROPS,
38
+ assetPath: str('The collection\'s object path.'), created: bool('True when the call made the collection, false when it updated one.'),
39
+ added: { type: 'array', items: { type: 'string' }, description: 'The parameters this call added.' },
40
+ scalars: { type: 'array', items: { type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true }, 'x-unreal-reflection-boundary': true, description: 'Every scalar parameter of the collection after the call: {name, default}.' },
41
+ vectors: { type: 'array', items: { type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true }, 'x-unreal-reflection-boundary': true, description: 'Every vector parameter after the call: {name, default [r, g, b, a]}.' },
42
+ saved: bool('Whether the collection reached disk.'),
43
+ }, ['success']), WRITE, WRITE_POLICY, MEDIUM, { whenToUse: ['One value must drive many materials at once, set once at runtime (a level-wide wetness, wind strength, time of day or flash): a material reads it with a CollectionParameter node (material.add_material_node nodeType CollectionParameter with collectionPath and name), and a Blueprint sets it with SetScalarParameterValue or SetVectorParameterValue of the Kismet Material Library, the collection on its Collection pin.', 'An existing collection needs another parameter or new defaults: send it again; parameters are never removed, since materials read them by id.'],
44
+ whenNotToUse: ['The value differs per object (use a material instance and material.set_material_parameter, or a dynamic material instance per actor).'],
45
+ topics: ['material parameter collection', 'mpc', 'global material parameter', 'shared material value', 'level wide material value'],
46
+ examples: [ex('A collection for level-wide weather', { name: 'MPC_Weather', path: '/Game/Materials', scalars: [{ name: 'Wetness', default: 0 }, { name: 'WindStrength', default: 0.3 }], vectors: [{ name: 'FogTint', default: [0.6, 0.7, 0.8, 1] }] }, { success: true, assetPath: '/Game/Materials/MPC_Weather.MPC_Weather', created: true, added: ['Wetness', 'WindStrength', 'FogTint'], saved: true })] }),
32
47
  r('create_landscape_material', 'material', 'Create a landscape material asset (Surface domain, Opaque by default).', schema({ name: str('Material name.'), path: str('Package path.'), ...PRESET_SETTINGS }, ['name']), OK, WRITE, WRITE_POLICY, MEDIUM, { whenToUse: ['A material is being made for a landscape; it starts empty (Surface domain, Opaque) and its layers are added afterwards.'],
33
48
  whenNotToUse: ['The material exists and only needs assigning to a landscape (use build_environment.sculpt with sculptOp=material).'],
34
49
  examples: [ex('Create a terrain material', { name: 'M_Landscape', path: '/Game/Materials/Landscape' }, { success: true })] }),
@@ -1,5 +1,5 @@
1
1
  import { arr, arrObj, bool, ex, LOW, MATERIAL_PARAMETER_ASSETS, MATERIAL_PARAMETER_LIST, num, READ, READ_POLICY, r, refObj, str, WRITE, WRITE_POLICY } from './builder.js';
2
- import { schema } from '../shared/record-presets.js';
2
+ import { OUTPUT_HEADER, schema } from '../shared/record-presets.js';
3
3
  const MAT = str('Material /Game asset path.');
4
4
  const MAT_ALIAS = str('Material asset path (accepted in place of materialPath).');
5
5
  const SOURCE_PIN = str('Source output: its name, its index, or channel letters of the default output ("G", "RG"; X/Y/Z/W work too). Omit for the default output.');
@@ -8,6 +8,7 @@ const SAVE = bool('Save the asset afterwards. Defaults to true; pass false to ke
8
8
  const OK = schema({ success: bool('Operation succeeded.'), details: { type: 'object', 'x-unreal-reflection-boundary': true, description: 'Operation details.' } }, ['success']);
9
9
  const MOVE_OUT = schema({
10
10
  success: bool('Operation succeeded.'),
11
+ details: OUTPUT_HEADER.details,
11
12
  nodeId: str('Moved node ID.'),
12
13
  posX: num('X coordinate the node now sits at.'),
13
14
  posY: num('Y coordinate the node now sits at.'),
@@ -44,7 +45,8 @@ const OPERATIONS = {
44
45
  'x-unreal-reflection-boundary': true,
45
46
  description: 'Steps run in order, 1-200. Each is {edit, ...the params of that edit}: edit is a node adder (add_material_node, '
46
47
  + 'add_scalar_parameter, add_vector_parameter, add_texture_sample, add_texture_coordinate, add_math_node, add_noise, '
47
- + 'add_custom_expression, ...), use_material_function, connect_nodes, set_node_position, update_custom_expression, '
48
+ + 'add_custom_expression, ...; or add_material_node with nodeKind, as in the single call: {"edit": "add_material_node", '
49
+ + '"nodeKind": "world_position"}), use_material_function, connect_nodes, set_node_position, update_custom_expression, '
48
50
  + 'set_blend_mode, set_shading_model, set_material_domain or set_two_sided. Optional per step: id (names the created '
49
51
  + 'node; later steps use "$id" in sourceNodeId/targetNodeId/nodeId), from/to ("$id.Pin" shorthand for connect_nodes, where '
50
52
  + 'a source pin may be channel letters like "$uv.G"; '
@@ -55,7 +57,7 @@ const OPERATIONS = {
55
57
  const BATCH_OUT = schema({
56
58
  success: bool('True when every step ran.'),
57
59
  assetPath: str('The material the batch edited, compiled and saved.'),
58
- results: arrObj('Per-step outcome: index, edit, id, success, nodeId, placementWarning, error.'),
60
+ results: arrObj('Per-step outcome: index, edit, id, success, nodeId, placementWarning, error. A step that ran and has nothing more to say (a plain connect_nodes) is counted in succeeded, not listed; a failed batch lists every step.'),
59
61
  nodeIds: { type: 'object', additionalProperties: { type: 'string' }, description: 'Step id -> node id for every node the batch created.' },
60
62
  succeeded: num('Steps that completed.'),
61
63
  failedIndex: num('Index of the step that stopped the batch (failures only).'),
@@ -66,7 +68,7 @@ const BATCH_OUT = schema({
66
68
  const CUSTOM_UPDATE_OUT = schema({
67
69
  success: bool('Operation succeeded.'),
68
70
  compiled: bool('False when the material does not compile after the edit (the default material renders in its place); compileErrors says why. A material function has no translation of its own to read, so this is true for one.'),
69
- compileErrors: arr('Compile errors the material translator reported after the edit, empty when it compiles.'),
71
+ compileErrors: arr('Compile errors after the edit, from the material translator and, once it has finished, the shader compile (where a Custom node\'s HLSL fails); empty when it compiles.'),
70
72
  saved: bool('Whether the material or function was saved after the edit.'),
71
73
  details: { type: 'object', 'x-unreal-reflection-boundary': true, description: 'Operation details.' },
72
74
  }, ['success']);
@@ -109,7 +111,7 @@ export const MATERIAL_GRAPH_RECORDS = [
109
111
  r('get_connected_subgraph', 'material', 'Retrieve the connected subgraph from a starting node.', schema({ materialPath: MAT, assetPath: MAT_ALIAS, nodeId: str('Starting node ID.'), orphansOnly: bool('Report only orphaned nodes; accepted in place of nodeId.') }, ['nodeId'], ['materialPath', 'assetPath']), OK, READ, READ_POLICY, LOW, { whenToUse: ['Nodes not wired to any output (orphans) must be found, or the connected island around one node listed.'],
110
112
  whenNotToUse: ['Orphaned nodes are to be removed (use material.delete_node once their ids are known).'],
111
113
  examples: [ex('Collect the subgraph under a node', { materialPath: M, nodeId: SAMPLE, orphansOnly: false }, DONE)] }),
112
- r('add_material_node', 'material', 'Add a generic material node by type.', schema({ materialPath: MAT, nodeType: str('Node type.'), type: str('Node type (alias of nodeType).'), name: str('Parameter name, when the node type is a parameter of any kind (scalar, vector, static switch, TextureObjectParameter, TextureSampleParameter2D).'), texturePath: str('Texture for a texture node (TextureObjectParameter, TextureSample...): its default, with the sampler type set to match (a normal map samples as Normal). A path that does not load adds nothing and fails.'), defaultValue: { description: 'Initial value for a Constant (number) or Constant3Vector (rgb array or {r,g,b}) node.' }, posX: num('Node X position.'), posY: num('Node Y position.'), x: num('Node X position (preferred spelling; posX is the fallback).'), y: num('Node Y position (preferred spelling; posY is the fallback).') }, ['materialPath', 'nodeType']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['An expression is needed by class name with no dedicated adder, such as Constant, Constant3Vector (with defaultValue), ComponentMask or Saturate.', 'A texture object must feed a Custom node or a material function input (nodeType TextureObjectParameter with name and texturePath).'],
114
+ r('add_material_node', 'material', 'Add a generic material node by type.', schema({ materialPath: MAT, nodeType: str('Node type.'), type: str('Node type (alias of nodeType).'), name: str('Parameter name, when the node type is a parameter of any kind (scalar, vector, static switch, TextureObjectParameter, TextureSampleParameter2D), or the parameter of collectionPath a CollectionParameter node reads.'), collectionPath: str('Material Parameter Collection a CollectionParameter node reads (name picks its parameter); a collection that does not load, or lacks the parameter, adds nothing and fails, listing its parameters.'), texturePath: str('Texture for a texture node (TextureObjectParameter, TextureSample...): its default, with the sampler type set to match (a normal map samples as Normal). A path that does not load adds nothing and fails.'), defaultValue: { description: 'Initial value for a Constant (number) or Constant3Vector (rgb array or {r,g,b}) node.' }, posX: num('Node X position.'), posY: num('Node Y position.'), x: num('Node X position (preferred spelling; posX is the fallback).'), y: num('Node Y position (preferred spelling; posY is the fallback).') }, ['materialPath', 'nodeType']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['An expression is needed by class name with no dedicated adder, such as Constant, Constant3Vector (with defaultValue), ComponentMask or Saturate.', 'A texture object must feed a Custom node or a material function input (nodeType TextureObjectParameter with name and texturePath).', 'A material must read a value of a Material Parameter Collection (nodeType CollectionParameter with collectionPath and name).'],
113
115
  whenNotToUse: ['The node already exists and only needs wiring or moving (use material.connect_nodes or material.set_node_position).'],
114
116
  examples: [ex('Add a Constant3Vector by type name', { materialPath: M, nodeType: 'Constant3Vector', x: -300, y: 100 }, DONE)] }),
115
117
  r('rebuild_material', 'material', 'Rebuild and compile a material (alias of compile_material).', schema({ materialPath: MAT, assetPath: MAT_ALIAS, save: SAVE }, [], ['materialPath', 'assetPath']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['The shader must be regenerated after graph edits; the compile, error check and save are identical to a plain compile.'],
@@ -1,4 +1,4 @@
1
- import { arr, arrObj, bool, ex, LOW, num, READ, READ_POLICY, r, str, WRITE, WRITE_POLICY } from './builder.js';
1
+ import { arr, arrObj, BLEND_MODE, bool, ex, LOW, MATERIAL_DOMAIN, num, READ, READ_POLICY, r, SHADING_MODEL, str, WRITE, WRITE_POLICY } from './builder.js';
2
2
  import { schema } from '../shared/record-presets.js';
3
3
  const MAT = str('Material /Game asset path.');
4
4
  const MATFN = str('Material function /Game asset path.');
@@ -16,7 +16,7 @@ const COMPILE_OK = schema({
16
16
  assetPath: str('Compiled asset path.'),
17
17
  assetType: str('Material or MaterialFunction.'),
18
18
  compiled: bool('False when the material does not compile; compileErrors says why.'),
19
- compileErrors: arr('Compile errors reported by the material translator, empty when it compiles.'),
19
+ compileErrors: arr('Compile errors from the material translator and, once it has finished, the shader compile (where a Custom node\'s HLSL fails); empty when it compiles.'),
20
20
  saved: bool('Whether the asset was saved.'),
21
21
  }, ['success']);
22
22
  const MATERIAL_INFO_OK = schema({
@@ -39,13 +39,13 @@ const MI = '/Game/Materials/MI_Base_Rusty';
39
39
  const MF = '/Game/Materials/Functions/MF_HeightBlend';
40
40
  const DONE = { success: true };
41
41
  export const MATERIAL_PARAMS_RECORDS = [
42
- r('set_blend_mode', 'material', 'Set the blend mode of a material.', schema({ assetPath: MAT, blendMode: str('Blend mode.'), save: SAVE }, ['assetPath', 'blendMode']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A material must become translucent, cut out (Masked) or additive instead of Opaque.'],
42
+ r('set_blend_mode', 'material', 'Set the blend mode of a material.', schema({ assetPath: MAT, blendMode: BLEND_MODE, save: SAVE }, ['assetPath', 'blendMode']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A material must become translucent, cut out (Masked) or additive instead of Opaque.'],
43
43
  whenNotToUse: ['The target is a material instance; only a base material can be edited here (find it with material.get_material_info).', 'A new material is being created with the blend mode already known (use material.create_material with blendMode).'],
44
44
  examples: [ex('Switch a material to masked blending', { assetPath: M, blendMode: 'Masked' }, DONE)] }),
45
- r('set_shading_model', 'material', 'Set the shading model of a material.', schema({ assetPath: MAT, shadingModel: str('Shading model.'), save: SAVE }, ['assetPath', 'shadingModel']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A surface needs a different shading model, such as DefaultLit, Unlit, Subsurface, ClearCoat or Hair.'],
45
+ r('set_shading_model', 'material', 'Set the shading model of a material.', schema({ assetPath: MAT, shadingModel: SHADING_MODEL, save: SAVE }, ['assetPath', 'shadingModel']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A surface needs a different shading model, such as DefaultLit, Unlit, Subsurface, ClearCoat or Hair.'],
46
46
  whenNotToUse: ['The target is a material instance; only a base material can be edited here (find it with material.get_material_info).', 'A new material is being created with the shading model already known (use material.create_material with shadingModel).'],
47
47
  examples: [ex('Use the default lit shading model', { assetPath: M, shadingModel: 'DefaultLit' }, DONE)] }),
48
- r('set_material_domain', 'material', 'Set the material domain of a material.', schema({ assetPath: MAT, materialDomain: str('Material domain.'), save: SAVE }, ['assetPath', 'materialDomain']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A material must change domain, for example between Surface, DeferredDecal, PostProcess and UI.'],
48
+ r('set_material_domain', 'material', 'Set the material domain of a material.', schema({ assetPath: MAT, materialDomain: MATERIAL_DOMAIN, save: SAVE }, ['assetPath', 'materialDomain']), OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['A material must change domain, for example between Surface, DeferredDecal, PostProcess and UI.'],
49
49
  whenNotToUse: ['The target is a material instance; only a base material can be edited here (find it with material.get_material_info).', 'A new material is being created with the domain already known (use material.create_material with materialDomain).'],
50
50
  examples: [ex('Keep a material in the surface domain', { assetPath: M, materialDomain: 'Surface' }, DONE)] }),
51
51
  r('compile_material', 'material', 'Compile a material and report its compile errors.', schema({ assetPath: MAT, materialPath: MAT_ALIAS, save: SAVE }, [], ['assetPath', 'materialPath']), COMPILE_OK, WRITE, WRITE_POLICY, LOW, { whenToUse: ['The compile errors of an edited graph must be read; a material that fails to compile renders as the default material.', 'Graph edits left the asset unsaved, so it must be compiled and saved.'],
@@ -49,18 +49,26 @@ export const AUDIO_AUTHORING_RECORDS = [
49
49
  }),
50
50
  a('add_mix_modifier', 'Add a Sound Class modifier to a Sound Mix; fadeInTime and fadeOutTime set the fades of the mix itself.', ['assetPath', 'soundClassPath', 'volumeAdjuster', 'pitchAdjuster', 'applyToChildren', 'fadeInTime', 'fadeOutTime', 'save'], ['assetPath', 'soundClassPath']),
51
51
  a('add_source_effect', 'Add an effect to a Source Effect Chain: a new preset of effectType, or an existing preset asset by effectPresetPath.', ['assetPath', 'effectType', 'effectPresetPath', 'bypass', 'save'], ['assetPath'], [], [], [], ['effectType', 'effectPresetPath']),
52
- { ...(withInputProps(a('build_metasound', 'Run many MetaSound graph edits in one call: add nodes, inputs and outputs, connect pins and set literals, with $id references between steps.', ['assetPath'], ['assetPath', 'operations'], ['nodeIds', 'results'], [], META), {
52
+ { ...(withInputProps(a('build_metasound', 'Run many MetaSound graph edits in one call: add nodes, inputs and outputs, connect pins and set literals, with $id references between steps.', ['assetPath'], ['assetPath', 'operations'], ['nodeIds', 'results', 'saved'], [], META), {
53
53
  operations: {
54
54
  type: 'array', items: OBJ_ITEM, 'x-unreal-reflection-boundary': true,
55
- description: 'Steps run in order, 1-200, stopping at the first failure. Each is {edit, ...the params of that edit}: edit is '
55
+ description: 'Steps run in order, 1-200, stopping at the first failure; every add_node class is looked up first, so a node '
56
+ + 'class the registry does not hold fails the batch with nothing applied, and so is every pin a connect or set_default names '
57
+ + 'on a node the batch adds (a wrong one fails with PIN_NOT_FOUND and that node\'s pins). Each is {edit, ...the params of that edit}: edit is '
56
58
  + 'add_node, connect, disconnect, remove_node, set_default, add_input or add_output (the add_metasound_node, connect_metasound_nodes, '
57
59
  + 'disconnect_metasound_nodes, remove_metasound_node, set_metasound_default, add_metasound_input, add_metasound_output params). Optional per step: id (names the node '
58
60
  + 'it creates; later steps use "$id" in nodeId/nodeIds/sourceNodeId/targetNodeId), from/to ("$id.PinName" shorthand for '
59
61
  + 'connect; interface nodes such as the On Play input are named with the explicit fields).',
60
62
  },
61
- save: { type: 'boolean', description: 'Save the MetaSound after each step (default true); false leaves every edit in memory only.' },
63
+ save: { type: 'boolean', description: 'Save the MetaSound once, after the steps (default true); a batch that stops at a failing step saves the steps before it. false leaves every edit in memory only.' },
62
64
  })), examples: [{ title: 'Build a one-oscillator MetaSound', ...BUILD_METASOUND_EXAMPLE }] },
63
- a('configure_distance_attenuation', 'Configure distance attenuation.', ['assetPath', 'innerRadius', 'falloffDistance', 'distanceAlgorithm', 'save'], ['assetPath']),
65
+ withInputProps(a('configure_distance_attenuation', 'Configure distance attenuation: inner radius, falloff distance and curve, and air absorption (a low-pass that muffles the sound with distance).', ['assetPath', 'innerRadius', 'falloffDistance', 'distanceAlgorithm', 'save'], ['assetPath']), {
66
+ attenuateWithLPF: { type: 'boolean', description: 'Air absorption on or off: a low-pass whose cutoff drops with distance. Sending any lpf value turns it on unless this is false.' },
67
+ lpfRadiusMin: { type: 'number', description: 'Distance in cm where the low-pass starts closing; nearer than this the cutoff is lpfFrequencyAtMin.' },
68
+ lpfRadiusMax: { type: 'number', description: 'Distance in cm where the cutoff reaches lpfFrequencyAtMax.' },
69
+ lpfFrequencyAtMin: { type: 'number', description: 'Low-pass cutoff in Hz at lpfRadiusMin and nearer (20000 leaves the sound unfiltered).' },
70
+ lpfFrequencyAtMax: { type: 'number', description: 'Low-pass cutoff in Hz at lpfRadiusMax and beyond (900 sounds like a distant, muffled engine).' },
71
+ }),
64
72
  a('configure_mix_eq', 'Configure Sound Mix equalization: the four bands through eqSettings, or the low, mid, highMid and high fields.', ['assetPath', 'applyEQ', 'eqPriority', 'eqSettings', 'lowFrequency', 'lowGain', 'midFrequency', 'midGain', 'highMidFrequency', 'highMidGain', 'highFrequency', 'highGain', 'save'], ['assetPath']),
65
73
  a('configure_occlusion', 'Configure audio occlusion.', ['assetPath', 'enable', 'occlusionVolumeScale', 'occlusionFilterScale', 'occlusionInterpolationTime', 'save'], ['assetPath']),
66
74
  a('configure_reverb_send', 'Configure an audio reverb send.', ['assetPath', 'enableReverbSend', 'reverbDistanceMin', 'reverbDistanceMax', 'reverbWetLevelMin', 'reverbWetLevelMax', 'save'], ['assetPath']),
@@ -79,7 +87,9 @@ export const AUDIO_AUTHORING_RECORDS = [
79
87
  a('create_attenuation_settings', 'Create attenuation settings and return the asset path.', ['name', 'path', 'innerRadius', 'falloffDistance', 'save'], ['name'], ['assetPath'], ['assetPath']),
80
88
  a('create_dialogue_voice', 'Create a Dialogue Voice asset and return its path.', ['name', 'path', 'gender', 'plurality', 'save'], ['name'], ['assetPath'], ['assetPath']),
81
89
  a('create_dialogue_wave', 'Create a Dialogue Wave asset and return its path; wavePath or speakerPath adds its first context mapping.', ['name', 'path', 'spokenText', 'wavePath', 'speakerPath', 'save'], ['name'], ['assetPath'], ['assetPath']),
82
- a('create_metasound', 'Create a MetaSound asset, named by name and path or by its full assetPath, and return its asset path. A MetaSound already at that path is refused (ASSET_EXISTS), never replaced.', ['name', 'path', 'assetPath', 'save'], [], ['assetPath'], ['assetPath'], META, ['name', 'assetPath']),
90
+ withInputProps(a('create_metasound', 'Create a MetaSound asset, named by name and path or by its full assetPath, and return its asset path. A MetaSound already at that path is refused (ASSET_EXISTS), never replaced. A one-shot source (the default: On Play in, On Finished out) is never virtualized by the engine, so one left playing on an AudioComponent that starts out of earshot is dropped for good; make a drone, hum or ambience with oneShot false.', ['name', 'path', 'assetPath', 'oneShot', 'save'], [], ['assetPath', 'oneShot'], ['assetPath'], META, ['name', 'assetPath']), {
91
+ oneShot: { type: 'boolean', description: 'false makes a continuous source with no On Finished output: the engine treats it as looping, so a hum or ambience whose AudioComponent starts out of earshot resumes when the listener comes near. Default true (it plays until On Finished fires).' },
92
+ }),
83
93
  a('create_reverb_effect', 'Create a Reverb Effect asset and return its path.', ['name', 'path', 'density', 'diffusion', 'gain', 'gainHF', 'decayTime', 'decayHFRatio', 'save'], ['name'], ['assetPath'], ['assetPath']),
84
94
  a('create_source_effect_chain', 'Create a Source Effect Chain asset and return its path.', ['name', 'path', 'save'], ['name'], ['assetPath'], ['assetPath']),
85
95
  withInputProps(a('create_submix_effect', 'Create a Sound Submix whose effect chain holds a new submix effect preset of effectType, and return its path.', ['name', 'path', 'effectType', 'save'], ['name', 'effectType'], ['assetPath'], ['assetPath']), {
@@ -16,6 +16,7 @@ export const AUDIO_RUNTIME_RECORDS = [
16
16
  withTopics(r('play_sound_2d', 'Play a non-spatial sound.', ['soundPath', 'volume', 'pitch', 'startTime'], ['soundPath']), ['play sound', 'play audio', 'play sfx', 'ui sound', 'play music']),
17
17
  withTopics(r('play_sound_at_location', 'Play a sound at a world location.', ['soundPath', 'location', 'rotation', 'volume', 'pitch', 'startTime', 'attenuationPath', 'concurrencyPath'], ['soundPath']), ['play sound at location', '3d sound', 'spatial sound', 'positional audio']),
18
18
  r('play_sound_attached', 'Play a sound attached to an actor component.', ['soundPath', 'actorName', 'componentName', 'attachPointName', 'volume', 'pitch'], ['soundPath', 'actorName']),
19
+ withTopics(r('play_sound_measure', 'Play a sound 2D and measure how loud it played, from the mixer\'s own meter: peak and average level in dB and a timeline, with silent: true when it played but produced no audio (an empty Sound Cue, a MetaSound whose audio output is unconnected). A Sound Wave also gets the peak, RMS and length of the recording itself (wavePeakDb, waveRmsDb, waveSeconds), which hold however slowly the editor draws. Answers when the sound ends or after maxSeconds.', ['soundPath', 'volume', 'maxSeconds'], ['soundPath'], ['peakDb', 'averageDb', 'silent', 'envelopeUpdates', 'endedBecause', 'timeline', 'timelineStepSeconds', 'wavePeakDb', 'waveRmsDb', 'waveSeconds'], ['peakDb', 'silent']), ['measure sound', 'sound level', 'is sound audible', 'loudness', 'silent sound', 'audio meter', 'verify sound plays']),
19
20
  r('pop_sound_mix', 'Pop a Sound Mix from the runtime mix stack.', ['mixName'], ['mixName']),
20
21
  r('prime_sound', 'Prime a sound asset for playback.', ['soundPath'], ['soundPath']),
21
22
  r('push_sound_mix', 'Push a Sound Mix onto the runtime mix stack.', ['mixName'], ['mixName']),
@@ -9,8 +9,8 @@ export const FUNCTIONS_EVENTS_RECORDS = [
9
9
  family: FAMILY,
10
10
  domain: DOMAIN,
11
11
  topics: ['new function', 'custom function', 'function graph', 'define function'],
12
- summary: 'Add a new function graph to a Blueprint with optional inputs and outputs; an existing function of that name is reused only when it matches the pure, inputs and outputs given.',
13
- whenToUse: ['A new callable function must be created on the Blueprint.'],
12
+ summary: 'Add a new function graph to a Blueprint with optional inputs and outputs; an existing function of that name is reused only when it matches the pure, inputs and outputs given. A name the parent class lets a Blueprint override (a widget\'s OnKeyDown) makes that override with its own signature, so leave inputs, outputs, pure and isPublic out.',
13
+ whenToUse: ['A new callable function must be created on the Blueprint.', 'A parent function with a return value must be overridden, such as a widget\'s OnKeyDown to handle a key.'],
14
14
  whenNotToUse: ['An event handler is needed (use add_event).'],
15
15
  inputProps: {
16
16
  blueprintPath: P.blueprintPath, functionName: P.functionName, inputs: P.inputs, outputs: P.outputs,
@@ -22,6 +22,7 @@ export const FUNCTIONS_EVENTS_RECORDS = [
22
22
  functionName: P.functionName,
23
23
  nodeGuid: { type: 'string', description: 'Node guid: the function\'s entry node, or the event node. A built-in event that already exists in the graph may be bound without one.' },
24
24
  resultNodeGuid: { type: 'string', description: 'The function\'s return node, present when the function has one (it is made when outputs are declared).' },
25
+ overrides: { type: 'string', description: 'The parent function the new one overrides (UserWidget::OnKeyDown), when functionName names one.' },
25
26
  },
26
27
  outputRequired: ['functionName'],
27
28
  effect: 'write',
@@ -20,7 +20,7 @@ export const GRAPH_BATCH_RECORDS = [
20
20
  'x-unreal-reflection-boundary': true,
21
21
  description: 'Steps run in order, 1-200. Each is {edit, ...that edit\'s own params}. Member steps come before the nodes '
22
22
  + 'that use them: add_variable (variableName, variableType as add_variable takes it: basic, class, struct, enum and container '
23
- + 'types, defaultValue, isPublic, category), add_function '
23
+ + 'types, defaultValue, isPublic, exposeOnSpawn, category), add_function '
24
24
  + '(functionName, inputs, outputs, pure, isPublic; its body steps set graphName to the function name; with an id, "$id" '
25
25
  + 'is its entry node and "$id_return" its return node, which exists when outputs are declared), add_event '
26
26
  + '(customEventName and parameters, or componentName plus eventName for a component or Widget Blueprint widget delegate, '
@@ -42,7 +42,7 @@ export const GRAPH_BATCH_RECORDS = [
42
42
  },
43
43
  required: ['blueprintPath', 'operations'],
44
44
  outputProps: {
45
- results: { type: 'array', items: ITEM, 'x-unreal-reflection-boundary': true, description: 'Per-step outcome: index, edit, id, success, error, nodeGuid, resultNodeGuid (add_function), pins (for created nodes), connected, appliedValue, placementWarning (a create step that was moved off an overlapping position, or placed where it still overlaps).' },
45
+ results: { type: 'array', items: ITEM, 'x-unreal-reflection-boundary': true, description: 'Per-step outcome: index, edit, id, success, error, nodeGuid, resultNodeGuid (add_function), pins (for created nodes), connected, appliedValue, placementWarning (a create step that was moved off an overlapping position, or placed where it still overlaps), inputPins and boundToMembers (a Math Expression\'s Expression step: the pins it made, and the names that read member variables instead). A step that ran and has nothing more to say (a plain connect_pins, an add_variable) is counted in succeeded, not listed; a failed batch lists every step.' },
46
46
  nodeIds: { type: 'object', additionalProperties: { type: 'string' }, description: 'Step id -> node guid for every node the batch created or reused; an add_function step with an id also adds "<id>_return" for its return node.' },
47
47
  succeeded: { type: 'number', description: 'Steps that completed.' },
48
48
  failedIndex: { type: 'number', description: 'Index of the step that stopped the batch (failures only).' },
@@ -9,7 +9,7 @@ export const GRAPH_PINS_RECORDS = [
9
9
  family: FAMILY,
10
10
  domain: DOMAIN,
11
11
  topics: ['link pins', 'wire nodes', 'connect nodes', 'exec pin', 'connect output to input'],
12
- summary: 'Connect two graph pins (exec or data) by nodeGuid and pin name.',
12
+ summary: 'Connect two graph pins (exec or data) by nodeGuid and pin name. A pin the editor adds on demand is added: a Sequence\'s then_2, a Make Array\'s [2], a Switch on Int\'s case 7 (a new switch has only Default).',
13
13
  whenToUse: ['An exec or data link between two existing nodes must be created.'],
14
14
  whenNotToUse: ['Links must be broken (use break_pin_links).'],
15
15
  inputProps: { blueprintPath: P.blueprintPath, graphName: P.graphName, fromNodeId: P.fromNodeId, fromPinName: P.fromPinName, toNodeId: P.toNodeId, toPinName: P.toPinName, sourceNode: P.sourceNode, targetNode: P.targetNode, sourcePin: P.sourcePin, targetPin: P.targetPin },
@@ -65,10 +65,14 @@ export const GRAPH_PINS_RECORDS = [
65
65
  whenNotToUse: ['A pin default value is the target (use set_pin_default_value).'],
66
66
  inputProps: {
67
67
  blueprintPath: P.blueprintPath, graphName: P.graphName, nodeId: P.nodeId, propertyName: P.propertyName, nodeGuid: P.nodeGuid,
68
- propertyValue: { ...P.propertyValue, description: "set_node_property: text for NodeComment, a number for NodePosX or NodePosY, true or false for bCommentBubbleVisible or bDisabled, Enabled, Disabled or DevelopmentOnly for EnabledState, an asset path for a reflected field. set_pin_default_value: the pin's new default as text: a number, true or false, an enum value name, a vector as X,Y,Z (0,150,110), a rotator as P,Y,R, or an asset path." },
68
+ propertyValue: { ...P.propertyValue, description: "set_node_property: text for NodeComment, a number for NodePosX or NodePosY, true or false for bCommentBubbleVisible or bDisabled, Enabled, Disabled or DevelopmentOnly for EnabledState, the text of a Math Expression node's Expression (each other name becomes an input pin, except one the Blueprint has a variable of, which reads that variable; a comparison used as a number is refused: write SelectFloat(1, 0, A > B)), an asset path for a reflected field. set_pin_default_value: the pin's new default as text: a number, true or false, an enum value name, a vector as X,Y,Z (0,150,110), a rotator as P,Y,R, or an asset path." },
69
69
  },
70
70
  required: ['blueprintPath', 'propertyName', 'propertyValue'],
71
71
  requiredOneOf: ['nodeId', 'nodeGuid'],
72
+ outputProps: {
73
+ inputPins: { type: 'array', items: { type: 'string' }, description: 'Expression: the input pins the parsed expression made, the names to wire.' },
74
+ boundToMembers: { type: 'array', items: { type: 'string' }, description: 'Expression: names that read the Blueprint\'s own variable of that name instead of making a pin; rename the input to get a pin.' },
75
+ },
72
76
  effect: 'write',
73
77
  behavior: { idempotency: 'idempotent', safeToRetry: true },
74
78
  latency: 'instant',
@@ -42,13 +42,15 @@ export const P = {
42
42
  'x-unreal-reflection-boundary': true,
43
43
  },
44
44
  graphName: S('Target graph name (Event Graph, Construction Script, etc.).'),
45
- nodeType: S('The node to create: CallFunction (memberName, plus memberClass for a function of another class), Event (eventName: BeginPlay, Tick), CustomEvent (customEventName), VariableGet or VariableSet (memberName), Cast (targetClass), InputAxisEvent (inputAxisName), Branch, Sequence, Select, Switch, SwitchOnInt, SwitchOnEnum, SwitchOnString, DoOnce, DoN, FlipFlop, Gate, MultiGate, ForLoop, ForEachLoop, WhileLoop (each also WithBreak), MakeArray, MakeStruct and BreakStruct (structPath), SpawnActorFromClass, GetAllActorsOfClass, Self, Timeline, Reroute, Comment; a common function by name (PrintString, Delay, SetActorLocation, GetPlayerPawn, IsValid, PlaySound2D); or a K2Node class name that inspect_graph info=node_types lists. For create_struct_make_break_nodes: make or break.'),
45
+ nodeType: S('The node to create: CallFunction (memberName, plus memberClass for a function of another class), Event (eventName: BeginPlay, Tick), CustomEvent (customEventName), VariableGet or VariableSet (memberName), Cast (targetClass), InputAxisEvent (inputAxisName), Branch, Sequence, Select, Switch, SwitchOnInt, SwitchOnEnum, SwitchOnString, DoOnce, DoN, FlipFlop, Gate, MultiGate, ForLoop, ForEachLoop, WhileLoop (each also WithBreak), MakeArray, MakeStruct and BreakStruct (structPath), SpawnActorFromClass, GetAllActorsOfClass, Self, Timeline, Reroute, Comment (a Switch on Int is made with only Default: wire a case by its number, from "$id.0", "$id.1"..., and the case pin is added; a Sequence or a commutative math node grows its inputs the same way); a common function by name (PrintString, Delay, SetActorLocation, GetPlayerPawn, GetActorOfClass, IsValid, PlaySound2D); or a K2Node class name that inspect_graph info=node_types lists. For create_struct_make_break_nodes: make or break.'),
46
46
  nodeId: S('Id of an existing node: the nodeGuid edit_graph returned when it made the node, or a nodeId inspect_graph lists.'),
47
47
  nodeName: S('Human-readable node name.'),
48
48
  memberName: S('Member (function/variable/event) name the node represents.'),
49
49
  memberClass: S('Member class (function, variable, event, etc.).'),
50
50
  targetClass: S('Target class for a node that carries one: a Cast target, a CreateWidget or '
51
- + 'SpawnActor class, or the subsystem a Get Subsystem node returns. Required '
51
+ + 'SpawnActor class, the subsystem a Get Subsystem node returns, or the class '
52
+ + 'GetAllActorsOfClass and GetActorOfClass look for (their result is then typed to it, '
53
+ + 'so a ForEach element wires to its functions). Required '
52
54
  + 'for cast and subsystem nodes, whose type is stored on the node itself and '
53
55
  + 'cannot be set afterwards.'),
54
56
  pinName: S('Pin name on a graph node.'),
@@ -53,6 +53,7 @@ export const SCS_COMPONENTS_RECORDS = [
53
53
  compiled: P.success,
54
54
  saved: P.success,
55
55
  scsVerification: { type: 'object', description: 'SCS node verification (exists, parent matches).', additionalProperties: true, 'x-unreal-reflection-boundary': true },
56
+ appliedProperties: { type: 'array', items: { type: 'string' }, description: 'The names in properties that took their value; one that did not apply fails the call and is named in the error.' },
56
57
  partWarnings: PART_WARNINGS,
57
58
  },
58
59
  outputRequired: ['componentName'],
@@ -123,8 +124,8 @@ export const SCS_COMPONENTS_RECORDS = [
123
124
  action: 'remove_scs_component',
124
125
  family: FAMILY,
125
126
  domain: DOMAIN,
126
- summary: 'Remove one or several SCS-owned component template nodes from the Blueprint.',
127
- whenToUse: ['An SCS component node and its template must be permanently removed.'],
127
+ summary: 'Remove one or several SCS-owned component template nodes from the Blueprint. As the editor deletes, the children move up to the removed node\'s parent, and removing a root makes its first scene child the root (DefaultSceneRoot gives way to the mesh under it).',
128
+ whenToUse: ['An SCS component node and its template must be permanently removed.', 'A mesh under DefaultSceneRoot must become the root, as physics simulation and buoyancy need: remove DefaultSceneRoot.'],
128
129
  whenNotToUse: ['The component should be detached but preserved (no detach action exists; remove is destructive).'],
129
130
  inputProps: {
130
131
  blueprintPath: P.blueprintPath, componentName: P.componentName,
@@ -132,6 +133,10 @@ export const SCS_COMPONENTS_RECORDS = [
132
133
  },
133
134
  required: ['blueprintPath'],
134
135
  requiredOneOf: ['componentName', 'componentNames'],
136
+ outputProps: {
137
+ promotedChildren: { type: 'array', items: { type: 'string' }, description: 'The removed component\'s children, which moved up instead of going with it.' },
138
+ newRoot: { type: 'string', description: 'The root after a root was removed, read back after the compile.' },
139
+ },
135
140
  effect: 'destructive',
136
141
  behavior: { safeToRetry: false },
137
142
  latency: 'interactive',
@@ -12,7 +12,10 @@ export const VARIABLES_METADATA_RECORDS = [
12
12
  summary: 'Add a new member variable to a Blueprint.',
13
13
  whenToUse: ['A Blueprint needs a new member variable with a type and default.'],
14
14
  whenNotToUse: ['A graph-local variable is needed (use create_node with a local variable).'],
15
- inputProps: { blueprintPath: P.blueprintPath, variableName: P.variableName, variableType: P.variableType, defaultValue: P.defaultValue, category: P.category, isReplicated: P.isReplicated, isPublic: P.isPublic },
15
+ inputProps: {
16
+ blueprintPath: P.blueprintPath, variableName: P.variableName, variableType: P.variableType, defaultValue: P.defaultValue, category: P.category, isReplicated: P.isReplicated, isPublic: P.isPublic,
17
+ exposeOnSpawn: { type: 'boolean', description: 'Expose on Spawn: the variable becomes an input pin on SpawnActor and Create Widget nodes for this class, set as the actor is made (before its BeginPlay). Makes it instance-editable too, as the editor does.' },
18
+ },
16
19
  required: ['blueprintPath', 'variableName', 'variableType'],
17
20
  outputProps: { variableName: P.variableName },
18
21
  outputRequired: ['variableName'],
@@ -121,7 +124,10 @@ export const VARIABLES_METADATA_RECORDS = [
121
124
  whenNotToUse: ['An SCS component template property is the target (use set_scs_property).'],
122
125
  inputProps: { blueprintPath: P.blueprintPath, propertyName: P.propertyName, propertyValue: P.propertyValue },
123
126
  required: ['blueprintPath', 'propertyName'],
124
- outputProps: { value: { description: 'Property value re-read from the Class Default Object after the write. Emitted on the literal path only and omitted when the value cannot be exported to JSON.' } },
127
+ outputProps: {
128
+ value: { description: 'Property value re-read from the Class Default Object after the write. Emitted on the literal path only and omitted when the value cannot be exported to JSON.' },
129
+ instancesUpdated: { type: 'number', description: 'Placed actors (in loaded levels) that still held the old default and took the new value, as the Details panel propagates a class default; an actor that overrides the value keeps it. Save the level to keep them.' },
130
+ },
125
131
  effect: 'write',
126
132
  behavior: { idempotency: 'idempotent', safeToRetry: true },
127
133
  latency: 'instant',
@@ -64,16 +64,26 @@ export const WIDGET_ANIMATION_RECORDS = [
64
64
  action: 'add_animation_keyframe',
65
65
  family: FAMILY,
66
66
  domain: DOMAIN,
67
- summary: 'Add a keyframe at a specific time on a widget animation track.',
68
- whenToUse: ['A property value must be keyframed at a specific time in a widget animation.'],
67
+ summary: 'Add a keyframe at a specific time on a widget animation track, or a whole animation across several widgets in one call (keys).',
68
+ whenToUse: [
69
+ 'A property value must be keyframed at a specific time in a widget animation.',
70
+ 'A whole widget animation (a logo popping in, a menu sliding up, a pulse) must be keyed in one call (keys).',
71
+ ],
69
72
  whenNotToUse: ['The track should be removed rather than keyframed.'],
70
73
  inputProps: { widgetPath: P.widgetPath, animationName: P.animationName, trackType: P.trackType, slotName: P.slotName, time: P.time,
71
74
  propertyValue: { description: 'The key value, by trackType: opacity a number 0-1; color {r,g,b,a} or [r,g,b,a]; translation, scale or shear {x,y} or [x,y]; angle a number in degrees; transform any of {translation:{x,y}, scale:{x,y}, angle, shear:{x,y}}. A value of the wrong shape is refused before anything is added.' },
72
75
  interpolation: P.interpolation,
73
- value: { type: 'number', description: 'A plain number for an opacity or angle key, in place of propertyValue.' } },
74
- required: ['widgetPath', 'animationName', 'time'],
76
+ value: { type: 'number', description: 'A plain number for an opacity or angle key, in place of propertyValue.' },
77
+ keys: {
78
+ type: 'array', minItems: 1, maxItems: 200,
79
+ items: { type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true },
80
+ 'x-unreal-reflection-boundary': true,
81
+ description: 'Many keyframes in one call, in place of time: each {time, propertyValue or value, and any of slotName, trackType, interpolation that differ from the call\'s own}. Every key is checked before any is written: a refused one is named by its index (keys[3]) and nothing is added. The Widget Blueprint is saved once.',
82
+ } },
83
+ required: ['widgetPath', 'animationName'],
75
84
  outputProps: {
76
85
  ...TRACK_OUTPUT,
86
+ keysAdded: { type: 'number', description: 'With keys: how many keyframes were added; the other fields describe the last one.' },
77
87
  time: { type: 'number', description: 'Key time in seconds.' },
78
88
  frameNumber: { type: 'number', description: 'Key position in MovieScene tick-resolution frames.' },
79
89
  keyCount: { type: 'number', description: 'Keys on the last channel written after this call.' },