Export interface for external call

.github/workflows/pr-doc-checker.yml

@@ -77,6 +77,7 @@ jobs:
               -e ^docs/Fixed-or-Improved-Logics.md$ \
               -e ^docs/AI-Scripting-and-Mapping.md$ \
               -e ^docs/User-Interface.md$           \
+              -e ^docs/Interoperability.md$         \
               -e ^docs/Miscellanous.md$             \
           )
           then

.gitignore

@@ -27,3 +27,5 @@ out
 
 # Python virtual environment for docs
 .venv/
+
+debug.log

CREDITS.md

@@ -730,6 +730,7 @@ This page lists all the individual contributions to the project by their author.
   - Fix the issue that the Jumpjet must end its movement before starting the next mission
   - Taunt warhead
   - Fix the bug where non-Teleporter miners would not return to work after minerals are depleted and then regenerated
+  - 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,11 @@
     <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\BulletExt.cpp" />
+    <ClCompile Include="src\Interop\EventExt.cpp" />
+    <ClCompile Include="src\Interop\TechnoExt.cpp" />
+    <ClCompile Include="src\Interop\Version.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 +226,11 @@
   <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\BulletExt.h" />
+    <ClInclude Include="src\Interop\EventExt.h" />
+    <ClInclude Include="src\Interop\TechnoExt.h" />
+    <ClInclude Include="src\Interop\Version.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 [Interoperability](/docs/Interoperability.md).
+
 ### 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/General-Info.md

