Writing Native Code - Revision history

Plasma: /* Writing Actual Code */

2024-05-19T12:01:59Z

Writing Actual Code

← Older revision		Revision as of 12:01, 19 May 2024
Line 150:		Line 150:
	LINK_NATIVES(ATestNativeClass);		LINK_NATIVES(ATestNativeClass);
	</syntaxhighlight>		</syntaxhighlight>


	You should generally follow the advice in the comment at the top of the generated files and don't modify them. Place your function definitions and other code in their own files. You might want to make some changes to the UnrealScript code later down the line, like adding more classes or native functions which means that you have to re run the ucc which in turn would mean all your changes to these files are lost. For simplicity this tutorial does everything in the generated files but you really shouldn't.		You should generally follow the advice in the comment at the top of the generated files and don't modify them. Place your function definitions and other code in their own files. You might want to make some changes to the UnrealScript code later down the line, like adding more classes or native functions which means that you have to re run the ucc which in turn would mean all your changes to these files are lost. For simplicity this tutorial does everything in the generated files but you really shouldn't.
Line 221:		Line 220:
	[[File:Result.PNG]]		[[File:Result.PNG]]

	As you can see, the function is being called and prints our message to the log. It also modifies the "TestInt" variable which then is printed out from UnrealScript.		As you can see, the function is being called and prints our message to the log. It also modifies the "TestInt" variable which then is printed out from UnrealScript.

	== Returning a Value from a Native Function ==		== Returning a Value from a Native Function ==

Plasma at 12:01, 19 May 2024

2024-05-19T12:01:25Z

← Older revision		Revision as of 12:01, 19 May 2024
Line 184:		Line 184:
	#include "../../Engine/Inc/Engine.h" //This also includes "Core"		#include "../../Engine/Inc/Engine.h" //This also includes "Core"
	</syntaxhighlight>		</syntaxhighlight>


	Now create the body of your native function in the .cpp file. The signature looks like this:		Now create the body of your native function in the .cpp file. The signature looks like this:
Line 190:		Line 191:
	void execTestNativeFunc(FFrame& Stack, void* Result);		void execTestNativeFunc(FFrame& Stack, void* Result);
	</syntaxhighlight>		</syntaxhighlight>


	Notice how Unreal automatically generated the prefix "exec". This is only to differentiate between functions that are callable from UnrealScript and others. Also look at the parameters. Although we declared it to take in a string in UnrealScript it now has different types as parameters. The function signatures for all native functions are exactly the same. The parameters that are passed in UnrealScript are contained in the "Stack" which is of the type "FFrame".		Notice how Unreal automatically generated the prefix "exec". This is only to differentiate between functions that are callable from UnrealScript and others. Also look at the parameters. Although we declared it to take in a string in UnrealScript it now has different types as parameters. The function signatures for all native functions are exactly the same. The parameters that are passed in UnrealScript are contained in the "Stack" which is of the type "FFrame".
Line 205:		Line 207:
	}		}
	</syntaxhighlight>		</syntaxhighlight>


	In the function body we use the "P_GET_STR" macro to grab the string that was passed to the function in UnrealScript from the stack. This macro creates a variable of type 'FString' with the name you provided as a parameter which is why I can use 'StringVar' later in the function. There are also other macros for different parameter types like "P_GET_INT", "P_GET_FLOAT", "P_GET_ACTOR", etc... You can find all of them in "Core/Inc/unscript.h".		In the function body we use the "P_GET_STR" macro to grab the string that was passed to the function in UnrealScript from the stack. This macro creates a variable of type 'FString' with the name you provided as a parameter which is why I can use 'StringVar' later in the function. There are also other macros for different parameter types like "P_GET_INT", "P_GET_FLOAT", "P_GET_ACTOR", etc... You can find all of them in "Core/Inc/unscript.h".

Plasma at 12:00, 19 May 2024

2024-05-19T12:00:08Z

Show changes

Plasma at 11:53, 19 May 2024

2024-05-19T11:53:25Z

