# Unreal

Our Unreal connector is in an early stage of development. It supports receiving meshes from Speckle in Unreal Engine 4.

Make sure to check out (and star ⭐️ ) our Github repository: https://github.com/specklesystems/speckle-unreal (opens new window)

TIP

Check out our dedicated tutorials on Unreal (opens new window)!

# Installation

The Unreal connector is packaged as an Unreal Engine 4 plugin that is currently only available through GitHub. To use it in your project:

  1. Download speckle-unreal repository archive from https://github.com/specklesystems/speckle-unreal/archive/refs/heads/main.zip (opens new window)

  2. Extract the downloaded archive into your project's Plugins directory (if your project directory doesn't contain a directory called Plugins, you should create it)

  1. Open your UE4 project (or restart the editor if you already have it opened). This will build the plugin in your environment.

That's It! Your project can now use the Speckle plugin!

For additional resources, see Unreal's guides on Installing Unreal Engine (opens new window), Setting Up Visual Studio for Unreal Engine (opens new window), and Create a New Project (opens new window).

# Alternate Installation (git)

If you plan on developing on top of speckle-unreal or prefer to use git, you can clone the speckle-unreal repository into your project's Plugins directory

  1. Within your project's Plugins folder execute git clone https://github.com/specklesystems/speckle-unreal.git

  2. Open / Restart your Unreal project.

For a beginners guide to git, see git - the simple guide by Roger Dudler (opens new window).

# Usage

The plugin includes an actor type named Speckle Unreal Manager that you can use to import objects from Speckle.

Here is how to use it:

  1. In the Place Actors sidebar, search for Speckle Unreal Manager and add it to the world.
  1. Select the SpeckleUnrealManager instance in the World Outliner sidebar and use the options presented in the Speckle category
  1. Currently, we require an explicit ObjectID to import. You can explore the objects in a stream by using the Speckle Web App for the Speckle server that you use.

  1. If your Speckle Stream is not public, you must generate a Personal Access Token and set it in the Auth Token configuration option.

IMPORTANT

Treat your Personal Access Token as a password. If someone else has access to your auth token, they can access to your Speckle data.

  1. After you set up the import parameters, just click the Import Speckle Object button. The specified object and all its children will be important as mesh actors.

# General Notes

This plugin is in early stages of development. If you have any thoughts or suggestions about this plugin, you're welcome to discuss them in our forum (opens new window).

# Mesh Conversion

Document Note

Blue snippets refer to Speckle Objects (opens new window) classes.

Red snippets refer to Unreal Engine classes.

Brown snippets refer to Speckle Unreal (opens new window) classes.


Speckle-Unreal provides two types of mesh conversion

  1. ASpeckleUnrealProceduralMesh (opens new window):
    • Uses a UProceduralMeshComponent
    • Are fast to convert to, and allow run-time editing
    • Slowest to render, can't use baked lighting
  2. ASpeckleUnrealStaticMesh (opens new window):
    • Uses a UStaticMeshComponent.
    • Are slower to convert to, and can't be easily edited at runtime.
    • Faster to render, can use baked lighting (assuming appropriate UVs).
    • Built meshes are saved in /Game/Speckle/<streamid>/Geometry/<meshid>

By extending either ASpeckleUnrealStaticMesh or ASpeckleUnrealProceduralMesh, you can set certain UProperties to customise conversion¹. This can be done through C++ or Blueprints.

¹Dev Note
It is also possible to create a custom ASpeckleUnrealActor and implement ISpeckleMesh to have completely custom mesh conversions. (If you are doing this, give us a shout on the forums (opens new window), we can help!)

# Material Conversion

# Conversion of Materials

Speckle's Objects (opens new window) kit supports PBR materials through the RenderMaterial (opens new window) property of Speckle meshes.

When receiving meshes with a RenderMaterial (opens new window), the Unreal connector will create UMaterialInstance (opens new window)s which are applied to converted meshes.

# How are materials converted

