If you want to help us maintaining this wiki, check out our discord server: https://discord.gg/3u69jMa 

Writing Native Code

From SWRC Wiki
Revision as of 17:21, 27 January 2018 by Leon (talk | contribs)
Jump to navigation Jump to search

Note: Some C++ and UnrealScript knowledge is required.

Introduction

Native coding in the Unreal Engine refers to code that is written in C++ instead of UnrealScript. This C++ code can be called from a script to execute tasks that are either too slow in UnrealScript (about 20 times slower than C++) or are not possible at all due to the limited features of the language. Native coding is only officially supported by Unreal Tournament from 1999 (I think Deus Ex as well...) since it is the only game that has its native header files publicly available for download. Epic never released the headers for newer versions of the engine due to licensing issues with third party code. However, after countless hours of work it was possible to modify the UT99 headers in such a way that they're usable with Republic Commando. This process is not finished yet but the most important classes like Object, Actor, Pawn and some others already work.

The way native coding works in Unreal is that you compile your scripts into a .u package and then when you write your C++ code you compile it as a dll with the same name as your package. When the game is loading a UnrealScript class and detects that it was declared as native, it also looks for a dll which contains the native code for this UnrealScript class.

Getting Started

Before you can write any C++ code you first need to create a UnrealScript class that you declare as native. This tutorial assumes that you already know how to compile UnrealScript code with ucc. If you don't, then the download for the Republic Commando UCC contains a brief explanation in its readme.

For the sake of this tutorial I'm going create a really simple and quite useless class that has one native function which writes a string to the log file.

class TestNativeClass extends Actor native
                                    placeable;

var int TestInt;

native(1024) final function TestNativeFunc(string param);

function PostBeginPlay(){
	Super.PostBeginPlay();

	TestNativeFunc("Hello World!");
	Log(TestInt);
}

The class is going to be implemented in C++ and thus must be declared as 'native'. I added an integer variable called 'TestInt' that we're going to modify in C++ and then use in UnrealScript just to show that both, the C++ and Unrealscript classes refer to the exact same object in memory.

Furthermore, I declared a native function called 'TestNativeFunc' that takes in a string parameter. Notice the number in parentheses right after the 'native' keyword. This is the unique identifier Unreal uses to associate this UnrealScript function declaration with the actual C++ function. Some of these IDs are already used by the engine so try not to overwrite them. You can check which ones are available by entering the 'DumpNatives' console command while ingame. It will write all available IDs to the log file. However, I always start at 1024. All following numbers are definitely not in use by the game so you can really use anything up to 4095 which is the maximum amount of native functions.

In my 'PostBeginPlay' function I simply call the native function with "Hello World!" as the string parameter and I also write 'TestInt' which at this point has been changed in C++ code to the log file.


Before you go now and compile the script with the ucc you want to do something else. When compiling a native class the ucc also generates a header and a source file with the C++ class definition and some other setup code. But these won't be created by default because the folder they're supposed to be created in doesn't exist so we'll do that before we compile our class. In the folder that contains the UnrealScript source code you have a folder with the name of your package which in turn contains a folder called 'Classes' that holds all the .uc files for this package. Navigate to your package's folder and create two new folders called 'Inc' and 'Src'.

FolderLayout.PNG

Now compile your package with ucc make. When the compilation is successful the ucc will prompt you whether you want to overwrite the files "MyPackageClasses.h" and "MyPackageClasses.cpp". Just click on yes for both. They are created in the 'Inc' and 'Src' folders.

Setting Up Visual Studio .NET 2003

In order to write native code for Republic Commando you first need MS Visual Studio 2003. Newer versions could work but probably won't so just use this one. Since it was also used to compile RC it gives you maximum compatibility. However, due to it being rather old, it has some issues with newer versions of Windows but there are workarounds. You can ignore any errors that might occur during the installation as it should work regardless.

Once you have installed Visual Studio open it up and create a new solution that is going to contain all your native coding projects. Go to "File->New->Blank Solution...", enter a name and click Ok. Then go ahead, right click the newly created solution in the solution explorer to the left and go to "Add->New Project...". Create an "Empty Project (.NET)" with the same name of your UnrealScript package. We are actually not going to use .NET but most of the other project default configurations don't work because the buttons in the Wizard are broken on modern Windows for some reason. When you have successfully created a new project you have to adjust some settings. But before you do anything go to the top toolbar and where it says 'Debug' select 'Release' from the drop down menu. The right click the project (not the Solution!) in the solution explorer and select "Properties".

You should see the following:

ProjectProperties.PNG

There's an issue that I've seen (on Windows 7 but not on Windows 10 strangely) where the properties on the right are not visible and there's just a big grey area. In that case, close Visual Studio, download this pre-configured project and place it in the "\Documents\Visual Studio Projects\MySolution\MyProject\" folder (but delete the one you created first). Rename it so that it has name of your project.

If you didn't have any problems and everything is displaying fine you have to adjust the following properties:

General:
	Configuration Type = Dynamic Library (.dll)
	Use Managed Extensions = No
	Character Set = Not Set
C/C++:
	Code Generation:
		Runtime Library = Multi-threaded DLL (/MD)	//Not necessary but recommended...
		Struct Member Alignment = 4 Bytes (/Zp4)
	Advanced:
		Calling Convention = __fastcall (/Gr)

When that is done place the source files (.h and .cpp) generated by the ucc in the "\Documents\Visual Studio Projects\MySolution\Test\"