Python Examples

For full control of the Simplygon processing of a set of actors in an Unreal scene, you can export the scene from Unreal into a Simplygon scene, and then have access to the full suite of tools in Simplygon for processing. The processed scene can later be imported into Unreal, either as a replacement of the original, or as e.g. a combined static mesh which can be hooked up as a stand in runtime replacement, or as hierarchical LOD replacement. In this section, we present a few short examples of how to export a scene from Unreal to Simplygon, or import a scene into Unreal from Simplygon.

The examples are located in: Content → Python → simplygon_subsystem_examples.py

Note

The Simplygon Subsystem is an Editor Subsystem. This means it is only available for Editor Utility Blueprints or Editor Utility Widgets.

Synchronous Export Example

Export example for exporting selected Actors, Static Mesh Components, or Static Meshes into a Simplygon .sgscene file, and waiting for the call to finish before continuing.

Actors

UE 5.5

# Export example for exporting selected Actors.
def export_actors_example():
    """Export Actors Example"""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # Get actors to export.
    EAS = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
    selected_actors = EAS.get_selected_level_actors()

    # The target file path of where the exported Simplygon scene will be saved.
    export_file_path = (
        unreal.Paths.project_intermediate_dir()
        + "/Simplygon/"
        + "PythonExportExample.sgscene"
    )

    # Call export function.
    export_task_id = simplygon_subsystem.export_actors_to_scene(
        export_file_path, selected_actors, get_default_scene_export_settings(True)
    )

    # Fetch the result (which will wait for the result).
    export_result = simplygon_subsystem.retrieve_export_scene_result(
        export_task_id
    )

    # Log result.
    if unreal.SubsystemTaskResult.cast(export_result).has_error:
        unreal.log_error(f"Export error: {unreal.SubsystemTaskResult.cast(export_result).error_message}")
    else:
        unreal.log(
            f"Export result: Scene written to file {export_result.output_file_path}"
        )

    return export_result

UE 5.6

# Export example for exporting selected Actors.
def export_actors_example():
    """Export Actors Example"""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # Get actors to export.
    EAS = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
    selected_actors = EAS.get_selected_level_actors()

    # The target file path of where the exported Simplygon scene will be saved.
    export_file_path = (
        unreal.Paths.project_intermediate_dir()
        + "/Simplygon/"
        + "PythonExportExample.sgscene"
    )

    # Call export function.
    export_task_id = simplygon_subsystem.export_actors_to_scene(
        export_file_path, selected_actors, get_default_scene_export_settings(True)
    )

    # Fetch the result (which will wait for the result).
    export_result = simplygon_subsystem.retrieve_export_scene_result(
        export_task_id
    )

    # Log result.
    if unreal.SubsystemTaskResult.cast(export_result).has_error:
        unreal.log_error(f"Export error: {unreal.SubsystemTaskResult.cast(export_result).error_message}")
    else:
        unreal.log(
            f"Export result: Scene written to file {export_result.output_file_path}"
        )

    return export_result

Static Mesh Components

UE 5.5

# Export example for exporting Static Mesh Components.
def export_components_example(add_components):
    """Export Components Example"""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # The target file path of where the exported Simplygon scene will be saved.
    export_file_path = (
        unreal.Paths.project_intermediate_dir()
        + "/Simplygon/"
        + "PythonExportExampleComponent.sgscene"
    )

    static_mesh_components = []
    if add_components:
        static_mesh_components = setup_components()

    if len(static_mesh_components) == 0:
        unreal.log_error("No static mesh components to export.")

    # Call export function.
    export_task_id = simplygon_subsystem.export_static_mesh_components_to_scene(
        export_file_path, static_mesh_components, get_default_scene_export_settings(
            True)
    )

    # Fetch the result (which will wait for the result).
    export_result = simplygon_subsystem.retrieve_export_scene_result(
        export_task_id
    )

    # Log result.
    if export_result.has_error:
        unreal.log_error(f"Export error: {export_result.error_message}")
    else:
        unreal.log(
            f"Export result: Scene written to file {export_result.output_file_path}"
        )

    return export_result