For opaque materials, a UMaterialInstanceDynamic (opens new window) is created as child material instance of ASpeckleUnrealManager::BaseMeshOpaqueMaterial (opens new window). For translucent materials (with an opacity <1), ASpeckleUnrealManager::BaseMeshTransparentMaterial (opens new window) is used as the parent instead.

By default, these base materials are a simple UMaterial (opens new window)s with opaque/translucent shader models respectively. Both have several properties exposed (see screenshot), and during the conversion process, these properties are set with the values from the RenderMaterial (opens new window)².

SpeckleMaterial, the default BaseMeshOpaqueMaterial.

SpeckleGlassMaterial, the default BaseMeshTransparentMaterial.

By specifying a custom base material, users can have complete control over how these properties are assigned.

²Dev Note
URenderMaterial is a C++ port of Objects.Other.RenderMaterial (opens new window). RenderMaterial (opens new window) json is parsed into URenderMaterial. A UMaterialInstanceDynamic (opens new window) is created from a base UMaterialInterface (opens new window) before being assigned the values from URenderMaterial. ASpeckleUnrealStaticMesh (opens new window) gets or creates the correct material that should be applied to a mesh.

# Overriding Converted Materials

Speckle does not currently support textured materials.

Because of this, often users want to use their own textured UMaterialInterface (opens new window)s instead of the ones converted from the RenderMaterial (opens new window). Converted UMaterialInstance (opens new window)s can be overridden with custom UMaterialInterface (opens new window)s in two ways.

Screenshot of material overrides By ID in details panel of ASpeckleUnrealManager. Materials with the ID 280559dd3... will use this material instead of converting one from the object's RenderMaterial.

Screenshot of material overrides By Name in details panel of ASpeckleUnrealManager. Materials with the name Mossy_Grass will use this material instead of converting one from the object's RenderMaterial.

# Material Priorities

Material priority (high to low).

  1. A UMaterialInterface (opens new window) in ASpeckleUnrealManager::MaterialOverridesById (opens new window) that matches RenderMaterial (opens new window)s by their Speckle ID.
  2. A UMaterialInterface (opens new window) in ASpeckleUnrealManager::MaterialOverridesByName (opens new window) that matches RenderMaterial (opens new window)s by name.
  3. Converted RenderMaterial (opens new window) set on Mesh (opens new window) Speckle object.
  4. Converted RenderMaterial (opens new window) on Mesh (opens new window)'s parent Speckle object. (FallbackMaterial).³
  5. ASpeckleUnrealManager::DefaultMeshMaterial (opens new window)

³Dev Note
Depending on the source application, the RenderMaterial could a property of the Mesh object, or of the Meshes parent. This is why both cases 3 and 4 (Above) exist.

# Limitations

  • I order to use textured materials, meshes need to have Texture coordinates (UV coordinates). Currently, Texture coordinates are only outputted from Rhino, Blender, and Sketchup connectors. (More connectors will receive support shortly! see issue (opens new window)). The Unreal connector does not generate texture coordinates for you. Having UV coordinates also has other advantages for lighting.

  • Textures cannot be sent/received through Speckle, only flat colours and simple PBR properties. Fully supporting textures could add significant value for interoperability between Unreal, Unity, Blender, Rhino, and Sketchup, however poses several technical challenges.

    Of course, Users are more than welcome to extend Speckle's Objects kit to include textures and their own custom properties to suit their needs.

# Motivation

As a tool, Unreal shines when it comes to producing beautiful, photorealistic renders of scenes. This has significant value for Speckle users as a tool for producing high quality and real-time demonstrations, animations, and XR experiences.

For some users, the simple flat materials converted using an object's RenderMaterial (opens new window) will be all they want, and PBR properties are used by many of the connectors Speckle supports.

Many users, however, want to use textured materials, after all, Unreal excels in photorealism, and high quality materials are a significant part of that.

The Material Overrides feature of the Unreal connector addresses this need as it enables a semi-automated workflow for applying textured materials to received geometry.

It is worth mentioning that Unreal has integration with Quixel (opens new window), a library of high-quality materials and assets that are free to use inside of Unreal Engine.

Last Updated: 11/25/2021, 12:13:52 PM