General Programming Guide - Revision history

PkR at 00:37, 14 October 2025

2025-10-14T00:37:24Z

← Older revision		Revision as of 00:37, 14 October 2025
Line 321:		Line 321:
	</syntaxhighlight>		</syntaxhighlight>

	=== Conditions (~~using~~ <code>if</code> and <code>else</code>) ===		=== Conditions (Using <code>if</code> and <code>else</code>) ===
	For conditions, <code>if</code>, <code>else if</code> and <code>else</code> statements are used. The condition itself is enclosed in brackets. Here is a simple function that compares values and outputs different text based on the result of comparison.<syntaxhighlight lang="cpp">		For conditions, <code>if</code>, <code>else if</code> and <code>else</code> statements are used. The condition itself is enclosed in brackets. Here is a simple function that compares values and outputs different text based on the result of comparison.<syntaxhighlight lang="cpp">
	void CompareTwoValues(Uint32 value1, Uint32 value2)		void CompareTwoValues(Uint32 value1, Uint32 value2)
Line 362:		Line 362:
	</syntaxhighlight>		</syntaxhighlight>

	=== Switch ~~statements~~ ===		=== Switch Statements ===
	If you have to compare the same variable against different values multiple times, switch statements are a great way to improve readability of your code.		If you have to compare the same variable against different values multiple times, switch statements are a great way to improve readability of your code.

Line 412:		Line 412:
	</syntaxhighlight>		</syntaxhighlight>

	==== Using <code>break</code> and ~~fall through cases~~ ====		==== Using <code>break</code> and Fall Through Cases ====
	In the previous examples, the function returned at the end of each case. However, often you need to continue executing the function after the switch statement. To finish the case, you add a <code>break;</code> statement. If you don't add it, the case will fall through, and the code will continue executing for the next case. You can combine <code>break</code> and fall through cases to create branching code.<syntaxhighlight lang="cpp">Uint32 value = RESULT_NONE;		In the previous examples, the function returned at the end of each case. However, often you need to continue executing the function after the switch statement. To finish the case, you add a <code>break;</code> statement. If you don't add it, the case will fall through, and the code will continue executing for the next case. You can combine <code>break</code> and fall through cases to create branching code.<syntaxhighlight lang="cpp">Uint32 value = RESULT_NONE;

Line 433:		Line 433:
	PrintDebug("Moving!");</syntaxhighlight>In the example above, when <code>mode</code> is <code>MODE_INIT</code>, <code>MODE_END</code> and <code>MODE_STOP</code> the value of <code>value</code> will be <code>RESULT_NOTMOVING</code>, but when <code>mode</code> is <code>MODE_MOVING</code> the value will be <code>RESULT_MOVING</code>.		PrintDebug("Moving!");</syntaxhighlight>In the example above, when <code>mode</code> is <code>MODE_INIT</code>, <code>MODE_END</code> and <code>MODE_STOP</code> the value of <code>value</code> will be <code>RESULT_NOTMOVING</code>, but when <code>mode</code> is <code>MODE_MOVING</code> the value will be <code>RESULT_MOVING</code>.

	=== Using <code>for</code> and <code>do-while</code> ~~loops~~ ===		=== Using <code>for</code> and <code>do-while</code> Loops ===

	To perform the same action on multiple variables or array members, you can use a <code>for</code> loop like this:<syntaxhighlight lang="cpp">		To perform the same action on multiple variables or array members, you can use a <code>for</code> loop like this:<syntaxhighlight lang="cpp">