UE 5.6

# Export example for exporting Static Mesh Components.
def export_components_example(add_components):
    """Export Components Example"""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # The target file path of where the exported Simplygon scene will be saved.
    export_file_path = (
        unreal.Paths.project_intermediate_dir()
        + "/Simplygon/"
        + "PythonExportExampleComponent.sgscene"
    )

    static_mesh_components = []
    if add_components:
        static_mesh_components = setup_components()

    if len(static_mesh_components) == 0:
        unreal.log_error("No static mesh components to export.")

    # Call export function.
    export_task_id = simplygon_subsystem.export_static_mesh_components_to_scene(
        export_file_path, static_mesh_components, get_default_scene_export_settings(
            True)
    )

    # Fetch the result (which will wait for the result).
    export_result = simplygon_subsystem.retrieve_export_scene_result(
        export_task_id
    )

    # Log result.
    if export_result.has_error:
        unreal.log_error(f"Export error: {export_result.error_message}")
    else:
        unreal.log(
            f"Export result: Scene written to file {export_result.output_file_path}"
        )

    return export_result

Static Mesh

UE 5.5

# Export example for exporting a Static Mesh.
def export_mesh_example(setup_mesh, mesh_path):
    """Export Mesh Example"""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # The target file path of where the exported Simplygon scene will be saved.
    export_file_path = (
        unreal.Paths.project_intermediate_dir()
        + "/Simplygon/"
        + "PythonExportExampleMesh.sgscene"
    )

    mesh_to_export = None
    if setup_mesh:
        mesh_to_export = get_static_mesh_from_path(
            mesh_path)

    # Call export function.
    export_task_id = simplygon_subsystem.export_static_mesh_to_scene(
        export_file_path, mesh_to_export, get_default_mesh_export_settings(True)
    )

    # Fetch the result (which will wait for the result).
    export_result = simplygon_subsystem.retrieve_export_scene_result(
        export_task_id
    )

    # Log result.
    if export_result.has_error:
        unreal.log_error(f"Export error: {export_result.error_message}")
    else:
        unreal.log(
            f"Export result: Scene written to file {export_result.output_file_path}"
        )

    return export_result

UE 5.6

# Export example for exporting a Static Mesh.
def export_mesh_example(setup_mesh, mesh_path):
    """Export Mesh Example"""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # The target file path of where the exported Simplygon scene will be saved.
    export_file_path = (
        unreal.Paths.project_intermediate_dir()
        + "/Simplygon/"
        + "PythonExportExampleMesh.sgscene"
    )

    mesh_to_export = None
    if setup_mesh:
        mesh_to_export = get_static_mesh_from_path(
            mesh_path)

    # Call export function.
    export_task_id = simplygon_subsystem.export_static_mesh_to_scene(
        export_file_path, mesh_to_export, get_default_mesh_export_settings(True)
    )

    # Fetch the result (which will wait for the result).
    export_result = simplygon_subsystem.retrieve_export_scene_result(
        export_task_id
    )

    # Log result.
    if export_result.has_error:
        unreal.log_error(f"Export error: {export_result.error_message}")
    else:
        unreal.log(
            f"Export result: Scene written to file {export_result.output_file_path}"
        )

    return export_result

Asynchronous Export Example

Export example for exporting selected Actors into a Simplygon .sgscene file using a callback to report when the export process has finished. Note that the code still waits for the processing to finish using the simplygon_subsystem.wait_for_all_tasks_to_complete(), but this is not needed, if you have other assets to export or other processings or tasks to run.

Actors

UE 5.5

