test-ue-project/Actor接口文档.md at main

yjj/test-ue-project

Fork 0

Files

yjj dd642c8585 ceshi

2026-02-26 23:45:31 +08:00

14 KiB

Raw Permalink Blame History

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（若走了别名）
示例：

{
  "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 } } }
    ]
  }
}

{
  "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：精准查询（椅子还在吗？在哪？）

{
  "ver": "2.0",
  "method": "actor.get_info",
  "params": {
    "targets": {
      "names": ["Chair_01"]
    },
    "return_transform": true
  }
}

示例 2：环境扫描（看看有哪些灯，最多 5 个）

{
  "ver": "2.0",
  "method": "actor.get_info",
  "params": {
    "targets": {
      "filter": {
        "class": "Light"
      }
    },
    "limit": 5,
    "return_transform": true
  }
}

示例响应

{
  "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：默认查询（常用核心属性）

{
  "ver": "2.0",
  "method": "actor.inspect",
  "params": {
    "targets": { "names": ["MyCube"] }
  }
}

示例 2：定向查询（只看灯光关键参数）

{
  "ver": "2.0",
  "method": "actor.inspect",
  "params": {
    "targets": { "names": ["PointLight_1"] },
    "properties": ["Intensity", "LightColor", "AttenuationRadius"]
  }
}

示例响应

{
  "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 }
示例

{
  "method": "actor.set_property",
  "params": {
    "targets": { "names": ["PointLight_1"] },
    "properties": {
      "Intensity": 10000.0,
      "LightColor": { "r": 255, "g": 0, "b": 0 }
    }
  }
}

{
  "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）

{
  "method": "actor.set_property",
  "params": {
    "targets": { "names": ["Floor"] },
    "properties": {
      "ActorLabel": "MainFloor"
    }
  }
}

{
  "code": 200,
  "result": {
    "count": 1,
    "actors": [
      {
        "name": "MainFloor",
        "class": "StaticMeshActor",
        "updated": {
          "ActorLabel": "MainFloor"
        }
      }
    ]
  }
}

示例 3：归类到大纲文件夹（FolderPath）

{
  "method": "actor.set_property",
  "params": {
    "targets": { "filter": { "class": "SpotLight" } },
    "properties": {
      "FolderPath": "Lighting/SpotLights"
    }
  }
}

示例 4：开启物理模拟（SimulatePhysics）

{
  "method": "actor.set_property",
  "params": {
    "targets": { "names": ["Cup_01"] },
    "properties": {
      "SimulatePhysics": true,
      "Mobility": "Movable"
    }
  }
}

示例 5：隐藏 Actor - 运行时隐藏（bHidden）

{
  "method": "actor.set_property",
  "params": {
    "targets": { "names": ["DebugHelper"] },
    "properties": {
      "bHidden": true
    }
  }
}

示例 6：隐藏 Actor - 编辑器隐藏（HiddenInEditor）

{
  "method": "actor.set_property",
  "params": {
    "targets": { "names": ["ConstructionGuide"] },
    "properties": {
      "HiddenInEditor": true
    }
  }
}

示例 7：添加标签 - 单个标签

{
  "method": "actor.set_property",
  "params": {
    "targets": { "filter": { "name_pattern": "test_*" } },
    "properties": {
      "Tags": "test"
    }
  }
}

示例 8：设置标签 - 覆盖所有标签

{
  "method": "actor.set_property",
  "params": {
    "targets": { "names": ["Player_Start"] },
    "properties": {
      "Tags": ["PlayerSpawn", "Important", "DoNotDelete"]
    }
  }
}

示例 9：增删标签 - 精确控制

{
  "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
示例：

{
  "method": "actor.destroy",
  "params": {
    "targets": {
      "names": ["Cube_1", "Sphere_Test_3"]
    }
  }
}

{
  "code": 200,
  "result": {
    "count": 2,
    "deleted_actors": ["Cube_1", "Sphere_Test_3"]
  }
}

{
  "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）

{
  "ver":"1.0","type":"req","id":"t1","method":"actor.set_transform",
  "params":{
    "targets": {"names": ["MyCube"]},
    "operation": {
      "set": {"location": {"z": 200}}
    }
  }
}

示例 2：批量增量（所有灯光 Z 轴上移 500，局部坐标系）

{
  "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 倍）

{
  "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）：

{"ver":"1.0","type":"res","id":"t1","code":200,"result":{"count":1,"actors":[{"name":"MyCube",...}]}}

14 KiB Raw Permalink Blame History Unescape Escape

actor.spawn v2.0 （全能生成）

actor.get_info v2.0 （场景感知 / 统一 Selector）

actor.inspect v2.0 （按需内省 / 防止 Token 爆炸）

actor.set_property v1.0（通用属性修改 / 带智能提示）

actor.destroy v2.0 （统一 Selector）

actor.set_transform （统一变换接口）

14 KiB

Raw Permalink Blame History