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)
Check out our dedicated tutorials on Unreal (opens new window)!
The Unreal connector is packaged as an Unreal Engine 4 plugin that is currently only available through GitHub. To use it in your project:
speckle-unrealrepository archive from https://github.com/specklesystems/speckle-unreal/archive/refs/heads/main.zip (opens new window)
Extract the downloaded archive into your project's
Pluginsdirectory (if your project directory doesn't contain a directory called
Plugins, you should create it)
- 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
Within your project's
git clone https://github.com/specklesystems/speckle-unreal.git
Open / Restart your Unreal project.
For a beginners guide to git, see git - the simple guide by Roger Dudler (opens new window).
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:
- In the
Place Actorssidebar, search for Speckle Unreal Manager and add it to the world.
- Select the
SpeckleUnrealManagerinstance in the
World Outlinersidebar and use the options presented in the
- 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.
- If your Speckle Stream is not public, you must generate a Personal Access Token and set it in the
Auth Tokenconfiguration option.
Treat your Personal Access Token as a password. If someone else has access to your auth token, they can access to your Speckle data.
- After you set up the import parameters, just click the
Import Speckle Objectbutton. 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
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
ASpeckleUnrealProceduralMesh(opens new window):
- Uses a
- Are fast to convert to, and allow run-time editing
- Slowest to render, can't use baked lighting
- Uses a
ASpeckleUnrealStaticMesh(opens new window):
- Uses a
- 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
- Uses a
By extending either
ASpeckleUnrealProceduralMesh, you can set certain UProperties to customise conversion¹. This can be done through C++ or Blueprints.
It is also possible to create a custom
ISpeckleMeshto 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
# 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
SpeckleGlassMaterial, the default
By specifying a custom base material, users can have complete control over how these properties are assigned.
URenderMaterialis a C++ port of
Objects.Other.RenderMaterial(opens new window).
RenderMaterial(opens new window) json is parsed into
UMaterialInstanceDynamic(opens new window) is created from a base
UMaterialInterface(opens new window) before being assigned the values from
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.
- By Name - The
RenderMaterial.Name(opens new window) will be matched by name, against
UMaterialInterface(opens new window)s in the
ASpeckleUnrealManager::MaterialsOverridesByName(opens new window)
- By Id - The Speckle ID of the
RenderMaterial(opens new window) will be matched against
UMaterialInterface(opens new window) values in
ASpeckleUnrealManager::MaterialsOverridesById(opens new window)
Screenshot of material overrides By ID in details panel of
Materials with the ID
280559dd3... will use this material instead of converting one from the object's
Screenshot of material overrides By Name in details panel of
Materials with the name
Mossy_Grass will use this material instead of converting one from the object's
# Material Priorities
Material priority (high to low).
UMaterialInterface(opens new window) in
ASpeckleUnrealManager::MaterialOverridesById(opens new window) that matches
RenderMaterial(opens new window)s by their Speckle ID.
UMaterialInterface(opens new window) in
ASpeckleUnrealManager::MaterialOverridesByName(opens new window) that matches
RenderMaterial(opens new window)s by name.
RenderMaterial(opens new window) set on
Mesh(opens new window) Speckle object.
RenderMaterial(opens new window) on
Mesh(opens new window)'s parent Speckle object. (
ASpeckleUnrealManager::DefaultMeshMaterial(opens new window)
Depending on the source application, the
RenderMaterialcould a property of the
Meshobject, or of the
Meshes parent. This is why both cases 3 and 4 (Above) exist.
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.
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.