Export interface for external call

CREDITS.md

@@ -720,6 +720,7 @@ This page lists all the individual contributions to the project by their author.
   - Fix an issue that the move mission of the jumpjet does not end correctly
   - Fix the issue that the Jumpjet must end its movement before starting the next mission
   - Taunt warhead
+  - Export interface for external call
 - **solar-III (凤九歌)**
   - Target scanning delay customization (documentation)
   - Skip target scanning function calling for unarmed technos (documentation)

Phobos.vcxproj

@@ -30,6 +30,8 @@
     <ClCompile Include="src\Ext\EBolt\Hooks.cpp" />
     <ClCompile Include="src\Ext\Unit\Hooks.SimpleDeployer.cpp" />
     <ClCompile Include="src\Ext\Unit\Hooks.Unload.cpp" />
+    <ClCompile Include="src\Interop\AttachEffect.cpp" />
+    <ClCompile Include="src\Interop\TechnoExt.cpp" />
     <ClCompile Include="src\New\Entity\Ares\RadarJammerClass.cpp" />
     <ClCompile Include="src\New\Type\Affiliated\CreateUnitTypeClass.cpp" />
     <ClCompile Include="src\Blowfish\blowfish.cpp" />
@@ -221,6 +223,8 @@
   <ItemGroup>
     <ClInclude Include="src\Ext\EBolt\Body.h" />
     <ClInclude Include="src\Ext\Event\Body.h" />
+    <ClInclude Include="src\Interop\AttachEffect.h" />
+    <ClInclude Include="src\Interop\TechnoExt.h" />
     <ClInclude Include="src\New\Entity\Ares\RadarJammerClass.h" />
     <ClInclude Include="src\New\Type\Affiliated\CreateUnitTypeClass.h" />
     <ClInclude Include="src\Blowfish\blowfish.h" />

README.md

