Unreal

​

Installation (Marketplace)

​

Installation (Git)

1. Git clone this repo into your project’s Plugins directory (created as needed).

git clone https://github.com/specklesystems/speckle-unreal

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

​

Usage (Editor)

1. In the Place Actors sidebar, search for Speckle Unreal Manager and add it to the world.

2. Select the SpeckleUnrealManager instance in the World Outliner sidebar and use the options presented in the Speckle category.

3. There are two ways to import objects using the Speckle Unreal Manager actor.

4. After you set up the receive parameters, just click the Receive button. The specified object and all its children will be imported as Actors.
   To set options on how the objects are converted, see the object-conversion secion.

​

Usage (Blueprint)

• A ServerTransport is used to make a HTTP request to a Speckle server for the object (and its children). It fetches JSON objects from the server, which are then stored in a local Memory Transport.
• The ReceiveOperation node handles the received objects, and deserializes them into Object Models (objects inheriting UBase).
• The SpeckleConverterComponent converts these objects into native actors/components.

​

Object conversion

Please note that ISpeckleConverter here, is not the same as the Speckle.​Core.​Kits.​ISpeckleConverter in the .NET SDK.

StaticMeshConverter and ProceduralMeshConverter are mutually exclusive, and for most users we recommend using static meshes (default).

​

Mesh converters

1. ProceduralMeshConverter(https://github.com/specklesystems/speckle-unreal/blob/main/Source/SpeckleUnreal/Public/Conversion/Converters/ProceduralMeshConverter.h):
   • Creates a UProceduralMeshComponent.
   • Slightly faster to convert, and allow run-time editing of vertices/faces.
   • Slowest to render, can’t use baked lighting.
2. StaticMeshConverter(https://github.com/specklesystems/speckle-unreal/blob/main/SpeckleUnrealProject/Plugins/SpeckleUnreal/Source/SpeckleUnreal/Public/SpeckleUnrealStaticMesh.h):
   • Creates a UStaticMeshComponent.
   • Mesh vertices/faces/etc can’t be edited easily (needs to be rebuilt).
   • Faster to render.
   • Built meshes can be saved as assets, allowing levels to be reloaded.
   • Additional Editor only build process allows for baked lighting, extra path-tracing options, and optimised lighting.

​

Material converter

​

How are materials converted

​

Overriding/Substituting converted materials

• By Name - The RenderMaterial.name will be matched against materials in the MaterialsOverridesByName array.
• By Id - The RenderMaterial.id will be by key with materials in the MaterailOverridesById map.

​

Material priorities

1. A material in OverridesById that matches by Id.
2. A material in OverridesByName that matches by Name.
3. A material cached from a previous receive operation.
4. A material asset in the /Game/Speckle/Materials/{id} package. (i.e. from a previous receive, but not cached, or from a strategically placed asset)
5. A material converted from RenderMaterial of the Mesh.
6. Finally, if all else fails, the DefaultMaterial set in the MaterialConverter will be used.

Note: If there is no material on an object, we do not fall back to the parent’s material like previous versions of this connector. We are aware this may cause unexpected behaviour. This issue will be addressed.

​

Limitations

• In 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. The Unreal Connector does not generate texture coordinates for you. Having UV coordinates also has other advantages for baked lighting.
• Textures cannot be sent/received through Speckle, only flat colours and simple PBR properties. Texture support is on our roadmap, but there are several techincal chalanges to overcome before this is possible.

​

Developing custom conversion logic

1. You can extend an existing converter, and re-implement specific functions.
2. You can write a completely custom ISpeckleConverter class and add an instance to your SpeckleConverterComponent
3. You can extend the SpeckleConverterComponent to customise more generally how objects are converted and actors attached.

​

Custom object models

1. The UE plugin does not provide a reflection based (de)serializer. Object Models implement their own (de)serialization logic in the form of manually parsing JSON properties.
2. Only certain Object Models are provided out of the box, while most are direct ports of Objects kit, some are not!
3. The Speckle Type is defined in the Object Model’s constructor, not by its Namespace like in .NET.
4. Units are applied while parsing (rather than ToNative conversion - subject to change)

bool UMyObjectModel::Parse(const TSharedPtr<FJsonObject> Obj, const TScriptInterface<ITransport> ReadTransport)
{
	if(!Super::Parse(Obj, ReadTransport)) return false;

	// Add your own JSON parsing here!
	// Remove explicit properties from DynamicProperties array
	
	// Simple example of parsing an optional number property:
	if(Obj->TryGetNumberField("myProperty", MyProperty)) DynamicProperties.Remove("myProperty");
	
	// Simple example of parsing an required number property:
	if(!Obj->TryGetNumberField("myProperty", MyProperty)) return false; // Return false on error, rather than fatal assertions
	DynamicProperties.Remove("myProperty");
	
	//Return true if parsed successfully
	return true;
}

Currently, Unit scaling is applied during Parsing (not conversion). This is subject to change!

​

Creating converters (C++)

UCLASS(BlueprintType, Blueprintable)
class SPECKLEUNREAL_API UMyConverter : public UObject, public ISpeckleConverter
{
	GENERATED_BODY()

public:
	virtual UObject* ConvertToNative_Implementation(const UBase* SpeckleBase, UWorld*, TScriptInterface<ISpeckleConverter>&) override;
	
	virtual bool CanConvertToNative_Implementation(TSubclassOf<UBase> BaseType) override;

}

UObject* UMyConverter::ConvertToNative_Implementation(const UBase* SpeckleBase, UWorld* World, TScriptInterface<ISpeckleConverter>& AvailableConverters)
{
	const UMyObjectModel* m = Cast<UMyObjectModel>(SpeckleBase);
	
	if(m == nullptr) return nullptr;
	
	return MyObjectToNative(m);
}

AActor* UMyConverter::MyObjectToNative(const UMyObjectModel* MyObject, UWorld* World)
{
	// Conversion logic here!!
	// Convert MyObject into an Actor that we return
}

​

Creating converters (Blueprint)