← Older revision		Revision as of 11:53, 19 May 2024
Line 73:		Line 73:

	When you've successfully created and configured your Project, you have to add the files generated by the ucc so that you can compile them. Just open the folders in Windows explorer and drag them onto your project in the solution explorer.		When you've successfully created and configured your Project, you have to add the files generated by the ucc so that you can compile them. Just open the folders in Windows explorer and drag them onto your project in the solution explorer.

			== Writing Actual Code ==

			Now go to Visual Studio and open both source files. It should look like this:


			MyPackageClasses.h:

			<syntaxhighlight lang="C++" line>
			/*===========================================================================
			C++ class definitions exported from UnrealScript.
			This is automatically generated by the tools.
			DO NOT modify this manually! Edit the corresponding .uc files instead!
			===========================================================================*/

			#ifndef MYPACKAGE_NATIVE_DEFS
			#define MYPACKAGE_NATIVE_DEFS

			#if SUPPORTS_PRAGMA_PACK
			#pragma pack (push,4)
			#endif

			#ifndef MYPACKAGE_API
			#define MYPACKAGE_API DLL_IMPORT
			#endif



			class MYPACKAGE_API ATestNativeClass : public AActor
			{
			public:
			INT TestInt;
			void execTestNativeFunc(FFrame& Stack, void* Result);
			DECLARE_CLASS(ATestNativeClass,AActor,0,MyPackage)
			NO_DEFAULT_CONSTRUCTOR(ATestNativeClass)
			DECLARE_NATIVES(ATestNativeClass)
			};



			#if SUPPORTS_PRAGMA_PACK
			#pragma pack (pop)
			#endif

			#if __STATIC_LINK

			#define AUTO_INITIALIZE_REGISTRANTS_TEST \
			ATestNativeClass::StaticClass(); \

			#endif // __STATIC_LINK

			#endif // CORE_NATIVE_DEFS
			</syntaxhighlight>


			MyPackageClasses.cpp:

			<syntaxhighlight lang="C++" line>
			/*===========================================================================
			C++ class definitions exported from UnrealScript.
			This is automatically generated by the tools.
			DO NOT modify this manually! Edit the corresponding .uc files instead!
			===========================================================================*/

			#include "MyPackagePrivate.h" //Either Create a file called "MyPackagePrivate.h" or just replace with "MyPackageClasses.h"

			IMPLEMENT_PACKAGE(MyPackage)



			IMPLEMENT_CLASS(ATestNativeClass);
			FNativeEntry<ATestNativeClass> ATestNativeClass::StaticNativeMap[] = {
			MAP_NATIVE(TestNativeFunc,0)
			{NULL,NULL}
			};
			LINK_NATIVES(ATestNativeClass);
			</syntaxhighlight>


			You should generally follow the advice in the comment at the top of the generated files and don't modify them. Place your function definitions and other code in their own files. You might want to make some changes to the UnrealScript code later down the line, like adding more classes or native functions which means that you have to re run the ucc which in turn would mean all your changes to these files are lost. For simplicity this tutorial does everything in the generated files but you really shouldn't.


			But what if you wanted to add some member functions to your class declaration? You can't do that without modifying the generated code but luckily there's a functionality in the UnrealScript compiler that does this for you: At the end of your uc file add a block called 'cpptext'. Everything contained within is added to the C++ class declaration. For example the cpptext block from one of my projects looks like this:

			<syntaxhighlight lang="C++" line>
			cpptext
			{
			//Overrides
			virtual UBOOL Exec(const char* Cmd, FOutputDevice& Ar);
			virtual void Tick(float DeltaTime);
			virtual float GetMaxTickRate();
			}
			Just make sure you don't add any non-static member variables there!!!
			</syntaxhighlight>


			Where it says this:

			<syntaxhighlight lang="C++" line>
			#ifndef MYPACKAGE_API
			#define MYPACKAGE_API DLL_IMPORT
			#endif
			</syntaxhighlight>

			replace "DLL_IMPORT" with "DLL_EXPORT" since we want to export symbols from our new dll. Alternatively you can also go to the project properties and under "C/C++ -> Preprocessor -> Preprocessor definitions" add "MYPACKAGE_API=DLL_EXPORT" that's a better and cleaner solution since you don't have to change it every time the files are generated.

			Also in "MyPackageClasses.h" you need to include the necessary headers. Which ones depends on what classes you're using. I created a subclass of "AActor" (C++ classes have the prefix 'A' for subclasses of Actor, 'U' for subclasses of Object and 'F' for everything else) which means that I have to include the headers of "Engine" since that's where Actor is defined. So add this line above your class definition:

Plasma at 11:50, 19 May 2024

2024-05-19T11:50:51Z

