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 Sep 13, 2019 · 20 revisions

Prerequisites

If you are on Windows you need to install Visual Studio 2019 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. If you're on Linux you must use .NET Core as Mono is currently broken.

Compiling USharp

  • Download the USharp source and copy the contents of the zip into into your engine plugins folder /Epic Games/UE_4.23/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. 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 buildcs command to compile the C# code**

**buildcs compiles a dll for packaged/shipping builds. Compiling the sln directly does not. The sln can be found at /USharp/Managed/UnrealEngine.Runtime/UnrealEngine.Runtime.sln

Creating a C# project

  • Open the "New Project" window in Unreal Engine. There should be a "C#" tab with templates you can use to create a new C# project.
  • The "Puzzle" template is a good starting point as it has examples of code for AActor, ACharacter, AGameMode
  • When you first create a C# project you will be prompted with dialogs to generate C# engine wrapper code and compile your C# game code. It's important to press "Yes".
  • C# game code is located under /PROJECT_NAME/Managed/

You can now start writing C#! Currently there isn't much documentation but look at the templates for examples of code.

Adding C# to an existing project

  • In the editor open "Edit->Project Settings...". USharp should be listed on the left hand side (under Plugins). Enable it and then reopen your project.
  • When you next open your project, you will be prompted to generate C# game code from the blank template.
  • USharp should now be abled and you can find the C# game code under /PROJECT_NAME/Managed/

Troubleshooting

  • If the "C#" tab doesn't exist in the "New Project" window; USharp wasn't compiled properly or isn't an enabled plugin.
  • If you need to regenerate C# engine wrapper code you can do so using the USharpGen modules command followed by USharpGen compile (in Unreal's command box available from Window->Developer Tools->Output Log). NOTE: Requires a USharp project to be loaded to use the commands.
  • 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 (you may need to also try regenerating C# engine wrapper code).
  • If there is missing C# wrapper code for a plugin you want to use, you can manually add it following the instructions here.

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. You can also force a hotreload via USharpRuntime reload.

NOTE: Packaging Mono / .NET Core currently requires them to be local to the USharp folder. To do this open PluginInstaller.exe and type copyruntime mono or copyruntime coreclr. This will copy Mono / .NET Core locally to the USharp folder.

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