Export interface for external call

.github/copilot-instructions.md

@@ -271,6 +271,69 @@ When the type or function you need is missing or incorrect in YRpp, add or fix i
 
 **Important:** Always push your YRpp branch *before* pushing the Phobos commit that references it, otherwise CI cannot resolve the submodule.
 
+### Interop API design
+
+#### Key macros
+
+Interop exports are declared in `src/Interop/*.h` using macros from `src/Utilities/Macro.h`:
+
+| Macro | Purpose | Notes |
+|---|---|---|
+| `DEFINE_CALLBACK(returnType, FuncName, params...)` | Declares a callback type. Callbacks are chain-able (each receives previous result) and stored in a static `std::vector`. Use null-checks when invoking. | Declare in header, initialize in `.cpp` |
+| `DEFINE_EXPORT(returnType, FuncName, params...)` | Exports a C function for P/Invoke. Signature: `extern "C" __declspec(dllexport)`. Use `_Phobos` suffix to avoid naming collisions with Ares. | See `src/Interop/TechnoExt.h/cpp` for examples |
+
+#### Interop API version management
+
+Interop API versions are defined in `src/Interop/Version.h` and follow **Semantic Versioning 2.0.0** (see https://semver.org/):
+
+| Version Component | Increment When | Example |
+|---|---|---|
+| **Major** | Breaking change (backward incompatible). Existing external code **will not work** without modification. | Changing callback signature: `double f(int a)` → `double f(int a, int b)` |
+| **Minor** | New backward-compatible feature added. External code continues to work without change. | Adding a new `DEFINE_EXPORT` function or new callback type. |
+| **Patch** | Backward-compatible bug fix only. No API changes. | Fixing a logic error in an exported function implementation. |
+
+**Version constants in `Version.h`:**
+```cpp
+#define INTEROP_API_VERSION_MAJOR 1
+#define INTEROP_API_VERSION_MINOR 2
+#define INTEROP_API_VERSION_PATCH 0
+```
+
+**When to increment:**
+
+- **MAJOR bump** (1.0.0 → 2.0.0):
+  - Change callback/function signature (parameter type, return type, count).
+  - Remove or rename a callback/export.
+  - Change callback return value semantics (e.g., return value now used differently).
+
+- **MINOR bump** (1.0.0 → 1.1.0):
+  - Add a new callback type and its registration function.
+  - Add a new `DEFINE_EXPORT` function.
+  - Extend callback behavior with new optional parameters (if backward compatible).
+
+- **PATCH bump** (1.0.0 → 1.0.1):
+  - Fix a bug in an exported function's implementation.
+  - Clarify documentation/comments.
+  - No API signature changes.
+
+**Example workflow:**
+
+1. You add `DEFINE_EXPORT(void, NewFeature_Phobos, ...)` - this is a new feature → **MINOR** bump (1.0.0 → 1.1.0).
+2. You change the signature of an existing callback from `int f(ptr)` to `int f(ptr, int extra)` → **MAJOR** bump (1.1.0 → 2.0.0).
+3. You fix a logic bug in `ConvertToType_Phobos` without changing its signature → **PATCH** bump (2.0.0 → 2.0.1).
+
+**Deprecated APIs:**
+
+When an exported function or callback becomes obsolete but must remain for compatibility, keep its stub but document it with a version range and deprecation note:
+
+```cpp
+/// <summary>
+/// DEPRECATED: Use RegisterCalculateSightCallback_Phobos (available since 1.1.0).
+/// This function will be removed in version 3.0.0.
+/// </summary>
+DEFINE_EXPORT(void, RegisterSightModifier_Phobos, OldCallbackType callback);  // Removed in 3.0.0
+```
+
 ## Code Style (enforced by .editorconfig)
 
 - **Tabs** for indentation (size 4).

.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
@@ -87,3 +88,35 @@ jobs:
             echo "Please, document your changes or use [No Documentation Needed] label for your Pull Request."
             exit 1
           fi
+
+  Interop-Version-Check:
+    name: Interop API Version Updated
+    # If the No Documentation Needed label is set, then workflow will not be executed
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'No Documentation Needed') }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+            fetch-depth: 0
+      - name: Check that Interop API version is updated
+        run: |
+          # Check if any files in src/Interop/ were modified (excluding Version.h itself for initial checks)
+          CHANGED_FILES=$(git diff --name-only $(git merge-base origin/$BASE_BRANCH HEAD))
+          INTEROP_MODIFIED=$(echo "$CHANGED_FILES" | grep -E "^src/Interop/.*\.(h|cpp)$" | grep -v "^src/Interop/Version\." || true)
+
+          if [ -z "$INTEROP_MODIFIED" ]; then
+            echo "No Interop files modified. Skipping version check."
+            exit 0
+          fi
+
+          # If Interop files were modified, check if Version.h was also modified
+          if echo "$CHANGED_FILES" | grep -q "^src/Interop/Version\.h$"; then
+            echo "Thank you for updating the Interop API version! 😋"
+            exit 0
+          else
+            echo "You modified Interop API but forgot to update the version! 🧐"
+            echo "Please update the version constants in 'src/Interop/Version.h' according to Semantic Versioning."
+            echo "See .github/copilot-instructions.md for version bumping guidelines."
+            exit 1
+          fi

.gitignore

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

CREDITS.md

@@ -749,6 +749,7 @@ This page lists all the individual contributions to the project by their author.
   - Allow replacing vanilla repairing with togglable auto repairing
   - Fix an issue that the time for units in the area guard mission to reacquire targets after eliminating the target is significantly longer than that in other missions
   - Framework for dynamic sight
+  - Export interface for external call
 - **solar-III (凤九歌)**
   - Target scanning delay customization (documentation)
   - Skip target scanning function calling for unarmed technos (documentation)

Phobos.vcxproj

@@ -32,6 +32,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" />
@@ -225,6 +230,11 @@
     <ClInclude Include="src\Commands\DeselectObject.h" />
     <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,7 @@ 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!
+
+### API versioning
+
+See [Interoperability](Interoperability.md#api-version-tracking).