@@ -95,6 +95,10 @@ Credits
 
 This project was founded by [@Belonit](https://github.com/Belonit) (Gluk-v48) and [@Metadorius](https://github.com/Metadorius) (Kerbiter) in 2020, with the first public stable release in 2021. Since then it has grown into a large community project with many contributors and maintainers.
 
+### Interoperability
+
+Phobos has opened the external interfaces of some key components. If you are also developing your own engine extension and wish to use Phobos at the same time, please check out [Interop](https://github.com/Phobos-developers/Phobos/tree/develop/src/Interop).
+
 ### Maintenance crew
 
 Maintenance crew consists of experienced Phobos contributors who are recognized and given the permission to maintain and shape the project to the extent of their permissions.

docs/Whats-New.md

@@ -668,6 +668,7 @@ Fixes / interactions with other extensions:
 - Fixed the bug that vehicle survivor can spawn on wrong position when transport has been destroyed (by NetsuNegi)
 - Fixed the bug that building with `Explodes=yes` use Ares's rubble logic will cause it's owner cannot defeat normally (by NetsuNegi)
 - Fixed ares hook which stopped OpenTopped transports from firing if cloaked. This can now be customized (by RAZER & Morton)
+- [Export interface for external call](index.md#interoperability) (by TaranDahl)
 
 ```
 

docs/locale/zh_CN/LC_MESSAGES/CREDITS.po

@@ -2378,6 +2378,9 @@ msgstr "修复了 Jumpjet 单位在开始下一个任务前必须先停止移动
 msgid "Taunt warhead"
 msgstr "嘲讽弹头"
 
+msgid "Export interface for external call"
+msgstr ""
+
 msgid "**solar-III (凤九歌)**"
 msgstr "**solar-III（凤九歌）**"
 

docs/locale/zh_CN/LC_MESSAGES/Whats-New.po

@@ -2334,6 +2334,11 @@ msgid ""
 "will cause it's owner cannot defeat normally (by NetsuNegi)"
 msgstr "修复了使用 Ares 废墟逻辑的 `Explodes=yes` 建筑会导致其所有者无法正常败北的 Bug（by NetsuNegi）"
 
+msgid ""
+"[Export interface for external call](index.md#interoperability) (by "
+"TaranDahl)"
+msgstr ""
+
 msgid "0.4.0.3"
 msgstr "0.4.0.3"
 

docs/locale/zh_CN/LC_MESSAGES/index.po

@@ -384,6 +384,16 @@ msgstr ""
 "[@Metadorius](https://github.com/Metadorius)（Kerbiter）于 2020 年创立，2021 "
 "年首次发布稳定版。此后它已发展成为一个由众多贡献者和维护者组成的大型社区项目。"
 
+msgid "Interoperability"
+msgstr ""
+
+msgid ""
+"Phobos has opened the external interfaces of some key components. If you "
+"are also developing your own engine extension and wish to use Phobos at "
+"the same time, please check out [Interop](https://github.com/Phobos-"
+"developers/Phobos/tree/develop/src/Interop)."
+msgstr ""
+
 msgid "Maintenance crew"
 msgstr "维护团队"
 

src/Interop/AttachEffect.cpp

@@ -0,0 +1,109 @@
+
+#include "AttachEffect.h"
+#include "New/Entity/AttachEffectClass.h"
+#include "New/Type/AttachEffectTypeClass.h"
+
+DEFINE_EXPORT(int, AE_Attach,
+	TechnoClass* pTarget,
+	HouseClass* pInvokerHouse,
+	TechnoClass* pInvoker,
+	AbstractClass* pSource,
+	const char** effectTypeNames,
+	int typeCount,
+	int durationOverride,
+	int delay,
+	int initialDelay,
+	int recreationDelay
+)
+{
+	if (!pTarget || !effectTypeNames || typeCount <= 0)
+		return 0;
+
+	AEAttachInfoTypeClass attachInfo;
+
+	for (int i = 0; i < typeCount; i++)
+	{
+		if (effectTypeNames[i])
+		{
+			if (auto pType = AttachEffectTypeClass::Find(effectTypeNames[i]))
+				attachInfo.AttachTypes.push_back(pType);
+		}
+	}
+
+	if (attachInfo.AttachTypes.empty())
+		return 0;
+
+	if (durationOverride != 0)
+		attachInfo.DurationOverrides.push_back(durationOverride);
+
+	if (delay >= 0)
+		attachInfo.Delays.push_back(delay);
+
+	if (initialDelay >= 0)
+		attachInfo.InitialDelays.push_back(initialDelay);
+
+	if (recreationDelay >= -1)
+		attachInfo.RecreationDelays.push_back(recreationDelay);
+
+	return AttachEffectClass::Attach(pTarget, pInvokerHouse, pInvoker, pSource, attachInfo);
+}
+
+DEFINE_EXPORT(int, AE_Detach,
+	TechnoClass* pTarget,
+	const char** effectTypeNames,
+	int typeCount
+)
+{
+	if (!pTarget || !effectTypeNames || typeCount <= 0)
+		return 0;
+
+	AEAttachInfoTypeClass detachInfo;
+
+	for (int i = 0; i < typeCount; i++)
+	{
+		if (effectTypeNames[i])
+		{
+			if (auto pType = AttachEffectTypeClass::Find(effectTypeNames[i]))
+				detachInfo.RemoveTypes.push_back(pType);
+		}
+	}
+
+	if (detachInfo.RemoveTypes.empty())
+		return 0;
+
+	return AttachEffectClass::Detach(pTarget, detachInfo);
+}
+
+DEFINE_EXPORT(int, AE_DetachByGroups,
+	TechnoClass* pTarget,
+	const char** groupNames,
+	int groupCount
+)
+{
+	if (!pTarget || !groupNames || groupCount <= 0)
+		return 0;
+
+	AEAttachInfoTypeClass detachInfo;
+
+	for (int i = 0; i < groupCount; i++)
+	{
+		if (groupNames[i])
+			detachInfo.RemoveGroups.push_back(groupNames[i]);
+	}
+
+	if (detachInfo.RemoveGroups.empty())
+		return 0;
+
+	return AttachEffectClass::DetachByGroups(pTarget, detachInfo);
+}
+
+DEFINE_EXPORT(void, AE_TransferEffects,
+	TechnoClass* pSource,
+	TechnoClass* pTarget
+)
+{
+	if (!pSource || !pTarget)
+		return;
+
+	AttachEffectClass::TransferAttachedEffects(pSource, pTarget);
+}

src/Interop/AttachEffect.h

@@ -0,0 +1,58 @@
+#pragma once
+
+#include <TechnoClass.h>
+#include <HouseClass.h>
+#include <AbstractClass.h>
+// Interop exports for AttachEffect operations.
+// C# P/Invoke examples (simplified):
+// ```csharp
+// [DllImport("Phobos.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "AE_Attach")]
+// public static extern int AE_Attach(IntPtr pTarget, IntPtr pInvokerHouse, IntPtr pInvoker, IntPtr pSource, IntPtr effectTypeNames, int typeCount, int durationOverride, int delay, int initialDelay, int recreationDelay);
+//
+// [DllImport("Phobos.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "AE_Detach")]
+// public static extern int AE_Detach(IntPtr pTarget, IntPtr effectTypeNames, int typeCount);
+// ```
+
+#include "Utilities/Macro.h"
+
+/// <summary>
+/// Attaches AttachEffect instances to a target unit.
+/// </summary>
+DEFINE_EXPORT(int, AE_Attach,
+	TechnoClass* pTarget,
+	HouseClass* pInvokerHouse,
+	TechnoClass* pInvoker,
+	AbstractClass* pSource,
+	const char** effectTypeNames,
+	int typeCount,
+	int durationOverride,
+	int delay,
+	int initialDelay,
+	int recreationDelay
+);
+
+/// <summary>
+/// Removes AttachEffect instances matching given types from a unit.
+/// </summary>
+DEFINE_EXPORT(int, AE_Detach,
+	TechnoClass* pTarget,
+	const char** effectTypeNames,
+	int typeCount
+);
+
+/// <summary>
+/// Removes AttachEffect instances matching given groups from a unit.
+/// </summary>
+DEFINE_EXPORT(int, AE_DetachByGroups,
+	TechnoClass* pTarget,
+	const char** groupNames,
+	int groupCount
+);
+
+/// <summary>
+/// Transfers AttachEffect instances from one unit to another.
+/// </summary>
+DEFINE_EXPORT(void, AE_TransferEffects,
+	TechnoClass* pSource,
+	TechnoClass* pTarget
+);

src/Interop/TechnoExt.cpp

@@ -0,0 +1,7 @@
+#include "TechnoExt.h"
+#include <Ext/Techno/Body.h>
+
+DEFINE_EXPORT(bool, ConvertToType_Phobos, FootClass* pThis, TechnoTypeClass* toType)
+{
+	return TechnoExt::ConvertToType(pThis, toType);
+}

src/Interop/TechnoExt.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <TechnoTypeClass.h>
+#include <FootClass.h>
+// Interop exports for external engine extensions.
+// C# P/Invoke example:
+// ```csharp
+// [DllImport("Phobos.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "ConvertToType_Phobos")]
+// [return: MarshalAs(UnmanagedType.I1)]
+// public static extern bool ConvertToType_Phobos(IntPtr pThis, IntPtr toType);
+// ```
+// Use `IntPtr` or `unsafe` pointers in managed code. The function below exposes
+// the same signature as used internally (FootClass*, TechnoTypeClass*).
+
+#include "Utilities/Macro.h"
+
+/// <summary>
+/// Converts a unit to a different type.
+/// </summary>
+/// <param name="pThis">Pointer to the FootClass instance to convert</param>
+/// <param name="toType">Pointer to the target TechnoTypeClass</param>
+/// <returns>true if conversion was successful, false otherwise</returns>
+DEFINE_EXPORT(bool, ConvertToType_Phobos, FootClass* pThis, TechnoTypeClass* toType);

src/Utilities/Macro.h

@@ -3,6 +3,13 @@
 #include <ASMMacros.h>
 #include "Patch.h"
 
+// Export / calling-convention macros for public C ABI functions
+// 
+// Usage:
+//   DEFINE_EXPORT(return_type, Name, arglist...)
+// Expands to: PHOBOS_EXPORT return_type PHOBOS_DECL Name(arglist)
+#define DEFINE_EXPORT(ret, name, ...) extern "C" __declspec(dllexport) ret __stdcall name(__VA_ARGS__)
+
 #define GET_REGISTER_STATIC_TYPE(type, dst, reg) static type dst; _asm { mov dst, reg }
 
 template<typename T>