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

package/dist/tools/catalog/capabilities/records/aggregate.d.ts

@@ -1,4 +1,4 @@
 import type { CapabilityRecord } from '../model.js';
-export declare const ALL_CAPABILITY_RECORD_COUNT: 393;
+export declare const ALL_CAPABILITY_RECORD_COUNT: 405;
 export declare const ALL_CAPABILITY_RECORDS: readonly CapabilityRecord[];
 //# sourceMappingURL=aggregate.d.ts.map

package/dist/tools/catalog/capabilities/records/aggregate.js

@@ -22,7 +22,7 @@ import { SYSTEM_CONTROL_SOURCES } from './system-control/index.js';
 import { MANAGE_GEOMETRY_SOURCES } from './world/manage-geometry.index.js';
 import { MANAGE_LEVEL_STRUCTURE_SOURCES } from './world/manage-level-structure.index.js';
 import { MANAGE_PCG_SOURCES } from './world/manage-pcg.index.js';
-export const ALL_CAPABILITY_RECORD_COUNT = 393;
+export const ALL_CAPABILITY_RECORD_COUNT = 405;
 const ALL_SOURCES = [
     ...BUILD_ENVIRONMENT_SOURCES,
     ...MANAGE_LEVEL_STRUCTURE_SOURCES,

package/dist/tools/catalog/capabilities/records/build-environment/spline.data.js

@@ -3,6 +3,7 @@ import { P } from './properties.js';
 const F = 'spline';
 const WU = ['A spline actor or spline mesh must be created or modified.'];
 const ACTOR_PATH = { ...P.actorPath, description: 'Object path of the spline actor; used when actorName is omitted.' };
+const SPLINE_POSITION = { ...P.position, description: 'Point position relative to the spline actor {x, y, z}: its local space, the location get_splines_info with actorName reports (worldLocation is where the point lies in the level).' };
 const TEMPLATE = {
     name: P.name, location: P.location, meshPath: P.meshPath, points: P.points,
     materialPath: P.materialPath, width: { ...P.width, description: 'Width of the deformed mesh ribbon in world units (default 400).' }, closedLoop: P.closedLoop,
@@ -21,7 +22,7 @@ export const SPLINE_RECORDS = [
         id: 'build_environment.add_spline_point', action: 'add_spline_point', family: F,
         summary: 'Add a point to an existing spline.',
         whenToUse: WU, whenNotToUse: ['The spline should be recreated with all points.'],
-        inputProps: { actorName: P.actorName, actorPath: ACTOR_PATH, position: P.position, index: P.index,
+        inputProps: { actorName: P.actorName, actorPath: ACTOR_PATH, position: SPLINE_POSITION, index: P.index,
             arriveTangent: P.arriveTangent, leaveTangent: P.leaveTangent, pointType: P.pointType },
         required: [], effect: 'write', latency: 'interactive', resources: 'low',
         exampleInput: { action: 'add_spline_point', actorName: 'Spline_1', position: { x: 100, y: 0, z: 0 } },
@@ -38,7 +39,7 @@ export const SPLINE_RECORDS = [
         id: 'build_environment.set_spline_point_position', action: 'set_spline_point_position', family: F,
         summary: 'Set the position of a spline point by index.',
         whenToUse: WU, whenNotToUse: ['The point should be moved interactively.'],
-        inputProps: { actorName: P.actorName, actorPath: ACTOR_PATH, pointIndex: P.pointIndex, position: P.position },
+        inputProps: { actorName: P.actorName, actorPath: ACTOR_PATH, pointIndex: P.pointIndex, position: SPLINE_POSITION },
         required: [], effect: 'write', behavior: { idempotency: 'idempotent' }, latency: 'interactive', resources: 'low',
         exampleInput: { action: 'set_spline_point_position', actorName: 'Spline_1', pointIndex: 0, position: { x: 0, y: 0, z: 100 } },
     }),
@@ -185,7 +186,7 @@ export const SPLINE_RECORDS = [
     buildRecord({
         id: 'build_environment.get_splines_info', action: 'get_splines_info', family: F,
         topics: ['point count and length', 'closed loop', 'world points'],
-        summary: 'List the spline actors in the level with each one\'s point count, length and world points (first 64); with actorName, one spline\'s points and types, length and closed-loop flag.',
+        summary: 'List the spline actors in the level with each one\'s point count, length and world points (first 64); with actorName, one spline\'s points (location relative to the actor, the space spline edits take, and worldLocation), types, length and closed-loop flag.',
         whenToUse: ['Spline actors must be enumerated.'],
         whenNotToUse: ['A specific spline path is already known.'],
         inputProps: { actorName: P.actorName },

package/dist/tools/catalog/capabilities/records/build-environment/water.data.js

@@ -13,7 +13,7 @@ const TARGET = { waterBodyName: { ...P.waterBodyName, description: 'Water body t
 export const WATER_RECORDS = [
     buildRecord({
         id: 'build_environment.create_water_body_ocean', action: 'create_water_body_ocean', family: F,
-        summary: 'Create an ocean water body actor.',
+        summary: 'Create an ocean water body actor with the editor\'s default ocean material and waves.',
         whenToUse: WU, whenNotToUse: ['A lake or river water body is needed.'],
         inputProps: BODY,
         required: [], effect: 'write', latency: 'interactive', resources: 'medium',
@@ -45,10 +45,13 @@ export const WATER_RECORDS = [
     }),
     buildRecord({
         id: 'build_environment.configure_water_waves', action: 'configure_water_waves', family: F,
-        summary: 'Configure water wave settings (height, length, amplitude).',
+        summary: 'Give a water body Gerstner waves, the swell its surface and anything floating on it follow: height, wavelength, steepness and wind direction. The call fails when the body does not end up holding the waves.',
         whenToUse: WU, whenNotToUse: ['Default waves are sufficient.'],
-        inputProps: { waveHeight: P.waveHeight, waveLength: P.waveLength,
-            amplitude: P.amplitude, steepness: P.steepness, direction: P.direction, ...TARGET },
+        inputProps: { waveHeight: { ...P.waveHeight, description: 'Height (amplitude) of the largest wave in cm; the body\'s other waves shrink to 15% of it, as a real sea\'s do. A calm harbour is about 5-10, open sea 50 or more.' },
+            waveLength: { ...P.waveLength, description: 'Wavelength of the longest wave in cm, crest to crest; the shortest waves are 13% of it (a harbour is about 1500-2500).' },
+            amplitude: { ...P.amplitude, description: 'Same as waveHeight; waveHeight wins when both are given.' },
+            steepness: { ...P.steepness, description: 'Crest sharpness of the short waves, 0 (smooth swell) to 1 (peaked); the long waves take about half. Keep it under about 0.3: steep crests from many waves fold the surface over itself.' },
+            direction: { ...P.direction, description: 'Wind direction: its yaw sets where the waves travel.' }, ...TARGET },
         required: [], effect: 'write', behavior: { idempotency: 'idempotent' }, latency: 'interactive', resources: 'low',
         exampleInput: { action: 'configure_water_waves', waveHeight: 1.0, waveLength: 10 },
     }),
@@ -70,7 +73,7 @@ export const WATER_RECORDS = [
     }),
     buildRecord({
         id: 'build_environment.create_buoyancy_component', action: 'create_buoyancy_component', topics: ['make a boat float'], family: F,
-        summary: 'Create a buoyancy component on an actor for water interaction.',
+        summary: 'Make an actor float: add a buoyancy component (pontoons in settings.BuoyancyData) to an actor whose root is a physics-simulating mesh, and let it take the water body\'s overlap at level load, so one placed already in the water floats instead of sinking. In a Blueprint, add /Script/Water.BuoyancyComponent with edit_scs and set the class default bGenerateOverlapEventsDuringLevelStreaming to true.',
         whenToUse: WU, whenNotToUse: ['Buoyancy is not needed.'],
         inputProps: { actorPath: P.actorPath, actorName: P.actorName, targetActor: P.targetActor, settings: P.settings },
         required: [], effect: 'write', latency: 'interactive', resources: 'low',

package/dist/tools/catalog/capabilities/records/control-actor/advanced-records.js

@@ -1,5 +1,6 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { DOMAIN, P } from './properties.js';
+import { bool, str, vec3 } from '../shared/schema-props.js';
 const FAMILY_ATTACH = 'attachment';
 const FAMILY_BLUEPRINT = 'blueprint';
 const FAMILY_SNAPSHOT = 'snapshot';
@@ -12,10 +13,17 @@ export const ADVANCED_RECORDS = [
         domain: DOMAIN,
         family: FAMILY_ATTACH,
         topics: ['attach actor', 'parent actor', 'attach to actor', 'child actor', 'attach to socket', 'set actor parent'],
-        summary: 'Attach a child actor to a parent actor in the scene hierarchy.',
-        whenToUse: ['An actor must follow another actor transform.'],
+        summary: 'Attach a child actor to a parent actor in the scene hierarchy, or to a bone or socket of one of its components (a weapon or a case to a hand).',
+        whenToUse: ['An actor must follow another actor transform.', 'A prop must ride a character\'s hand, head or other bone: socketName with snapToTarget, then tune the grip with relativeLocation/relativeRotation.'],
         whenNotToUse: ['The actor should remain independent (use detach).'],
-        inputProps: { childActor: P.childActor, parentActor: P.parentActor },
+        inputProps: {
+            childActor: P.childActor, parentActor: P.parentActor,
+            componentName: str('Component of the parent actor to attach to (default its root): on a character built from several meshes, the mesh that owns the bone.'),
+            socketName: str('Bone or socket on that component to attach to (hand_r, weapon_r, head). Refused with SOCKET_NOT_FOUND when the component has neither.'),
+            snapToTarget: bool('Snap the child onto the bone or socket instead of keeping its current world placement (default false).'),
+            relativeLocation: vec3('With snapToTarget: offset from the bone or socket in its own space, as [x, y, z].'),
+            relativeRotation: vec3('With snapToTarget: rotation relative to the bone or socket, as [pitch, yaw, roll] in degrees.'),
+        },
         required: ['childActor', 'parentActor'],
         effect: 'write',
         costLatency: 'interactive',
@@ -80,7 +88,7 @@ export const ADVANCED_RECORDS = [
         family: FAMILY_COLLISION,
         summary: 'Enable or disable collision on an actor, or on many actors at once with actorNames, as one undoable step; normalizes to set_collision.',
         whenToUse: ['Actor collision must be toggled.', 'Many actors must have collision toggled together (actorNames does them in one call).'],
-        whenNotToUse: ['Per-component collision is required (use set_component_property).'],
+        whenNotToUse: ['One component only, or a mode other than on and off (QueryOnly, PhysicsOnly): use edit_component (edit set_properties) with CollisionEnabled, which takes the ECollisionEnabled names.'],
         inputProps: {
             actorName: P.actorName,
             actorNames: { type: 'array', items: { type: 'string' }, description: 'Several actors to toggle in one call and one undo step, in place of actorName; names not found are listed back under missing, and the actors changed under affectedActors (which the receipt lists as changes, with an actor handle each).' },
@@ -95,12 +103,25 @@ export const ADVANCED_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'call_actor_function',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_FUNCTION,
-        summary: 'Call a named function on an actor with optional arguments; normalizes to call_function.',
-        whenToUse: ['A Blueprint or native function on an actor must be invoked.'],
+        summary: 'Call a named function on an actor, or while Play In Editor runs on the game\'s GameInstance, GameMode or another framework object, with optional arguments; normalizes to call_function.',
+        whenToUse: [
+            'A Blueprint or native function on an actor must be invoked.',
+            'A function of the running game\'s GameInstance (save, score, reset) must be called during Play In Editor: actorName GameInstance.',
+            'A function of one of the actor\'s components must be called (a body\'s GetCenterOfMass, a movement component\'s StopMovementImmediately): componentName.',
+        ],
         whenNotToUse: ['The function has side effects that cannot be undone.'],
-        inputProps: { actorName: P.actorName, functionName: P.functionName, arguments: P.arguments },
+        inputProps: {
+            actorName: {
+                ...P.actorName,
+                description: 'Target actor name in the current level; while Play In Editor runs, GameInstance, GameMode, GameState, PlayerController, PlayerPawn, PlayerState or HUD names that object of the running game (the GameInstance is no actor).',
+            },
+            componentName: str('Call the function on this component of the actor instead of on the actor itself (refused with COMPONENT_NOT_FOUND when the actor has none of that name).'),
+            functionName: P.functionName,
+            arguments: P.arguments,
+        },
         required: ['actorName', 'functionName'],
         outputProps: { value: P.value },
         outputRequired: [],

package/dist/tools/catalog/capabilities/records/control-actor/search-records.js

@@ -147,7 +147,7 @@ export const SEARCH_RECORDS = [
         summary: 'Find all actors in the level matching a Unreal class name or path.',
         whenToUse: ['All instances of a class must be located.'],
         whenNotToUse: ['A tag-based lookup is more appropriate (use find_by_tag).'],
-        inputProps: { className: P.className, class: { type: 'string', description: 'Unreal class name or path (alias of className).' }, classPath: { type: 'string', description: 'Unreal class path (e.g. /Script/Engine.PointLight or /Game/Enemies/BP_Bug) of the actors to find (alias of className).' } },
+        inputProps: { className: P.className, class: { type: 'string', description: 'Unreal class name or path (alias of className).' }, classPath: { type: 'string', description: 'Unreal class path (e.g. /Script/Engine.PointLight or /Game/Enemies/BP_Enemy) of the actors to find (alias of className).' } },
         required: [],
         requiredOneOf: ['className', 'class', 'classPath'],
         outputProps: FIND_OUTPUT,
@@ -164,7 +164,7 @@ export const SEARCH_RECORDS = [
         summary: 'Alias of find_by_class. The bridge dispatches both names to the same handler.',
         whenToUse: ['Preferred when callers use the explicit find_actors_by_class verb.'],
         whenNotToUse: ['Use find_by_class to avoid alias normalization.'],
-        inputProps: { className: P.className, class: { type: 'string', description: 'Unreal class name or path (alias of className).' }, classPath: { type: 'string', description: 'Unreal class path (e.g. /Script/Engine.PointLight or /Game/Enemies/BP_Bug) of the actors to find (alias of className).' } },
+        inputProps: { className: P.className, class: { type: 'string', description: 'Unreal class name or path (alias of className).' }, classPath: { type: 'string', description: 'Unreal class path (e.g. /Script/Engine.PointLight or /Game/Enemies/BP_Enemy) of the actors to find (alias of className).' } },
         required: [],
         requiredOneOf: ['className', 'class', 'classPath'],
         outputProps: FIND_OUTPUT,

package/dist/tools/catalog/capabilities/records/control-actor/spawn-records.js

@@ -1,4 +1,4 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { bool, num, str } from '../shared/schema-props.js';
 import { DOMAIN, P } from './properties.js';
 const FAMILY_SPAWN = 'spawn';
@@ -12,7 +12,7 @@ const SPAWN_UNDO = {
 const SPAWN_PLACEMENT = {
     groundZ: num('Z of the solid surface under the actor; absent when nothing is below it.'),
     groundClearance: num('How far the bottom of the actor\'s bounds sits above that surface; negative means it is sunk into it.'),
-    placementWarning: str('Present when the placement looks wrong: it intersects other actors, is sunk below the surface under it (the bottom of its bounds is under it, wherever its pivot is; suggestedLocation rests it), floats more than 50 units above it, or has nothing below it (an actor held up from the side is mounted, never floating: see mountedOn). Tag the actor mcp.placement.ok when that is deliberate and it is never reported.'),
+    placementWarning: str('Present when the placement looks wrong: it intersects other actors, is sunk below the surface under it (the bottom of its bounds is under it, wherever its pivot is; suggestedLocation rests it), floats more than 50 units above it, or has nothing below it (an actor held up from the side is mounted, never floating: see mountedOn). A water body is a surface, not a solid: an actor partly under water (a buoy, a hull, a wading pawn) is neither intersecting nor sunk, and groundZ is the water level. Tag the actor mcp.placement.ok when that is deliberate and it is never reported.'),
     mountedOn: str('The actor this one hangs on from the side (a window band flush on a hall, an awning on a facade): its bounds touch or overlap that actor\'s vertical face, so it is held up and is not reported floating or without a surface below. Present only then.'),
     overlappingActors: {
         type: 'array',
@@ -31,6 +31,7 @@ export const SPAWN_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'spawn',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_SPAWN,
         topics: ['spawn actor', 'place actor', 'add actor to level', 'create actor', 'spawn cube', 'spawn static mesh', 'instantiate class'],
@@ -70,6 +71,7 @@ export const SPAWN_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'spawn_blueprint',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_SPAWN,
         topics: ['spawn blueprint actor', 'place blueprint in level', 'instantiate blueprint'],
@@ -103,6 +105,7 @@ export const SPAWN_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'spawn_batch',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_SPAWN,
         topics: ['spawn many actors', 'batch spawn', 'place many actors', 'lay out level', 'build level layout'],
@@ -117,7 +120,8 @@ export const SPAWN_RECORDS = [
                 description: 'Actors to spawn, 1-500. Each is a spawn payload: classPath, blueprintPath or meshPath, plus '
                     + 'actorName, location, rotation, scale ([x, y, z] arrays). Optional per item: materialPath (applied like '
                     + 'set_material; componentName/materialSlot/allComponents narrow it), variables ({name: value} Blueprint '
-                    + 'variables set on the new instance, like set_blueprint_variables), folder (outliner folder path), tags '
+                    + 'variables set on the new instance, like set_blueprint_variables; in a running game they are set before its '
+                    + 'BeginPlay, so it starts with them), folder (outliner folder path), tags '
                     + '(actor tags; delete_by_tag removes the batch again). Items that fail are reported; the rest still spawn.',
             },
             defaults: {
@@ -144,8 +148,9 @@ export const SPAWN_RECORDS = [
                 type: 'array',
                 items: { type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true },
                 'x-unreal-reflection-boundary': true,
-                description: 'Per item (only the failed ones and those with a placementWarning under report: failures): index, success, '
-                    + 'name, path, error, errorCode, variablesSet, variablesError, materialApplied, materialError, and the placement '
+                description: 'Per item (only the failed ones and those with a placementWarning or ignoredKeys under report: failures): '
+                    + 'index, success, name, path, error, errorCode, variablesSet, variablesError, materialApplied, materialError, '
+                    + 'ignoredKeys (the item\'s keys no spawn reads, such as a "label" meant as actorName), and the placement '
                     + 'facts set_transform reports (groundZ, groundClearance, placementWarning, overlappingActors, suggestedLocation), '
                     + 'measured after the item took its tags, variables and material, so an item tagged mcp.placement.ok is never '
                     + 'reported. name is the label the item asked for, or the unique actor name when it gave no actorName.',
@@ -239,6 +244,7 @@ export const SPAWN_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'delete',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_LIFECYCLE,
         topics: ['delete actor', 'destroy actor', 'remove actor from level', 'delete selected actor', 'delete spawned actor', 'delete object'],
@@ -257,6 +263,7 @@ export const SPAWN_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'destroy_actor',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_LIFECYCLE,
         summary: 'Long-form alias for delete. The bridge dispatches both names to the same handler.',
@@ -273,6 +280,7 @@ export const SPAWN_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'delete_by_tag',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_LIFECYCLE,
         summary: 'Permanently delete every actor matching a gameplay tag, or any of several tags in one call.',

package/dist/tools/catalog/capabilities/records/control-actor/state-records.js

@@ -1,4 +1,4 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { DOMAIN, P } from './properties.js';
 const FAMILY_VISIBILITY = 'visibility';
 const FAMILY_QUERY = 'query';
@@ -93,6 +93,7 @@ export const STATE_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'list',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_QUERY,
         topics: ['list actors', 'all actors in level', 'actors in scene', 'enumerate actors', 'world outliner', 'actors in level', 'level actors', 'actor positions', 'actor locations', 'actor transforms', 'level layout', 'variable values of many actors', 'how many actors', 'count actors', 'actors in the level', 'actors near point', 'count enemies'],

package/dist/tools/catalog/capabilities/records/control-actor/transform-records.js

@@ -1,4 +1,4 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { DOMAIN, P } from './properties.js';
 const FAMILY_TRANSFORM = 'transform';
 const FAMILY_PHYSICS = 'physics';
@@ -59,6 +59,7 @@ export const TRANSFORM_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'set_transform',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_TRANSFORM,
         topics: ['move actor', 'set actor location', 'set position', 'rotate actor', 'set rotation', 'scale actor', 'teleport actor', 'translate'],
@@ -78,6 +79,7 @@ export const TRANSFORM_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'teleport_actor',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_TRANSFORM,
         summary: 'Alias of set_transform. The bridge dispatches both names to the same handler.',
@@ -95,6 +97,7 @@ export const TRANSFORM_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'set_actor_location',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_TRANSFORM,
         summary: 'Alias of set_transform (location-only intent); normalizes to set_transform.',
@@ -112,6 +115,7 @@ export const TRANSFORM_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'set_actor_rotation',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_TRANSFORM,
         summary: 'Alias of set_transform (rotation-only intent); normalizes to set_transform.',
@@ -129,6 +133,7 @@ export const TRANSFORM_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'set_actor_scale',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_TRANSFORM,
         summary: 'Alias of set_transform (scale-only intent); normalizes to set_transform.',
@@ -146,6 +151,7 @@ export const TRANSFORM_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_actor',
         action: 'get_transform',
+        editorStates: ANY_EDITOR_STATE,
         domain: DOMAIN,
         family: FAMILY_TRANSFORM,
         topics: ['actor location', 'actor position', 'actor rotation', 'where is the actor'],
@@ -164,14 +170,16 @@ export const TRANSFORM_RECORDS = [
         ...buildCoreRecord({
             parentTool: 'control_actor',
             action: 'sample_motion',
+            editorStates: ANY_EDITOR_STATE,
             domain: DOMAIN,
             family: FAMILY_TRANSFORM,
-            topics: ['sample motion', 'record trajectory', 'track actor over time', 'watch actor move', 'jump height'],
-            summary: 'Watch an actor over game time in Play-In-Editor and return its location, velocity and chosen properties at every interval, plus start/end and min/max extents, in one call; it can also press keys at exact game times (inputs) and wait for another actor\'s property to change before it starts (startWhen).',
+            topics: ['sample motion', 'record trajectory', 'track actor over time', 'watch actor move', 'jump height', 'foot sliding', 'bone position over time'],
+            summary: 'Watch an actor over game time in Play-In-Editor and return its location, velocity, rotation and chosen properties at every interval, plus start/end and min/max extents, in one call; it can also follow points on the actor (bones, sockets, components) with their height over the ground, press keys at exact game times (inputs) and wait for another actor\'s property to change before it starts (startWhen).',
             whenToUse: [
                 'A jump, spring launch, moving platform, enemy patrol or fall must be proven in PIE without a sleep-and-poll loop.',
                 'The peak height, landing point or path of a moving actor is needed.',
                 'An input must land at an exact moment (jump when a platform appears): inputs and startWhen run the whole timeline inside one call, so the caller\'s own delay between calls cannot shift it.',
+                'Feet must be proven to plant without sliding, sinking or floating, or a hand or muzzle must be followed: points with groundTrace measure it per point.',
             ],
             whenNotToUse: ['Only the current transform is needed (use get_transform).', 'Nothing is playing: the editor world does not simulate (start PIE with control_editor.play).'],
             inputProps: {
@@ -194,11 +202,17 @@ export const TRANSFORM_RECORDS = [
                     },
                     description: 'Keys pressed and released at exact game times during the run (at most 32), e.g. [{"key":"D","atSeconds":0,"holdSeconds":2},{"key":"SpaceBar","atSeconds":0.6,"holdSeconds":0.2}]. A key still held when the run ends is released.',
                 },
+                points: {
+                    type: 'array', items: { type: 'string' }, maxItems: 8,
+                    description: 'Places on the actor sampled with it (at most 8): a component by its name (LegL), a bone or socket of any of its components (foot_l, hand_r), or a component\'s own socket as Component.Socket (Weapon.Muzzle). Each sample\'s points gives each one\'s world location [x, y, z]; a name the actor lacks is refused with the names it has. Fewer samples are kept with points: 400 x 2 / (2 + points).',
+                },
+                groundTrace: { type: 'boolean', description: 'With points: each sample\'s aboveGround gives each point\'s height over the first surface below it that blocks Visibility (the actor and what is attached to it ignored), negative when the point is inside that surface, and pointStats sums up its contact.' },
+                contactCm: { type: 'number', description: 'With groundTrace: how far above its own lowest height a point still counts as planted (default 2 cm), so an ankle bone that never reaches the floor still counts as down when the foot is.' },
                 startWhen: {
                     type: 'object',
                     properties: {
                         actorName: { type: 'string', description: 'Actor whose property starts the run.' },
-                        propertyName: { type: 'string', description: 'That actor\'s property, as propertyNames reads it (e.g. bActorEnableCollision).' },
+                        propertyName: { type: 'string', description: 'That actor\'s property, as propertyNames reads it: bActorEnableCollision, or a component\'s as Component.Property (CharacterMovement.MovementMode starts the run on a landing when equals is MOVE_Walking).' },
                         equals: { description: 'Value that starts the run, as samples show it ("True", "False", 3).' },
                         waitForChange: { type: 'boolean', description: 'Default true: start only when the value BECOMES equals (a platform appearing), not while it already is.' },
                         maxWaitSeconds: { type: 'number', description: 'Game seconds to wait before giving up with endedBecause startWhenTimeout (default 10, at most 30).' },
@@ -213,12 +227,12 @@ export const TRANSFORM_RECORDS = [
                 actorName: { type: 'string', description: 'The actor watched.' },
                 samples: {
                     type: 'array', items: { type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true },
-                    description: 'One entry per sample: t (game seconds since the start), location [x, y, z], velocity [x, y, z], properties.',
+                    description: 'One entry per sample: t (game seconds since the start), location [x, y, z], velocity [x, y, z], rotation [pitch, yaw, roll] in degrees (on the first sample and on each one where it changed, so a sample without it still has the last one written), properties, and with points their world locations (points) and heights over the ground (aboveGround, with groundTrace; a point with nothing below it within 10 m is left out).',
                 },
                 sampleCount: { type: 'number', description: 'How many samples were taken.' },
                 gameSeconds: { type: 'number', description: 'Game time covered.' },
                 realSeconds: { type: 'number', description: 'Wall-clock time the run took.' },
-                endedBecause: { type: 'string', description: 'duration, realTimeCap, sampleCap, actorDestroyed (a PIE death that reloads the level ends here), worldEnded (PIE stopped) or startWhenTimeout (startWhen never happened within maxWaitSeconds).' },
+                endedBecause: { type: 'string', description: 'duration, realTimeCap, sampleCap, actorDestroyed (a PIE death that reloads the level ends here), worldEnded (PIE stopped), startWhenTimeout (startWhen never happened within maxWaitSeconds) or gamePaused (game time stood still for 3 s: a title or pause menu holds the game; the warning says how to get past it).' },
                 inputsApplied: {
                     type: 'array', items: { type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true },
                     description: 'One entry per input: key, at, hold, and down/up, the game seconds since the start when it was pressed and released (up is when the run ended for a key still held).',
@@ -229,6 +243,10 @@ export const TRANSFORM_RECORDS = [
                 min: { type: 'array', items: { type: 'number' }, description: 'Smallest x, y and z sampled (the lowest point is min[2]).' },
                 max: { type: 'array', items: { type: 'number' }, description: 'Largest x, y and z sampled (the peak height is max[2]).' },
                 missingProperties: { type: 'array', items: { type: 'string' }, description: 'propertyNames the actor\'s class does not have.' },
+                pointStats: {
+                    type: 'object', additionalProperties: true, 'x-unreal-reflection-boundary': true,
+                    description: 'Per point: min and max [x, y, z] over the run; with groundTrace also minAboveGround and maxAboveGround (a negative minimum means it sank into the surface, a large one that it never touched it), contactSeconds (time spent planted) and contactSlip (cm it moved across the ground while planted: a planted foot that slides shows here).',
+                },
                 windowRestored: { type: 'boolean', description: 'True when the editor window was minimized: a minimized editor runs PIE at about 3 fps, so it was put back on screen, without taking focus, before the run and is minimized again when the run ends. The background CPU throttle (Use Less CPU when in Background) is off for the run only, whatever the window did.' },
             },
             outputRequired: [],
@@ -236,9 +254,9 @@ export const TRANSFORM_RECORDS = [
             costLatency: 'interactive',
             exampleInput: { action: 'sample_motion', actorName: 'PlayerPawn', durationSeconds: 1.5, propertyNames: ['bDead'] },
             exampleOutput: {
-                success: true, message: '31 samples of BP_Mario_C_0 over 1.50 game seconds (duration)',
-                actorName: 'BP_Mario_C_0', sampleCount: 31, gameSeconds: 1.5, realSeconds: 3.2, endedBecause: 'duration',
-                samples: [{ t: 0, location: [8500, 0, 56.1], velocity: [0, 0, 0], properties: { bDead: 'False' } }],
+                success: true, message: '31 samples of BP_Hero_C_0 over 1.50 game seconds (duration)',
+                actorName: 'BP_Hero_C_0', sampleCount: 31, gameSeconds: 1.5, realSeconds: 3.2, endedBecause: 'duration',
+                samples: [{ t: 0, location: [8500, 0, 56.1], velocity: [0, 0, 0], rotation: [0, 90, 0], properties: { bDead: 'False' } }],
                 start: [8500, 0, 56.1], end: [9310, 0, 130.2], min: [8500, 0, 56.1], max: [9310, 0, 302.4],
             },
         }),

package/dist/tools/catalog/capabilities/records/control-editor/asset.js

@@ -106,7 +106,10 @@ export const ASSET_RECORDS = [
             assetPaths: { type: 'array', items: { type: 'string' }, description: 'Save only these assets or levels, e.g. ["/Game/UI/WBP_Menu"], and leave every other dirty package as it is; omit to save everything dirty.' },
         },
         required: [],
-        outputProps: { compensation: COMPENSATION },
+        outputProps: {
+            compensation: COMPENSATION,
+            leftDirtyPackages: { type: 'array', items: { type: 'string' }, description: 'With assetPaths: the other packages that still hold unsaved changes, left as they were.' },
+        },
         effect: 'write',
         costLatency: 'interactive', costResources: 'medium',
         exampleInput: { action: 'save_all' },

package/dist/tools/catalog/capabilities/records/control-editor/camera.js

@@ -1,10 +1,11 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { P } from './properties.js';
 const F = 'camera';
 const D = 'editor';
 export const CAMERA_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_editor', action: 'set_view_target', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Set the PIE view target to a specific actor by name.',
         whenToUse: ['The camera must follow or focus on a specific actor in PIE.'],
         whenNotToUse: ['A fixed camera position is preferred (use set_camera).'],
@@ -15,6 +16,7 @@ export const CAMERA_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'set_game_view_target', dispatchAction: 'set_view_target',
+        editorStates: ANY_EDITOR_STATE,
         domain: D, family: F,
         summary: 'Set the PIE view target (alias for set_view_target).',
         whenToUse: ['The camera view target must be set using the set_game_view_target alias.'],
@@ -26,6 +28,7 @@ export const CAMERA_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'set_camera', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Set the viewport camera position and rotation: the level viewport, or, while Play In Editor runs with the player ejected (control_editor play control=eject), the free camera the game view is drawn from.',
         whenToUse: [
             'The viewport camera must be moved to a specific position and orientation.',
@@ -49,6 +52,7 @@ export const CAMERA_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'set_camera_fov', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Set the camera field of view of the view on screen: the level viewport, the free view of an ejected player, or while the player plays the running game\'s camera (method player_camera_manager; locked to the value until play stops).',
         whenToUse: ['The camera FOV must be adjusted for the viewport.'],
         whenNotToUse: ['The default FOV is acceptable.'],

package/dist/tools/catalog/capabilities/records/control-editor/command.js

@@ -1,4 +1,4 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { P } from './properties.js';
 const F = 'command';
 const D = 'editor';
@@ -176,6 +176,7 @@ export const COMMAND_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'open_editor_tab', dispatchAction: 'control_editor',
+        editorStates: ANY_EDITOR_STATE,
         domain: D, family: F,
         summary: 'Open a registered editor tab by id via FGlobalTabmanager, the same path the Window menu uses. Content-source plugins register their windows globally — Bridge as "BridgeTab" — so this reaches them without depending on either plugin. Fab registers no fixed id (it numbers each tab Fab1, Fab2, ...), so tabId "Fab" opens a new Fab tab through the Fab browser API (UE 5.8+). This is also the correct way to authenticate against those services: each owns its own sign-in and persists its own session, so opening its window lets it log in on its own terms rather than reimplementing a login.',
         whenToUse: [
@@ -198,6 +199,7 @@ export const COMMAND_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'console_command', dispatchAction: 'console_command',
+        editorStates: ANY_EDITOR_STATE,
         domain: D, family: F,
         topics: ['console command', 'exec command', 'run command', 'stat fps', 'cheat command', 'type a cheat code'],
         summary: 'Execute an Unreal console command via cross-parent dispatch to the console_command bridge action.',
@@ -210,6 +212,7 @@ export const COMMAND_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'restore_editor_window', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Restore or minimize the main editor window without giving it focus. Restoring also stops the editor throttling itself '
             + 'while in the background (a minimized editor runs Play In Editor at about 3 fps, which makes every timed test lie); '
             + 'minimize puts the window away and turns the throttle back on, so an editor kept out of the way costs the machine next to nothing.',
@@ -235,6 +238,7 @@ export const COMMAND_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'set_preferences', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Set editor preferences for a category. Distinct from system_control set_project_setting.',
         whenToUse: ['Editor preferences must be configured for a category.'],
         whenNotToUse: ['Project settings are needed (use system_control set_project_setting).'],

package/dist/tools/catalog/capabilities/records/control-editor/input.js

@@ -1,10 +1,11 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { P } from './properties.js';
 const F = 'input';
 const D = 'editor';
 export const INPUT_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_editor', action: 'simulate_input', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         aliases: ['control_editor.click_widget', 'control_editor.widget_click', 'control_editor.press_ui_button'],
         topics: ['click button', 'click ui button', 'click button in running game', 'check or toggle a checkbox in running game', 'press key', 'press jump key', 'simulate key press', 'drive game ui', 'test running game', 'list live widgets', 'list widgets in running game', 'widgets on screen', 'list buttons on screen', 'press space', 'press spacebar', 'hold key down', 'list open widgets in game'],
         summary: 'Simulate a keyboard or mouse input event (key_down, key_up, key_tap, mouse_click, mouse_move), or list and press the live UMG widgets of a PIE session (widget_list, widget_click).',

package/dist/tools/catalog/capabilities/records/control-editor/screenshot.js

@@ -1,4 +1,4 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { P } from './properties.js';
 const F = 'screenshot';
 const D = 'editor';
@@ -60,6 +60,7 @@ const SCREENSHOT_OUTPUT = {
 export const SCREENSHOT_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_editor', action: 'screenshot', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Capture a screenshot from the editor viewport, game viewport, or full editor window.',
         whenToUse: ['A visual snapshot of the editor or game viewport is needed.'],
         whenNotToUse: ['A real-time capture stream is needed.'],

package/dist/tools/catalog/capabilities/records/control-editor/session.js

@@ -1,10 +1,11 @@
-import { buildCoreRecord } from '../core/builder.js';
+import { ANY_EDITOR_STATE, buildCoreRecord } from '../core/builder.js';
 import { P } from './properties.js';
 const F = 'session';
 const D = 'editor';
 export const SESSION_RECORDS = [
     buildCoreRecord({
         parentTool: 'control_editor', action: 'play', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         topics: ['play in editor', 'pie', 'start pie', 'start game', 'run game', 'press play', 'simulate'],
         aliases: ['control_editor.start_pie'],
         summary: 'Start Play-In-Editor (PIE) session; answers once the play world has begun play.',
@@ -18,6 +19,7 @@ export const SESSION_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'stop', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         topics: ['stop pie', 'stop game', 'end play', 'exit pie'],
         summary: 'Stop the running PIE session.',
         whenToUse: ['The PIE session must be terminated.'],
@@ -30,6 +32,7 @@ export const SESSION_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'stop_pie', dispatchAction: 'stop',
+        editorStates: ANY_EDITOR_STATE,
         domain: D, family: F,
         summary: 'Stop the running PIE session (alias for stop).',
         whenToUse: ['The PIE session must be terminated using the stop_pie alias.'],
@@ -42,6 +45,7 @@ export const SESSION_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'pause', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Pause the running PIE session.',
         whenToUse: ['PIE must be paused without stopping.'],
         whenNotToUse: ['PIE is not running or already paused.'],
@@ -52,6 +56,7 @@ export const SESSION_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'resume', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Resume a paused PIE session.',
         whenToUse: ['A paused PIE session must resume.'],
         whenNotToUse: ['PIE is not paused.'],
@@ -62,6 +67,7 @@ export const SESSION_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'eject', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Eject the player from its pawn in PIE, as the editor\'s Eject button does: the session switches to Simulate in Editor and the view becomes a free camera that set_camera moves and screenshot photographs. Answers once the view has switched.',
         whenToUse: ['The player must detach from the possessed pawn.', 'The view of a running game must be placed for a screenshot: eject, then set_camera.'],
         whenNotToUse: ['PIE is not running (NO_ACTIVE_SESSION).', 'The game must keep playing from the pawn: an ejected player no longer drives it.'],
@@ -80,6 +86,7 @@ export const SESSION_RECORDS = [
     }),
     buildCoreRecord({
         parentTool: 'control_editor', action: 'possess', domain: D, family: F,
+        editorStates: ANY_EDITOR_STATE,
         summary: 'Possess a pawn in PIE: the player controller takes the pawn named by actorName. Without actorName it brings an ejected player back to its own pawn, as the editor\'s Possess button does (the way back from eject). Answers once the player is back in the game.',
         whenToUse: ['The player must take control of a specific pawn.', 'An ejected player must return to the game (no actorName).'],
         whenNotToUse: ['PIE is not running (NOT_IN_PIE).', 'The actor is not a pawn (INVALID_TARGET).'],