UnrealEnginePython中的UObject API详解

UnrealEnginePython中的UObject API详解

UnrealEnginePython 项目地址: https://gitcode.com/gh_mirrors/un/UnrealEnginePython

概述

在UnrealEnginePython项目中，UObject API是与虚幻引擎对象系统交互的核心接口。这个API为Python开发者提供了一套简洁而强大的工具集，用于操作虚幻引擎中的各种对象(UObject)。本文将深入解析这个API的功能和使用方法，帮助开发者更好地在Python中操作虚幻引擎对象。

基本对象操作

获取和设置属性

value = uobject.get_property('name')  # 获取属性值
uobject.set_property('name', value)   # 设置属性值
properties_list = uobject.properties()  # 获取所有属性列表

这些方法允许你直接访问和修改UObject的属性。需要注意的是，当前版本不支持结构体类型的属性操作。

对象标识信息

name = uobject.get_name()          # 获取对象名称
full_name = uobject.get_full_name()  # 获取完整名称(包含路径)

这些方法可以帮助你识别和区分不同的UObject实例。

对象查找与遍历

对象查找方法

found_uobject = uobject.find_object('name')  # 按名称查找对象(性能较低)
found_uobjects = uobject.all_objects()       # 获取所有对象(性能极低)
found_actors = uobject.all_actors()          # 获取所有Actor(性能中等)

重要提示：这些查找方法性能开销较大，应谨慎使用，特别是在游戏运行时。

Actor操作

基本变换控制

# 位置操作
location = uobject.get_actor_location()
uobject.set_actor_location(vector)  # 或 set_actor_location(x, y, z)

# 旋转操作
rotation = uobject.get_actor_rotation()
uobject.set_actor_rotation(rotation)  # 或 set_actor_rotation(pitch, yaw, roll)

# 方向向量
forward = uobject.get_actor_forward()
right = uobject.get_actor_right()
up = uobject.get_actor_up()

# 速度
velocity = uobject.get_actor_velocity()

这些方法会自动处理组件与Actor之间的关系，简化了常见的变换操作。

Actor生命周期管理

# 生成与销毁
uclass = uobject.get_class()
new_actor = uobject.actor_spawn(uclass[, location, rotation])
uobject.actor_destroy()

# 边界信息
location, extents = uobject.get_actor_bounds()

组件管理

组件操作

# 组件查询
has_component = uobject.actor_has_component_of_type(uclass)
component = uobject.get_actor_component_by_type(uclass)  # 或 get_component_by_type(uclass)
components = uobject.get_actor_components()

# 组件添加
new_component = uobject.add_actor_component(uclass, 'name')
new_component = uobject.add_actor_root_component(uclass, 'name')

这些方法为管理Actor上的组件提供了便利的接口。

反射系统调用

方法调用

# 简单调用
uobject.call('function arg0 arg1 argN....')

# 带返回值的调用
ret = uobject.call_function('function', arg0, arg1, argN....')

反射调用是UObject API最强大的功能之一，它允许你调用任何暴露给反射系统的方法，包括蓝图函数。

示例：

text_render_component.call('SetText Hello')

输入系统

输入控制

uobject.enable_input()                  # 启用输入
uobject.bind_input_axis('axis')         # 绑定输入轴
is_down = uobject.is_input_key_down('key')  # 检查按键状态
axis_value = uobject.get_input_axis('axis')  # 获取输入轴值

物理与碰撞

物理操作

uobject.set_simulate_physics()  # 启用物理模拟

# 射线检测
hit = uobject.line_trace_single_by_channel(start, end, channel)
hits = uobject.line_trace_multi_by_channel(start, end, channel)

特殊功能

导航系统

uobject.simple_move_to_location(vector)  # 或 simple_move_to_location(x, y, z)

使用导航网格系统移动Actor。

鼠标控制

uobject.show_mouse_cursor()      # 显示鼠标光标
uobject.enable_click_events()    # 启用点击事件
uobject.enable_mouse_over_events()  # 启用鼠标悬停事件
hit = uobject.get_hit_result_under_cursor(channel)  # 获取光标下的命中结果

可破坏物体

uobject.destructible_apply_damage(damage, impulse, direction, impulse)

视图控制

uobject.set_view_target(target)  # 设置视图目标(需要带相机组件的Actor)

样条组件

length = uobject.get_spline_length()  # 获取样条长度
point = uobject.get_world_location_at_distance_along_spline(distance)  # 获取样条上的点

性能考虑

在使用UObject API时，需要注意以下几点性能考量：

1. 反射调用(call和call_function)比直接调用C++方法慢，但提供了最大的灵活性
2. 对象查找方法(find_object, all_objects)性能开销很大，应避免在游戏循环中使用
3. 对于频繁调用的操作，尽量使用专用的API方法而非反射调用

结语

UnrealEnginePython的UObject API为Python开发者提供了与虚幻引擎对象系统交互的强大工具集。通过合理使用这些API，你可以在保持良好性能的同时，实现复杂的游戏逻辑和交互功能。记住，当专用API方法不存在时，反射调用是你的备用选择。

UnrealEnginePython 项目地址: https://gitcode.com/gh_mirrors/un/UnrealEnginePython