# Export example for exporting selected Actors using a callback.
def export_actors_example_using_callback():
    """Example for exporting actors from a level and get the result via a callback."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)
    with ExportNotificationContext(simplygon_subsystem) as notification_context:
        # Get actors to export.
        EAS = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
        selected_actors = EAS.get_selected_level_actors()

        # The target file path of where the exported Simplygon scene will be saved.
        export_file_path = (
            unreal.Paths.project_intermediate_dir()
            + "/Simplygon/"
            + "PythonExportExampleCallback.sgscene"
        )

        # Call export function which will call the callback once it's finished.
        simplygon_subsystem.export_actors_to_scene(
            export_file_path, selected_actors, get_default_scene_export_settings(True)
        )

        # Optional wait for tasks to finish
        simplygon_subsystem.wait_for_all_tasks_to_complete()

UE 5.6

# Export example for exporting selected Actors using a callback.
def export_actors_example_using_callback():
    """Example for exporting actors from a level and get the result via a callback."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)
    with ExportNotificationContext(simplygon_subsystem) as notification_context:
        # Get actors to export.
        EAS = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
        selected_actors = EAS.get_selected_level_actors()

        # The target file path of where the exported Simplygon scene will be saved.
        export_file_path = (
            unreal.Paths.project_intermediate_dir()
            + "/Simplygon/"
            + "PythonExportExampleCallback.sgscene"
        )

        # Call export function which will call the callback once it's finished.
        simplygon_subsystem.export_actors_to_scene(
            export_file_path, selected_actors, get_default_scene_export_settings(True)
        )

        # Optional wait for tasks to finish
        simplygon_subsystem.wait_for_all_tasks_to_complete()

Static Mesh Components

UE 5.5

# Export example for exporting Static Mesh Components using a callback.
def export_components_example_using_callback(add_components):
    """Example for exporting static mesh components and get the result via a callback."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)
    static_mesh_components = []
    if add_components:
        static_mesh_components = setup_components()

    with ExportNotificationContext(simplygon_subsystem) as notification_context:
        # The target file path of where the exported Simplygon scene will be saved.
        export_file_path = (
            unreal.Paths.project_intermediate_dir()
            + "/Simplygon/"
            + "PythonExportExampleCallback.sgscene"
        )

        simplygon_subsystem.export_static_mesh_components_to_scene(
            export_file_path, static_mesh_components, get_default_scene_export_settings(True))

        # Optional wait for tasks to finish
        simplygon_subsystem.wait_for_all_tasks_to_complete()

UE 5.6

# Export example for exporting Static Mesh Components using a callback.
def export_components_example_using_callback(add_components):
    """Example for exporting static mesh components and get the result via a callback."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)
    static_mesh_components = []
    if add_components:
        static_mesh_components = setup_components()

    with ExportNotificationContext(simplygon_subsystem) as notification_context:
        # The target file path of where the exported Simplygon scene will be saved.
        export_file_path = (
            unreal.Paths.project_intermediate_dir()
            + "/Simplygon/"
            + "PythonExportExampleCallback.sgscene"
        )

        simplygon_subsystem.export_static_mesh_components_to_scene(
            export_file_path, static_mesh_components, get_default_scene_export_settings(True))

        # Optional wait for tasks to finish
        simplygon_subsystem.wait_for_all_tasks_to_complete()

Static Mesh

UE 5.5

# Export example for exporting Static Mesh using a callback.
def export_mesh_example_using_callback(setup_mesh, mesh_path):
    """Example for exporting a mesh and get the result via a callback."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)
    static_mesh_components = setup_components()
    mesh_to_export = None
    if setup_mesh:
        mesh_to_export = get_static_mesh_from_path(
            mesh_path)
    with ExportNotificationContext(simplygon_subsystem) as notification_context:
        # The target file path of where the exported Simplygon scene will be saved.
        export_file_path = (
            unreal.Paths.project_intermediate_dir()
            + "/Simplygon/"
            + "PythonExportExampleCallback.sgscene"
        )

        simplygon_subsystem.export_static_mesh_to_scene(
            export_file_path, mesh_to_export, get_default_mesh_export_settings(True))

        # Optional wait for tasks to finish
        simplygon_subsystem.wait_for_all_tasks_to_complete()

UE 5.6

# Export example for exporting Static Mesh using a callback.
def export_mesh_example_using_callback(setup_mesh, mesh_path):
    """Example for exporting a mesh and get the result via a callback."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)
    static_mesh_components = setup_components()
    mesh_to_export = None
    if setup_mesh:
        mesh_to_export = get_static_mesh_from_path(
            mesh_path)
    with ExportNotificationContext(simplygon_subsystem) as notification_context:
        # The target file path of where the exported Simplygon scene will be saved.
        export_file_path = (
            unreal.Paths.project_intermediate_dir()
            + "/Simplygon/"
            + "PythonExportExampleCallback.sgscene"
        )

        simplygon_subsystem.export_static_mesh_to_scene(
            export_file_path, mesh_to_export, get_default_mesh_export_settings(True))

        # Optional wait for tasks to finish
        simplygon_subsystem.wait_for_all_tasks_to_complete()