← Older revision		Revision as of 11:50, 19 May 2024
Line 69:		Line 69:
	ImportLibrary = $(ProjectDir)/lib/$(TargetName).lib		ImportLibrary = $(ProjectDir)/lib/$(TargetName).lib
	</pre>		</pre>

			It could be that there is an issue where the properties on the right are not visible and instead there is just a big grey area. The solution to this problem is installing the .NET framework 1.0 which can be found [https://www.microsoft.com/en-us/download/details.aspx?id=96 here]. Follow [https://superuser.com/questions/120218/how-do-i-install-net-framework-1-1-for-windows-7 these] instructions to install it on newer versions of windows.

			When you've successfully created and configured your Project, you have to add the files generated by the ucc so that you can compile them. Just open the folders in Windows explorer and drag them onto your project in the solution explorer.

Plasma at 11:48, 19 May 2024

2024-05-19T11:48:46Z

← Older revision		Revision as of 11:48, 19 May 2024
Line 48:		Line 48:

	You should see the following:		You should see the following:

			[[File:ProjectProperties.PNG]]

			Change the following properties:

			<pre>
			General:
			OutputDirectory = $(SolutionDir)/../GameData/System
			Configuration Type = Dynamic Library (.dll)
			Use Managed Extensions = No
			Character Set = Not Set
			C/C++:
			Code Generation:
			Runtime Library = Multi-threaded DLL (/MD)
			Struct Member Alignment = 4 Bytes (/Zp4)
			Advanced:
			Calling Convention = __fastcall (/Gr)
			Linker:
			Advanced:
			ImportLibrary = $(ProjectDir)/lib/$(TargetName).lib
			</pre>

Plasma at 11:46, 19 May 2024

2024-05-19T11:46:05Z

← Older revision		Revision as of 11:46, 19 May 2024
Line 38:		Line 38:

	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 enter yes for both. They are created in the 'Inc' and 'Src' folders respectively.		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 enter yes for both. They are created in the 'Inc' and 'Src' folders respectively.

			== Setting Up Visual Studio .NET 2003 ==

			In order to write native code for Republic Commando you first need [[MS Visual Studio 2003]]. While it is possible to user a newer version of Visual Studio, it is not recommended due to C++ not having a standardized [https://en.wikipedia.org/wiki/Application_binary_interface ABI]. This means that there is no guarantee for binary compatibility between modules compiled with different compilers or even different versions of the same compiler. Compilation will work fine on newer compilers but there will most likely be random crashes at startup. Also mixing different versions of the MSVC++ runtime libraries will only lead to more problems.

			VS .NET 2003 is rather old and thus, 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. You can also use a newer better editor and only use VS to compile everything from the command line.

			Once you have installed Visual Studio open it up and download or clone this solution that is going to contain all your native coding projects: [https://github.com/SWRC-Modding/CT Github]. This repository always contains the most up-to-date version of the headers. Place the content of the 'CT' folder in the Code folder you just created. Open the solution up in visual studio and you will see that it already contains three native coding projects that you can use as an example. You can use these projects and add your code there but you probably want to create a new project with a different name. In order to do that go to the explorer on the left, right-click the solution ('CT') and go to "Add->New Project...". Create an "Empty Project (.NET)" with the same name as 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. Right click the project (not the Solution!) in the solution explorer and select Properties".

			You should see the following:

Plasma at 11:44, 19 May 2024

2024-05-19T11:44:19Z

← Older revision		Revision as of 11:44, 19 May 2024
Line 34:		Line 34:

	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 have to 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' in the same folder as 'Classes'.		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 have to 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' in the same folder as 'Classes'.

			[[File: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 enter yes for both. They are created in the 'Inc' and 'Src' folders respectively.

Plasma at 11:43, 19 May 2024

2024-05-19T11:43:19Z

← Older revision		Revision as of 11:43, 19 May 2024
Line 28:		Line 28:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

			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 print from 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. I also declared it as final since I don't want it to be overridden by a subclass but you don't have to do this. 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.

			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 have to 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' in the same folder as 'Classes'.

Plasma at 11:42, 19 May 2024

2024-05-19T11:42:49Z

← Older revision		Revision as of 11:42, 19 May 2024
Line 13:		Line 13:
	For the sake of this tutorial I'm going create a really simple and quite useless class that has only one native function which writes a string to the log file.		For the sake of this tutorial I'm going create a really simple and quite useless class that has only one native function which writes a string to the log file.

	<~~codeblock~~>		<syntaxhighlight lang="C++" line>
	class TestNativeClass extends Actor native		class TestNativeClass extends Actor native
	placeable;		placeable;
Line 27:		Line 27:
	Log(TestInt); //Printing out TestInt which has been modified in C++ code		Log(TestInt); //Printing out TestInt which has been modified in C++ code
	}		}
	</~~codeblock~~>		</syntaxhighlight>