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

@@ -741,6 +741,7 @@ This page lists all the individual contributions to the project by their author.
   - Extra threat
   - Fix the incorrect mission switching in infantry EnterIdleMode
   - Fix the issue that `BombSight` not being updated correctly in techno conversion
+  - 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](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

@@ -695,6 +695,7 @@ Fixes / interactions with other extensions:
 - Fixed a bug where passengers created by the InitialPayload logic or TeamType with `Full=true` would fail to fire when the transport unit with `OpenTopped=yes` moved to an area that the passengers' `MovementZone` cannot move into (by NetsuNegi)
 - Fixed a bug where game will crash after loading if a techno with `AlphaImage` converts to a type without it, or an anim with `AlphaImage` changes to a type without it through `Next` (by NetsuNegi & FlyStar)
 - Fixed the issue that `BombSight` not being updated correctly in techno conversion (by TaranDahl)
+- [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

@@ -2454,6 +2454,9 @@ msgstr "修复了非超时空矿车在矿区无矿后即便矿石已重新生成
 msgid "Miners back to work when ore regenerated"
 msgstr "矿车在矿石再生后返回工作"
 
+msgid "Export interface for external call"
+msgstr "用于外部调用的导出接口"
+
 msgid "Allow disable an over-optimization in targeting"
 msgstr "允许禁用索敌中的过度优化"
 

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

@@ -2476,6 +2476,10 @@ msgstr ""
 "`预装载小队` 的作战小队创建的乘客无法开火的 Bug（by NetsuNegi）"
 
 msgid ""
+"[Export interface for external call](index.md#interoperability) (by "
+"TaranDahl)"
+msgstr "用于外部调用的导出接口（by TaranDahl）"
+
 "Fixed a bug where if a techno converts from type has `AlphaImage` to "
 "non `AlphaImage` type, game will crash after load (by NetsuNegi)"
 msgstr ""

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 "维护团队"
 

src/Ext/Techno/Body.h

@@ -1,4 +1,4 @@
-#pragma once
+#pragma once
 
 #include <Ext/TechnoType/Body.h>
 #include <Utilities/Container.h>

src/Ext/Techno/Hooks.TargetEvaluation.cpp

@@ -1,4 +1,5 @@
 #include "Body.h"
+#include "Interop/TechnoExt.h"
 
 // Cursor & target acquisition stuff not directly tied to other features can go here.
 
@@ -506,6 +507,11 @@ DEFINE_HOOK(0x70CF87, TechnoClass_ThreatCoefficient_CanAttackMeThreatBonus, 0x9)
 		};
 	ApplyLastTargetDistanceBonus();
 
+	for (auto const& cb : TechnoExtInterop::CalculateExtraThreatCallbacks)
+	{
+		totalThreat = cb(pThis, pTarget, totalThreat);
+	}
+
 	return 0;
 }