Line 459:		Line 459:
	}</syntaxhighlight>		}</syntaxhighlight>

	=== Using ~~bitwise operators~~ ===		=== Using Bitwise Operators ===

	==== Setting and ~~checking flags~~ ====		==== Setting and Checking Flags ====
	The Sonic Adventure games often use 16-bit (2 byte) or 32-bit (4 byte) values to store flags. Since a flag can only be on or off, it only requires one bit of information, and a 32-bit value can store 32 independent flags. This becomes useful because you can pass all flags to functions as a single value and check or set them independently within the function.		The Sonic Adventure games often use 16-bit (2 byte) or 32-bit (4 byte) values to store flags. Since a flag can only be on or off, it only requires one bit of information, and a 32-bit value can store 32 independent flags. This becomes useful because you can pass all flags to functions as a single value and check or set them independently within the function.

Line 486:		Line 486:
	// NJD_FLAG_USE_ALPHA, NJD_FLAG_FLIP_U and NJD_FLAG_IGNORE_LIGHT are some of the common material flags used in Ninja SDK. They are defined in Ninja defines.</syntaxhighlight>		// NJD_FLAG_USE_ALPHA, NJD_FLAG_FLIP_U and NJD_FLAG_IGNORE_LIGHT are some of the common material flags used in Ninja SDK. They are defined in Ninja defines.</syntaxhighlight>

	==== Bitwise ~~operators~~ ====		==== Bitwise Operators ====
	Sometimes you need to combine the bits of two variables in a single value, or split a single variable's bits into multiple variables. To do that, you use bitwise operators XOR <code>^</code>, AND <code>&</code>, OR <code>\|</code>, or bit shifts <code><<</code> and <code>>></code>.		Sometimes you need to combine the bits of two variables in a single value, or split a single variable's bits into multiple variables. To do that, you use bitwise operators XOR <code>^</code>, AND <code>&</code>, OR <code>\|</code>, or bit shifts <code><<</code> and <code>>></code>.

Line 535:		Line 535:
	In other words, source files have the actual '''implementation''' of your code, while header files contain the '''interface''' to that implementation. As such, source and header files often come in pairs sharing the same name, e.g. <code>mod.cpp</code> and <code>mod.h</code>.		In other words, source files have the actual '''implementation''' of your code, while header files contain the '''interface''' to that implementation. As such, source and header files often come in pairs sharing the same name, e.g. <code>mod.cpp</code> and <code>mod.h</code>.

	==== Using ~~headers~~ ====		==== Using Headers ====
	To use the interface from one source file in a different source file, you need to <code>#include</code> the header. For example, to enable the use of SADX Mod Loader types, functions etc. in your mod, you need to add the line <code>#include <SADXModLoader.h></code> at the top of your <code>.cpp</code> file.		To use the interface from one source file in a different source file, you need to <code>#include</code> the header. For example, to enable the use of SADX Mod Loader types, functions etc. in your mod, you need to add the line <code>#include <SADXModLoader.h></code> at the top of your <code>.cpp</code> file.

Line 545:		Line 545:
	Depending on the contents of your header, including the same header in multiple source files can lead to a compilation error. To avoid such errors, add <code>#pragma once</code> at the top of the header. This directive tells the compiler to only include that header once in a single compilation.		Depending on the contents of your header, including the same header in multiple source files can lead to a compilation error. To avoid such errors, add <code>#pragma once</code> at the top of the header. This directive tells the compiler to only include that header once in a single compilation.

	==== Using static ~~declarations~~ ====		==== Using <code>static</code> Declarations ====
	If you put <code>static</code> before a variable or a function, it will only be usable in the current source file. Static variables also retain their values between function calls and last until quitting the game.<syntaxhighlight lang="cpp">		If you put <code>static</code> before a variable or a function, it will only be usable in the current source file. Static variables also retain their values between function calls and last until quitting the game.<syntaxhighlight lang="cpp">
	static void StaticFunction();		static void StaticFunction();

PkR at 16:09, 12 October 2025

2025-10-12T16:09:19Z

← Older revision		Revision as of 16:09, 12 October 2025
Line 571:		Line 571:
	</syntaxhighlight>'''SA2'''<syntaxhighlight lang="cpp">		</syntaxhighlight>'''SA2'''<syntaxhighlight lang="cpp">
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''		</syntaxhighlight>

			''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''

	Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)

