Learning Unreal Engine with Python

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:

• UActor
• UAsset
• UComponent
• UMaterialExpression and more

Besides accessing objects through preset menu items, we can also use Python commands to access them.

Accessing Actors¶

For example, to access selected Actors:

unreal.get_editor_subsystem(unreal.EditorActorSubsystem).get_selected_level_actors()

Find by Object Name¶

unreal.PythonBPLib.find_actor_by_name("StaticMeshActor_8")

CAUTION
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.

Help Command¶

In the Python window, using the Help command will display detailed information about the object.

For example, withhelp(unreal.PythonBPLib.find_actor_by_name)， you can see the purpose, parameters, and return values of the unreal.PythonBPLib.find_actor_by_name method.

help(unreal.PythonBPLib.find_actor_by_name)

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.

NOTE
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:

unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()

For UE4:

unreal.EditorLevelLibrary.get_editor_world()

Find by Label Name¶

With 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

Introspection¶

After obtaining the desired objects, resources, etc., we can:

dir¶

The 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".

type¶

Editor Property¶

One significant difference between UObject in UE and regular Python objects is that accessing and setting UObject properties requires using get_editor_property and set_editor_property. This ensures that functions like PostEditChangeProperty in the editor are triggered.

Access Methods¶

unreal.PythonBPLib.get_all_property_names provides the ability to get all "editor_property" names for a UObject Class.

unreal.PythonBPLib.get_all_property_names(_r.static_class())

Note
The _r above is an instance of a StaticMeshActor object, and _r.static_class() gets its Class.

Advanced¶

inspect¶

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.

For example:

• 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¶

Relative Links¶

Splitting unreal.py for a better development experience

Setting up Autocomplete for Editor Python Scripting