Python is not only a tool-making language, but also a learning tool.
In simple terms, introspection is the ability to determine the type of an object at runtime.（ In the context of Unreal Engine and TAPython, runtime refers to the editor's runtime, not the gameplay.）That allowing us to quickly understand and familiarize ourselves with the objects in Unreal Engine and their relationships.
Python is an object-oriented programming language where everything is an object. Each object may have attributes and methods (functions). With introspection, we can dynamically examine objects and their methods.
Introspection is an ability to determine the type of an object at runtime. Everything in python is an object. Every object in Python may have attributes and methods. By using introspection, we can dynamically examine python objects. Code Introspection is used for examining the classes, methods, objects, modules, keywords and get information about them so that we can utilize it. Introspection reveals useful information about your program’s objects. Python, being a dynamic, object-oriented programming language, provides tremendous introspection support. Python’s support for introspection runs deep and wide throughout the language.
Access Objects in Unreal Engine¶
The Access Objects in the Editor tutorial introduces how to access objects in the engine and assign them to the global variable _r. The object types accessible through the menu include:
The object types accessible through the menu include:
- UMaterialExpression and more
Besides accessing objects through preset menu items, we can also use Python commands to access them.
For example, to access selected Actors:
Find by Object Name¶
Note that objects have both a name (ID Name) and a label_name. ID Name is unique, while label_name is the displayed object name and can have duplicates.
In the Python window, using the Help command will display detailed information about the object.
For example, with
help(unreal.PythonBPLib.find_actor_by_name)， you can see the purpose, parameters, and return values of the
find_actor_by_name(...) method of builtins.type instance X.find_actor_by_name(name, world=None, include_dead=True) -> Actor Get actor by name(ID Name) in specified World Args: name (str): Name(ID Name) of actor world (World): World Context include_dead (bool): Include dead object or not Returns: Actor: A pointer to the named actor or NULL if not found.
In the method above, the second parameter is an optional World. The default value is the current editor's World.
UE uses different Worlds to separate object ownership. For example, models in the Static Mesh Editor and objects in the scene belong to different Worlds; objects placed in the editor and the same object during PILE gameplay are actually part of different Worlds.
To get the current editor's World in UE5:
Find by Label Name¶
unreal.PythonBPLib.find_actors_by_label_name, you can find all objects with the same Label Name in the current World.
cubes = unreal.PythonBPLib.find_actors_by_label_name("SM_Cube", unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world())
Accessing UAsset Resources¶
- Resources selected in the Content Browser
- Access resources by resource path
- Directories selected in the Content Browser
- Get all resources in a specified directory
- Get resources of a specified type
Accessing Component Components¶
- Access selected Components
- Access all Components of a specified type
After obtaining the desired objects, resources, etc., we can:
dir function can list the attributes, methods, etc., of Python objects. By slightly "modifying"
dir, it can be used to quickly search for attribute and method names in objects.
def d(obj, sub_string=''): sub_string = sub_string.lower() for x in dir(obj): if not sub_string or sub_string in x.lower(): print(x)
For example, use "d(_r, 'name')" to search for content related to "name".
One significant difference between UObject in UE and regular Python objects is that accessing and setting UObject properties requires using
set_editor_property. This ensures that functions like PostEditChangeProperty in the editor are triggered.
unreal.PythonBPLib.get_all_property_names provides the ability to get all "editor_property" names for a UObject Class.
_r above is an instance of a StaticMeshActor object, and
_r.static_class() gets its Class.
The inspect module provides several useful functions to help get information about live objects such as modules, classes, methods, functions, tracebacks, frame objects, and code objects. For example, it can help you examine the contents of a class, retrieve the source code of a method, extract and format the argument list for a function, or get all the information you need to display a detailed traceback.
Using Python's inspect module, we can obtain more detailed information about objects.
- inspect.ismodule(obj) - Determine if the object is a module
- inspect.getdoc(obj) - Get object documentation
- inspect.signature(func) - Get function signature
- inspect.isbuiltin(attr) - Determine if it is a builtin attribute
- inspect.getsourcefile(func) - Get the Python source file where the method is located and more
Connecting Them Together¶
Object Detail Viewer¶
When we can access an object's properties, methods, function signatures, etc., we can put them together into a tool. This is thU_003_ObjectDetailViewer
Unreal Python Stub¶
When we enable Developer Mode in Preferences > Plugins > Python and launch the UE editor, a stub file named
unreal.py is generated in the
<Your_UE_Project>/Intermediate/PythonStub directory. It contains all the Python-available objects and APIs in the current editor. We can use it to implement code completion in PyCharm and VsCode and perform simple data analysis to understand which Python objects are most commonly used and which editor libraries need to be studied and familiarized.
Copy the unreal.py file from the Intermediate/PythonStub directory in the project to the TA/TAPython/Python directory.
Using matplotlib and networkx to categorize and visualize UE objects¶
Splitting unreal.py for a better development experience