## actor.spawn v2.0 （全能生成） - **Method**：`actor.spawn` - **Params**： - `instances`: 数组，支持单体/批量统一入口。每个元素： - `asset_id`: 推荐字段，智能解析三级回落： 1) 别名（内置）：`cube` `sphere` `cylinder` `cone` `plane` `point_light` `spot_light` `directional_light` `rect_light` `camera` 2) 资源路径：如 `/Game/Environment/Props/SM_Table_01.SM_Table_01`（静态网格自动生成 `AStaticMeshActor` 并绑定 Mesh）；或蓝图类路径 `/Game/BP_Enemy.BP_Enemy_C`（直接 Spawn 类） 3) 类名：如 `BP_Enemy_C` 或 `/Script/Engine.PointLight` - 兼容字段：`preset`（旧别名）、`class`（旧类路径） - `name`：可选，强制命名 - `mesh`：可选，覆盖静态网格路径（优先级高于解析出的 Mesh） - `transform`：可选对象，或顶层字段 `location/rotation/scale`（向后兼容） - `location` `{x,y,z}`，`rotation` `{pitch,yaw,roll}`，`scale` `{x,y,z}` - 兼容：旧字段 `batch` 会被转为 `instances` - **Response**： - `count`: 成功创建数量 - `created`: 数组，对应输入顺序，失败位置为 `null` - `name`，`path`，`class` - `asset_id`（若输入使用 asset_id） - `type`（解析出的类型名） - `preset`（若走了别名） - **示例**： ```json { "ver": "2.0", "method": "actor.spawn", "params": { "instances": [ { "asset_id": "point_light", "transform": { "location": { "z": 500 } } }, { "asset_id": "/Game/Environment/Props/SM_Table_01.SM_Table_01", "transform": { "location": { "x": 200 } } }, { "asset_id": "/Game/Blueprints/Characters/BP_NPC_Guard.BP_NPC_Guard_C", "name": "Guard_01", "transform": { "location": { "x": -200 }, "rotation": { "yaw": 90 } } } ] } } ``` ```json { "code": 200, "result": { "count": 3, "created": [ { "name": "PointLight_4", "type": "PointLight" }, { "name": "SM_Table_01_2", "type": "StaticMeshActor" }, { "name": "Guard_01", "type": "BP_NPC_Guard_C" } ] } } ``` ## actor.get_info v2.0 （场景感知 / 统一 Selector） - **Method**：`actor.get_info` - **Params**： - `targets`: 对象（复用 `actor.set_transform` / `actor.destroy` 选择器） - `names`: 可选，字符串数组，按 Label 精准查找 - `paths`: 可选，字符串数组，按对象路径查找 - `filter`: 可选，场景扫描筛选 - `class`: 类名包含匹配（模糊，忽略大小写） - `name_pattern`: 名称通配匹配（Wildcard） - `exclude_classes`: 数组，排除类名（全等匹配，忽略大小写） - `return_transform`: `true`/`false`，默认 `true`。返回 `transform`（location/rotation/scale），若只想看列表可置 `false` 节省 Token。 - `return_bounds`: `true`/`false`，默认 `false`。返回组件包围盒尺寸 `bounds {x,y,z}`（堆叠/避障需要尺寸时再开）。 - `limit`: 整数，默认 `50`，限制返回数量保护上下文。 - **Response**： - `count`: 实际返回的数量（受 limit 截断） - `total_found`: 真实匹配总数（可提示还有更多） - `actors`: 数组 - 基础：`name`, `class`, `path` - 可选：`transform`（`location/rotation/scale`，需 `return_transform=true`）、`bounds`（需 `return_bounds=true`） - **示例 1：精准查询（椅子还在吗？在哪？）** ```json { "ver": "2.0", "method": "actor.get_info", "params": { "targets": { "names": ["Chair_01"] }, "return_transform": true } } ``` - **示例 2：环境扫描（看看有哪些灯，最多 5 个）** ```json { "ver": "2.0", "method": "actor.get_info", "params": { "targets": { "filter": { "class": "Light" } }, "limit": 5, "return_transform": true } } ``` - **示例响应** ```json { "code": 200, "result": { "count": 2, "total_found": 15, "actors": [ { "name": "PointLight_1", "class": "PointLight", "path": "/Game/Maps/Level1.PointLight_1", "transform": { "location": { "x": 100, "y": 200, "z": 300 }, "rotation": { "pitch": 0, "yaw": 0, "roll": 0 }, "scale": { "x": 1, "y": 1, "z": 1 } } }, { "name": "SpotLight_Hallway", "class": "SpotLight", "path": "/Game/Maps/Level1.SpotLight_Hallway", "transform": { "location": { "x": 500, "y": 200, "z": 300 }, "rotation": { "pitch": 0, "yaw": 0, "roll": 0 }, "scale": { "x": 1, "y": 1, "z": 1 } } } ] } } ``` --- ## actor.inspect v2.0 （按需内省 / 防止 Token 爆炸） - **Method**：`actor.inspect` - **Params**： - `targets`: 对象（统一 Selector，推荐单体，也可批量） - `names/paths/filter` 同 `actor.get_info` - `properties`: 字符串数组；为空/缺省时使用默认白名单 - 默认白名单：`Mobility`, `bHidden`, `CollisionProfileName`, `Tags` - **Response**： - `count`: 返回的 actor 数量 - `actors`: 数组 - `name`, `class`, `path` - `props`: 仅包含请求的属性键值 - **示例 1：默认查询（常用核心属性）** ```json { "ver": "2.0", "method": "actor.inspect", "params": { "targets": { "names": ["MyCube"] } } } ``` - **示例 2：定向查询（只看灯光关键参数）** ```json { "ver": "2.0", "method": "actor.inspect", "params": { "targets": { "names": ["PointLight_1"] }, "properties": ["Intensity", "LightColor", "AttenuationRadius"] } } ``` - **示例响应** ```json { "code": 200, "result": { "count": 1, "actors": [ { "name": "PointLight_1", "class": "PointLight", "path": "/Game/Maps/Level1.PointLight_1", "props": { "Intensity": 5000.0, "LightColor": { "r": 255, "g": 255, "b": 255, "a": 255 }, "AttenuationRadius": 1000.0 } } ] } } ``` --- ## actor.set_property v1.0（通用属性修改 / 带智能提示） - **Method**：`actor.set_property` - **Params**： - `targets`: 统一 Selector（names/paths/filter） - `properties`: 对象，键为属性名，值为目标值。示例：`{"Intensity": 10000.0, "LightColor": {"r": 255, "g": 0, "b": 0}}` - **行为与防呆**： - 自动 Actor → RootComponent → 其他组件 递归查找属性（避免点光源/网格属性找不到） - **特殊属性拦截白名单**（调用专用函数，而非简单反射修改）： - `ActorLabel` / `Label`：调用 `SetActorLabel()`，自动处理名称冲突（若重名则自动加后缀） - `FolderPath`：调用 `SetFolderPath()`，正确刷新世界大纲文件夹归类 - `SimulatePhysics` / `bSimulatePhysics`：调用 `SetSimulatePhysics()`，触发物理状态重建 - `Mobility`：调用 `SetMobility()`，正确处理光照/导航网格失效。值可为 `"Static"` / `"Stationary"` / `"Movable"` - `Hidden` / `bHidden` / `HiddenInGame`：调用 `SetActorHiddenInGame()`，**运行时隐藏**（编辑器视图中仍可见） - `HiddenInEditor` / `bHiddenInEditor` / `bHiddenEd`：调用 `SetIsTemporarilyHiddenInEditor()`，**编辑器隐藏**（在编辑器视图中立即隐藏/显示） - `Tags`：Actor 标签数组，支持三种模式： - 数组覆盖：`["tag1", "tag2"]` 替换所有标签 - 单字符串：`"tag1"` 添加单个标签（不覆盖） - 增删对象：`{ "add": ["tag1"], "remove": ["tag2"] }` 精确控制增删 - 属性不存在：不会直接 404，会返回 `suggestions`（按编辑距离排序），提示可能的正确属性名 - 类型不匹配：返回 `expected_type` 及 `current_value`，帮助 AI 校正格式/类型 - 支持类型：数字（整型/浮点）、bool、string/name/text、FVector、FRotator、FLinearColor、FColor；其它结构会提示不支持 - **Response**： - `count`: 成功修改的 Actor 数量 - `actors`: 数组 - `name`, `class`, `path` - `updated`: 成功写入的键值 - `errors`: 可选数组，包含 `{ property, error, suggestions?, expected_type?, current_value? }`；对于 ActorLabel 名称冲突场景，会返回 `{ property, warning, requested, actual }` - **示例** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["PointLight_1"] }, "properties": { "Intensity": 10000.0, "LightColor": { "r": 255, "g": 0, "b": 0 } } } } ``` ```json { "code": 200, "result": { "count": 1, "actors": [ { "name": "PointLight_1", "class": "PointLight", "updated": { "Intensity": 10000.0, "LightColor": { "r": 255, "g": 0, "b": 0, "a": 1 } } } ] } } ``` - **示例 2：重命名 Actor（修改 ActorLabel）** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["Floor"] }, "properties": { "ActorLabel": "MainFloor" } } } ``` ```json { "code": 200, "result": { "count": 1, "actors": [ { "name": "MainFloor", "class": "StaticMeshActor", "updated": { "ActorLabel": "MainFloor" } } ] } } ``` - **示例 3：归类到大纲文件夹（FolderPath）** ```json { "method": "actor.set_property", "params": { "targets": { "filter": { "class": "SpotLight" } }, "properties": { "FolderPath": "Lighting/SpotLights" } } } ``` - **示例 4：开启物理模拟（SimulatePhysics）** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["Cup_01"] }, "properties": { "SimulatePhysics": true, "Mobility": "Movable" } } } ``` - **示例 5：隐藏 Actor - 运行时隐藏（bHidden）** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["DebugHelper"] }, "properties": { "bHidden": true } } } ``` - **示例 6：隐藏 Actor - 编辑器隐藏（HiddenInEditor）** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["ConstructionGuide"] }, "properties": { "HiddenInEditor": true } } } ``` - **示例 7：添加标签 - 单个标签** ```json { "method": "actor.set_property", "params": { "targets": { "filter": { "name_pattern": "test_*" } }, "properties": { "Tags": "test" } } } ``` - **示例 8：设置标签 - 覆盖所有标签** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["Player_Start"] }, "properties": { "Tags": ["PlayerSpawn", "Important", "DoNotDelete"] } } } ``` - **示例 9：增删标签 - 精确控制** ```json { "method": "actor.set_property", "params": { "targets": { "names": ["OldActor"] }, "properties": { "Tags": { "add": ["NewTag"], "remove": ["DeprecatedTag"] } } } } ``` --- ## actor.destroy v2.0 （统一 Selector） - **Method**：`actor.destroy` - **Params**： - `targets`: 对象（与 `actor.set_transform` 选择器一致） - `names`: 可选，字符串数组，按 Label 匹配 - `paths`: 可选，字符串数组，按对象路径匹配 - `filter`: 可选，对场景扫描筛选 - `class`: 类名包含匹配（模糊，忽略大小写） - `name_pattern`: 名称通配匹配（Wildcard） - `exclude_classes`: 数组，排除类名（全等匹配，忽略大小写） - 兼容：旧字段 `name/path` 会被自动转换；`actor.destroy_batch` 的 `batch` 会被转换为 `targets.names/paths` - **Response**： - `count`: 成功删除的数量 - `target_count`: 被选中的数量 - `deleted_actors`: 数组，包含已删除的 `name/path/class` - **示例**： ```json { "method": "actor.destroy", "params": { "targets": { "names": ["Cube_1", "Sphere_Test_3"] } } } ``` ```json { "code": 200, "result": { "count": 2, "deleted_actors": ["Cube_1", "Sphere_Test_3"] } } ``` ```json { "method": "actor.destroy", "params": { "targets": { "filter": { "class": "DecalActor", "name_pattern": "*_Debug_*" } } } } ``` ## actor.set_transform （统一变换接口） - 结 构：`targets`（选择器） + `operation`（操作） - `targets` 字段： - `names`: 字符串数组，指定 Actor 名称。 - `paths`: 字符串数组，指定 Actor 路径。 - `filter`: 筛选器对象，支持 `class` (包含匹配), `name_pattern` (通配符), `exclude_classes` (排除类名数组)。 - `operation` 字段： - `space`: `"World"` (默认) 或 `"Local"`。 - `snap_to_floor`: `true` (执行贴地)。 - `set`: 绝对值设置 (`location`, `rotation`, `scale`)。 - `add`: 增量设置 (`location`, `rotation`, `scale`)，支持负数。 - `multiply`: 倍乘设置 (`location`, `rotation`, `scale`)。 - 计算顺序：先应用 `set`，再 `add`，最后 `multiply`；若 `space = "Local"`，增量位移会按本次最终旋转（累积后的 `rotation`）进行方向变换。 - 示例 1：单体绝对设置（Z=200） ```json { "ver":"1.0","type":"req","id":"t1","method":"actor.set_transform", "params":{ "targets": {"names": ["MyCube"]}, "operation": { "set": {"location": {"z": 200}} } } } ``` - 示例 2：批量增量（所有灯光 Z 轴上移 500，局部坐标系） ```json { "ver":"1.0","type":"req","id":"t2","method":"actor.set_transform", "params":{ "targets": { "filter": {"class": "Light"} }, "operation": { "space": "Local", "add": {"location": {"z": 500}} } } } ``` - 示例 3：多选倍乘（Cube_1 和 Sphere_2 放大 2 倍） ```json { "ver":"1.0","type":"req","id":"t3","method":"actor.set_transform", "params":{ "targets": { "names": ["Cube_1", "Sphere_2"] }, "operation": { "multiply": {"scale": {"x": 2, "y": 2, "z": 2}} } } } ``` - 响应（code 200）： ```json {"ver":"1.0","type":"res","id":"t1","code":200,"result":{"count":1,"actors":[{"name":"MyCube",...}]}} ```