Synchronous Import Example

Import example for importing a Simplygon .sgscene file into Unreal, and waiting for the call to finish before continuing.

UE 5.5

# Import example spawning imported actors into the current editor world.
def import_example(import_scene_path, tex_coord_name=""):
    """Import example spawning imported actors into the current editor world."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # Get world to spawn imported actors into.
    editor_subsystem = unreal.get_editor_subsystem(
        unreal.UnrealEditorSubsystem)
    world = editor_subsystem.get_editor_world()

    # Set import settings to use.
    import_settings = unreal.SgSceneImportSettings()
    if len(tex_coord_name) > 0:
        import_settings.geometry_settings.tex_coord_names = [tex_coord_name]

    # Call import function
    import_task_id = simplygon_subsystem.import_scene_as_actors(
        import_scene_path, world, import_settings
    )

    # Fetch the result (which will wait for the result).
    import_result = simplygon_subsystem.retrieve_import_scene_as_actors_result(
        import_task_id
    )

    # Log result.
    if import_result.has_error:
        unreal.log_error(f"Import error: {import_result.error_message}")
    else:
        unreal.log(
            f"Import result: Num Actors imported {len(import_result.imported_actor_paths)}"
        )
        unreal.log(
            f"Import result: Num meshes imported: {len(import_result.imported_meshes)}"
        )
        unreal.log(
            f"Import result: Num materials imported: {len(import_result.imported_materials)}"
        )
        unreal.log(
            f"Import result: Num textures imported: {len(import_result.imported_textures)}"
        )

    return import_result

UE 5.6

# Import example spawning imported actors into the current editor world.
def import_example(import_scene_path, tex_coord_name=""):
    """Import example spawning imported actors into the current editor world."""
    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # Get world to spawn imported actors into.
    editor_subsystem = unreal.get_editor_subsystem(
        unreal.UnrealEditorSubsystem)
    world = editor_subsystem.get_editor_world()

    # Set import settings to use.
    import_settings = unreal.SgSceneImportSettings()
    if len(tex_coord_name) > 0:
        import_settings.geometry_settings.tex_coord_names = [tex_coord_name]

    # Call import function
    import_task_id = simplygon_subsystem.import_scene_as_actors(
        import_scene_path, world, import_settings
    )

    # Fetch the result (which will wait for the result).
    import_result = simplygon_subsystem.retrieve_import_scene_as_actors_result(
        import_task_id
    )

    # Log result.
    if import_result.has_error:
        unreal.log_error(f"Import error: {import_result.error_message}")
    else:
        unreal.log(
            f"Import result: Num Actors imported {len(import_result.imported_actor_paths)}"
        )
        unreal.log(
            f"Import result: Num meshes imported: {len(import_result.imported_meshes)}"
        )
        unreal.log(
            f"Import result: Num materials imported: {len(import_result.imported_materials)}"
        )
        unreal.log(
            f"Import result: Num textures imported: {len(import_result.imported_textures)}"
        )

    return import_result

Asynchronous Import Example

Import example which imports a Simplygon .sgscene file into Unreal, and uses a callback to report when the import process has finished. Note that the code still waits for the processing to finish using the simplygon_subsystem.wait_for_all_tasks_to_complete(), but this is not needed, if you have other assets to import or other processings or tasks to run.

UE 5.5

# Import example spawning imported actors into the current editor world using a callback.
def import_example_using_callback(import_scene_path, tex_coord_name):
    """Import example spawning imported actors into the current editor world using a callback."""
    # Create callback
    def on_import_completed(import_result):
        unreal.log(f"Simplygon import task using subsystem callback completed.")

        # Log result.
        if import_result.has_error:
            unreal.log_error(f"Import error: {import_result.error_message}")
        else:
            unreal.log(
                f"Import result: Num Actors imported {len(import_result.imported_actor_paths)}"
            )
            unreal.log(
                f"Import result: Num meshes imported: {len(import_result.imported_meshes)}"
            )
            unreal.log(
                f"Import result: Num materials imported: {len(import_result.imported_materials)}"
            )
            unreal.log(
                f"Import result: Num textures imported: {len(import_result.imported_textures)}"
            )

        # Remove callback from subsystem. Specific to these examples.
        # Not necessary to add & remove callbacks for each import/export.
        simplygon_subsystem = unreal.get_editor_subsystem(
            unreal.SimplygonSubsystem)
        simplygon_subsystem.on_import_scene_as_actors_completed.clear()

    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # Add callback to subsystem.
    simplygon_subsystem.on_import_scene_as_actors_completed.add_callable(
        on_import_completed
    )

    # Get world to spawn imported actors into.
    editor_subsystem = unreal.get_editor_subsystem(
        unreal.UnrealEditorSubsystem)
    world = editor_subsystem.get_editor_world()

    # Set import settings to use.
    import_settings = unreal.SgSceneImportSettings()
    import_settings.geometry_settings.tex_coord_names = [tex_coord_name]

    # Call import function which will call the callback once it's finished.
    simplygon_subsystem.import_scene_as_actors(
        import_scene_path, world, import_settings
    )

    # Optional wait for tasks to finish
    simplygon_subsystem.wait_for_all_tasks_to_complete()

UE 5.6

# Import example spawning imported actors into the current editor world using a callback.
def import_example_using_callback(import_scene_path, tex_coord_name):
    """Import example spawning imported actors into the current editor world using a callback."""
    # Create callback
    def on_import_completed(import_result):
        unreal.log(f"Simplygon import task using subsystem callback completed.")

        # Log result.
        if import_result.has_error:
            unreal.log_error(f"Import error: {import_result.error_message}")
        else:
            unreal.log(
                f"Import result: Num Actors imported {len(import_result.imported_actor_paths)}"
            )
            unreal.log(
                f"Import result: Num meshes imported: {len(import_result.imported_meshes)}"
            )
            unreal.log(
                f"Import result: Num materials imported: {len(import_result.imported_materials)}"
            )
            unreal.log(
                f"Import result: Num textures imported: {len(import_result.imported_textures)}"
            )

        # Remove callback from subsystem. Specific to these examples.
        # Not necessary to add & remove callbacks for each import/export.
        simplygon_subsystem = unreal.get_editor_subsystem(
            unreal.SimplygonSubsystem)
        simplygon_subsystem.on_import_scene_as_actors_completed.clear()

    simplygon_subsystem = unreal.get_editor_subsystem(
        unreal.SimplygonSubsystem)

    # Add callback to subsystem.
    simplygon_subsystem.on_import_scene_as_actors_completed.add_callable(
        on_import_completed
    )

    # Get world to spawn imported actors into.
    editor_subsystem = unreal.get_editor_subsystem(
        unreal.UnrealEditorSubsystem)
    world = editor_subsystem.get_editor_world()

    # Set import settings to use.
    import_settings = unreal.SgSceneImportSettings()
    import_settings.geometry_settings.tex_coord_names = [tex_coord_name]

    # Call import function which will call the callback once it's finished.
    simplygon_subsystem.import_scene_as_actors(
        import_scene_path, world, import_settings
    )

    # Optional wait for tasks to finish
    simplygon_subsystem.wait_for_all_tasks_to_complete()