PkR at 16:08, 12 October 2025

2025-10-12T16:08:12Z

← Older revision		Revision as of 16:08, 12 October 2025
Line 572:		Line 572:
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''		</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''


	Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)

PkR at 16:07, 12 October 2025

2025-10-12T16:07:49Z

← Older revision		Revision as of 16:07, 12 October 2025
Line 572:		Line 572:
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''		</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''


	Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)

PkR at 16:06, 12 October 2025

2025-10-12T16:06:59Z

← Older revision		Revision as of 16:06, 12 October 2025
Line 572:		Line 572:
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''		</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''


	Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)

PkR at 16:06, 12 October 2025

2025-10-12T16:06:43Z

← Older revision		Revision as of 16:06, 12 October 2025
Line 572:		Line 572:
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''		</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''


	Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)

PkR at 16:06, 12 October 2025

2025-10-12T16:06:23Z

← Older revision		Revision as of 16:06, 12 October 2025
Line 571:		Line 571:
	</syntaxhighlight>'''SA2'''<syntaxhighlight lang="cpp">		</syntaxhighlight>'''SA2'''<syntaxhighlight lang="cpp">
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.		</syntaxhighlight>''The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.''

	Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)

PkR at 16:05, 12 October 2025

2025-10-12T16:05:55Z

← Older revision		Revision as of 16:05, 12 October 2025
Line 571:		Line 571:
	</syntaxhighlight>'''SA2'''<syntaxhighlight lang="cpp">		</syntaxhighlight>'''SA2'''<syntaxhighlight lang="cpp">
	extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };		extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
	</syntaxhighlight>Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)		</syntaxhighlight>The "C" after <code>extern</code> is necessary for compatibility with both C and C++ code. It allows calling C functions from C++ code.

			Apart from that, your mod must export the mod's initialization (<code>Init</code>) function. This function is what makes your mod code start working when the Mod Loader loads it.<syntaxhighlight lang="cpp">extern "C" __declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)
	{		{
	// Your code here		// Your code here

PkR at 16:01, 12 October 2025

2025-10-12T16:01:19Z

← Older revision		Revision as of 16:01, 12 October 2025
Line 593:		Line 593:
	__declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer }; // This is needed for the Mod Loader to recognize the DLL.		__declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer }; // This is needed for the Mod Loader to recognize the DLL.
	}		}
	</syntaxhighlight>		</syntaxhighlight>'''Mod Loader exports are used only once for the whole mod. You only need to put the Mod Loader exports in your mod's main source file (e.g. <code>mod.cpp</code>).'''

PkR at 15:58, 12 October 2025

2025-10-12T15:58:29Z

← Older revision		Revision as of 15:58, 12 October 2025
Line 551:		Line 551:
	</syntaxhighlight>		</syntaxhighlight>

	=== Using <code>extern</code> ===		==== Using <code>extern</code> ====
	If you define a variable in one source file and want to use it in another source, you use the <code>extern</code> keyword. Basically <code>extern</code> is the opposite of <code>static</code>.		If you define a variable in one source file and want to use it in another source, you use the <code>extern</code> keyword. Basically <code>extern</code> is the opposite of <code>static</code>.

Line 560:		Line 560:
	For functions, the <code>extern</code> keyword is not necessary because this behavior is default for functions. You can mark a function as <code>static</code> to change it.		For functions, the <code>extern</code> keyword is not necessary because this behavior is default for functions. You can mark a function as <code>static</code> to change it.

	=== Using <code>extern "C"</code> and <code>__declspec(dllexport)</code> ===		==== Using <code>extern "C"</code> and <code>__declspec(dllexport)</code> ====
	When your mod has a function or variable that you want to be used outside the mod itself, you need to export it.		When your mod has a function or variable that you want to be used outside the mod itself, you need to export it.