Skip to content
This repository has been archived by the owner on Oct 19, 2020. It is now read-only.

Plugin Setup

Jump to bottom
pixeltris edited this page Nov 25, 2018 · 20 revisions

Prerequisites

If you are on Windows you need to install Visual Studio 2017 with the latest version of the .NET and C++ tools

If you are MacOS you need to install Xcode

If you are on MacOS or Linux (or want to run Mono on Windows) you need to grab the latest version of x64 Mono from https://www.mono-project.com/download/stable/

If you want to run .NET Core you need to download the .NET Core 3.0 preview build from https://github.com/dotnet/core-sdk/blob/master/README.md#installers-and-binaries

Compiling USharp

  • Download the USharp source and copy the contents of the zip into into your engine plugins folder /Epic Games/UE_4.21/Engine/Plugins/ make sure that the folder is called USharp (not USharp-master) (it's important that the folder is named "USharp" and the .uplugin file is directly within that folder)
  • Compile /USharp/Managed/PluginInstaller/PluginInstaller.sln and /USharp/Managed/UnrealEngine.Runtime/UnrealEngine.Runtime.sln. If you are on MacOS or Linux you can do this using the "msbuild" command in a terminal
  • Run /USharp/Binaries/Managed/PluginInstaller/PluginInstaller.exe (this must be run via mono on MacOS / Linux)
  • In PluginInstaller type the buildcpp command to compile the C++ code
  • In PluginInstaller type the copyruntime all command (this is optional on Windows). This will copy Mono / .NET Core locally to the USharp folder.

USharp should now be available to enable in the editor (Edit->Plugins->Programming->USharp)

Generating C# wrapper code

To access native types (AActor, APawn, UActorComponent, etc) you need to generate C# wrapper code

  • In the editor open the output log (Window->Developer Tools->Output Log). At the bottom of the output log there should be a text box to enter commands
  • Use the USharpGen modules command. This will freeze the engine for a short period of time while it generates code
  • If the code generates successfully you can then compile it with the command USharpGen compile. If it fails to compile navigate to the .sln file it prints out and compile it manually (via msbuild or your favorite C# IDE)

If the above steps stop working after updating USharp delete the Modules folder at /USharp/Binaries/Managed/Modules/ and try again.

Writing C# game code

When you first opened the editor with USharp enabled it should have created a C# project under /YOUR_PROJECT/Managed/. Use this to write your C# game code (see the Test.cs file for rough samples of code).

If your C# project can't resolve UnrealEngine.Runtime.dll / UnrealEngine.dll references:

  • Manually add a reference to /USharp/Binaries/Managed/Modules/bin/Debug/UnrealEngine.dll and /USharp/Binaries/Managed/UnrealEngine.Runtime.dll
  • If it's still broken close the editor then delete .usharpGenerated and USharp.ProjectGeneratedVariables.props files from your project "Managed" folder. When you next open your project in Unreal Engine the references should be updated
  • If it's still broken regenerate the modules using the USharpGen command

Packaging and enabling multiple .NET runtimes

Multiple .NET runtimes can be enabled at the same time (.NET Framework, .NET Core, Mono) and you can switch between them in the editor. This allows for rich debugging between C# / C++ with .NET Core or .NET Framework whilst still being able to use Mono without having to reopen the editor.

/USharp/Binaries/Managed/Runtimes/DotNetRuntime.txt is used to determine which runtimes to initialize when USharp first loads. The following are valid entries (one per line, no additional text per line):

  • CLR
  • CoreCLR
  • Mono
  • Package:CoreCLR
  • Package:Mono

CLR is .NET Framework, CoreCLR is .NET Core and Mono obviously Mono. "Package:" means that the given runtime will be packaged when you are packaging your game (only valid for Mono / CoreCLR).

You can determine which runtimes are enabled by typing the USharpRuntime command. The same command is also used to switch the active runtime such as USharpRuntime Mono.

NOTE: Packaging will currently copy the runtime folders 2-3 times due to limitations in packaging. An unmodified Mono folder is around 400MB and and .NET Core is around 70MB. These folders can (and should) be trimmed down where appropriate which depends on your requirements. (It will first copy the runtime to /YOUR_PROJECT/Binaries/, then possibly a temporary directory used by the packaging process and then finally the target package directory.)

Clone this wiki locally