@@ -28,3 +28,12 @@ Phobos fully supports saving and loading thanks to prototype code from publicly
 While Phobos is standalone, it is designed to be used alongside [Ares](https://ares.strategy-x.com) and [CnCNet5 spawner](https://github.com/CnCNet/cncnet-for-ares). Adding new features or improving existing ones is done with compatibility with those in mind.
 
 While we would also like to support HAres we can't guarantee compatibility with it due to the separation of it's userbase and developers from international community. We welcome any help on the matter though!
+
+### Interop API Compatibility
+
+Phobos exports a set of C/C++ interop functions for external tools and mod loaders (see [Interoperability](Interoperability.md#api-version-tracking)).
+
+- **Version discovery:** External code should call `GetInteropBuildNumber()` before relying on specific API features.
+- **API lifecycle:** All exported APIs are labeled with their availability range [startBuild, endBuild) in the Interoperability documentation.
+- **Deprecated APIs:** When an API is deprecated, its function stub remains but calling it triggers a fatal error with a clear message. This ensures broken integrations fail fast with actionable guidance.
+- **Recommended usage:** Check the API availability table in [Interoperability](Interoperability.md#api-availability-table) to ensure your target API is supported in the Phobos build you're using.

docs/Interoperability.md

@@ -0,0 +1,234 @@
+
+# Interoperability
+
+This page documents the exported interfaces in [Interop](https://github.com/Phobos-developers/Phobos/tree/develop/src/Interop).
+
+## API Version Tracking
+
+Phobos tracks Interop API versions using build numbers. Each exported API is labeled with its availability range:
+- **[startBuild, endBuild)**: API is available from build `startBuild` up to (but not including) build `endBuild`.
+- **[startBuild, ∞)**: API is still active and has no planned removal date.
+
+### GetInteropBuildNumber
+
+```cpp
+unsigned int GetInteropBuildNumber()
+```
+
+Returns the current Phobos Interop build number. Use this to detect which APIs are available.
+
+**Availability:** [48, ∞)
+
+### Deprecated API Handling
+
+When an API is deprecated, its function stub is retained but with a fatal error handler. The calling application will receive a descriptive error message and must stop execution. This ensures:
+1. Broken links are immediately detected at runtime (not a crash).
+2. Clear messaging guides developers to the replacement API.
+3. Migration timeline is documented in the error message.
+
+**Example** (not currently in use):
+
+```cpp
+// DEPRECATED: Removed after build 52. Use NewAPI instead.
+// Calling this will trigger a fatal error with the message:
+// "SomeOldAPI_Deprecated has been removed (was available until build 52). Please use NewAPI."
+```
+
+### API Availability Table
+
+| API | Signature | Availability | Notes |
+|-----|-----------|---------------|-------|
+| AE_Attach | `int AE_Attach(...)` | [48, ∞) | Still active |
+| AE_Detach | `int AE_Detach(...)` | [48, ∞) | Still active |
+| AE_DetachByGroups | `int AE_DetachByGroups(...)` | [48, ∞) | Still active |
+| AE_TransferEffects | `void AE_TransferEffects(...)` | [48, ∞) | Still active |
+| ConvertToType_Phobos | `bool ConvertToType_Phobos(...)` | [48, ∞) | Still active |
+| Bullet_SetFirerOwner | `bool Bullet_SetFirerOwner(...)` | [48, ∞) | Still active |
+| EventExt_AddEvent | `bool EventExt_AddEvent(...)` | [48, ∞) | Still active |
+
+## New type and entity
+
+### AttachEffect
+
+AttachEffect interop APIs allow external code to attach, detach, and transfer attach effects on units.
+
+#### AE_Attach
+
+```cpp
+int AE_Attach(
+		TechnoClass* pTarget,
+		HouseClass* pInvokerHouse,
+		TechnoClass* pInvoker,
+		AbstractClass* pSource,
+		const char** effectTypeNames,
+		int typeCount,
+		int durationOverride,
+		int delay,
+		int initialDelay,
+		int recreationDelay
+)
+```
+
+Attaches one or more AttachEffect types to the target.
+
+**Availability:** [48, ∞)
+
+- Parameters:
+	- pTarget: Target unit to receive effects.
+	- pInvokerHouse: Invoker house context.
+	- pInvoker: Invoker techno context.
+	- pSource: Optional source object context.
+	- effectTypeNames: Array of AttachEffect type names.
+	- typeCount: Number of entries in effectTypeNames.
+	- durationOverride: If non-zero, duration override is applied.
+	- delay: If >= 0, delay override is applied.
+	- initialDelay: If >= 0, initial delay override is applied.
+	- recreationDelay: If >= -1, recreation delay override is applied.
+- Returns:
+	- > 0 on success (value returned by internal attach routine).
+	- 0 on failure.
+- Fails when:
+	- pTarget is null.
+	- effectTypeNames is null.
+	- typeCount <= 0.
+	- No valid effect type name resolves to an existing AttachEffectType.
+
+#### AE_Detach
+
+```cpp
+int AE_Detach(
+		TechnoClass* pTarget,
+		const char** effectTypeNames,
+		int typeCount
+)
+```
+
+Detaches effects by explicit effect type names.
+
+- Parameters:
+	- pTarget: Target unit to remove effects from.
+	- effectTypeNames: Array of AttachEffect type names to remove.
+	- typeCount: Number of entries in effectTypeNames.
+**Availability:** [48, ∞)
+- Returns:
+	- > 0 on success (value returned by internal detach routine).
+	- 0 on failure.
+- Fails when:
+	- pTarget is null.
+	- effectTypeNames is null.
+	- typeCount <= 0.
+	- No valid effect type name resolves to an existing AttachEffectType.
+
+#### AE_DetachByGroups
+
+```cpp
+int AE_DetachByGroups(
+		TechnoClass* pTarget,
+		const char** groupNames,
+		int groupCount
+)
+```
+
+Detaches effects by AttachEffect group name.
+
+- Parameters:
+	- pTarget: Target unit to remove effects from.
+	- groupNames: Array of group names.
+	- groupCount: Number of entries in groupNames.
+**Availability:** [48, ∞)
+- Returns:
+	- > 0 on success (value returned by internal detach-by-group routine).
+	- 0 on failure.
+- Fails when:
+	- pTarget is null.
+	- groupNames is null.
+	- groupCount <= 0.
+	- groupNames contains no non-null entries.
+
+#### AE_TransferEffects
+
+```cpp
+void AE_TransferEffects(
+		TechnoClass* pSource,
+		TechnoClass* pTarget
+)
+```
+
+Transfers all attached effects from source to target.
+
+- Parameters:
+	- pSource: Source unit.
+	- pTarget: Target unit.
+
+**Availability:** [48, ∞)
+
+- Behavior:
+	- No operation if pSource or pTarget is null.
+
+## Vanilla class extension
+
+### TechnoExt
+
+#### ConvertToType_Phobos
+
+```cpp
+bool ConvertToType_Phobos(FootClass* pThis, TechnoTypeClass* toType)
+```
+
+Converts a FootClass instance to another TechnoType.
+
+- Parameters:
+	- pThis: Unit to convert.
+	- toType: Destination TechnoType.
+
+**Availability:** [48, ∞)
+
+- Returns:
+	- true if conversion succeeds.
+	- false if conversion fails.
+- Notes:
+	- This API forwards directly to TechnoExt::ConvertToType.
+
+### BulletExt
+
+#### Bullet_SetFirerOwner
+
+```cpp
+bool Bullet_SetFirerOwner(BulletClass* pBullet, HouseClass* pHouse)
+```
+
+Updates the recorded firer house for a bullet extension.
+
+- Parameters:
+	- pBullet: Bullet instance.
+	- pHouse: New firer house (can be null if caller intentionally clears ownership).
+
+**Availability:** [48, ∞)
+
+- Returns:
+	- true if the bullet extension is found and updated.
+	- false on failure.
+- Fails when:
+	- pBullet is null.
+	- No BulletExt entry exists for pBullet.
+
+### EventExt
+
+#### EventExt_AddEvent
+
+```cpp
+bool EventExt_AddEvent(EventExt* pEventExt)
+```
+
+Invokes AddEvent on an EventExt object.
+
+- Parameters:
+	- pEventExt: Event extension instance.
+
+**Availability:** [48, ∞)
+
+- Returns:
+	- false if pEventExt is null.
+	- Otherwise, returns the result of pEventExt->AddEvent().
+
+

docs/Whats-New.md

@@ -683,6 +683,8 @@ Fixes / interactions with other extensions:
 - Fixed an Ares bug that led to erroneous interactions where the parasite would frequently reset to the victim's position under specific circumstances and that was highly prone to crashes (by NetsuNegi)
 - Fixed the initial direction of building placed by Ares's UnitDelivery superweapon (by NetsuNegi)
 - Fixed the bug where non-Teleporter miners would not return to work after minerals are depleted and then regenerated (by TaranDahl)
+- 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/index.md

@@ -16,6 +16,7 @@ New / Enhanced Logics<New-or-Enhanced-Logics.md>
 Fixed / Improved Logics<Fixed-or-Improved-Logics.md>
 AI Scripting and Mapping<AI-Scripting-and-Mapping.md>
 User Interface<User-Interface.md>
+Interoperability<Interoperability.md>
 Miscellanous<Miscellanous.md>
 ```
 

docs/locale/zh_CN/LC_MESSAGES/CREDITS.po

@@ -2422,6 +2422,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

@@ -2408,6 +2408,11 @@ msgid ""
 "Fixed the initial direction of building placed by Ares's UnitDelivery superweapon (by NetsuNegi)"
 msgstr "修复了 Ares 的单位投放超级武器投放的建筑物的初始朝向（by NetsuNegi）"
 
+msgid ""
+"[Export interface for external call](index.md#interoperability) (by "
+"TaranDahl)"
+msgstr "用于外部调用的导出接口（by TaranDahl）"
+
 msgid "0.4.0.3"
 msgstr "0.4.0.3"
 

docs/locale/zh_CN/LC_MESSAGES/index.po

@@ -384,6 +384,17 @@ 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 "Phobos为一些关键组件打开了外部接口。如果你也在开发自己的引擎扩展并且希望同时使用Phobos，"
+"请查阅[Interop](https://github.com/Phobos-developers/Phobos/tree/develop/src/Interop)。"
+
 msgid "Maintenance crew"
 msgstr "维护团队"