Interoperability

This page documents the exported interfaces in Interop.

API Convention

All exported API functions return HRESULT to indicate success or failure following COM convention:

HRESULT	Meaning
S_OK	Operation completed successfully.
S_FALSE	Operation completed but had nothing to do (e.g., no matching effects found).
E_POINTER	A required pointer parameter was null.
E_INVALIDARG	One or more arguments are invalid.
E_UNEXPECTED	An unexpected internal error occurred (e.g., extension data not found).
E_FAIL	The operation failed.

Functions that produce output data take an additional output pointer parameter that receives the result. Use SUCCEEDED(hr) / FAILED(hr) to check the return value.

API Version Tracking

Semantic Versioning Rules

• Major (X): Increment for breaking changes (backward incompatible API modifications).
  Example: Deleting an API, changing function parameters, modifying data structures that break existing code.
  When bumped, reset Minor and Patch to 0 (e.g., 1.2.3 → 2.0.0).

• Minor (Y): Increment for backward-compatible new features.
  Example: Adding a new API function, new parameters that don’t break existing code.
  When bumped, reset Patch to 0 (e.g., 1.2.3 → 1.3.0).

• Patch (Z): Increment for backward-compatible miscs (no API changes).
  Example: Fixing crashes, correcting calculations, optimizing internals without changing interface (e.g., 1.2.3 → 1.2.4).

GetInteropAPIVersion

HRESULT GetInteropAPIVersion(InteropAPIVersion* pVersion)

Returns the current Interop API version via pVersion output parameter.

• Parameters:

  • pVersion: Receives the version structure { major, minor, patch }.

• Returns S_OK on success, E_POINTER if pVersion is null.

Example (C# P/Invoke):

[StructLayout(LayoutKind.Sequential)]
public struct InteropAPIVersion
{
    public uint major;
    public uint minor;
    public uint patch;
}

[DllImport("Phobos.dll", CallingConvention = CallingConvention.StdCall)]
public static extern int GetInteropAPIVersion(out InteropAPIVersion pVersion);

InteropAPIVersion version;
int hr = GetInteropAPIVersion(out version);
if (hr >= 0 && version.major >= 1)
{
    // Safe to use features from v1.0.0 onwards
}

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 silent crash).

2. Clear messaging guides developers to the replacement API and version range.

3. Migration timeline is documented in the error message.

Example (not currently in use):

// DEPRECATED: Removed in Interop API v2.0.0. Use NewAPI instead.
// Availability: [1.0.0, 2.0.0)
// Calling this will trigger a fatal error with the message:
// "SomeOldAPI_Deprecated has been removed in Interop API v2.0.0 (was available in v1.0.0-v1.x.x). Please use NewAPI."

Available APIs

Module	API	Availability	Status
AttachEffect	AE_Attach	[1.0.0, ∞)	Active
AttachEffect	AE_Detach	[1.0.0, ∞)	Active
AttachEffect	AE_DetachByGroups	[1.0.0, ∞)	Active
AttachEffect	AE_TransferEffects	[1.0.0, ∞)	Active
BulletExt	Bullet_SetFirerOwner	[1.0.0, ∞)	Active
EventExt	EventExt_AddEvent	[1.0.0, ∞)	Active
TechnoExt	ConvertToType_Phobos	[1.0.0, ∞)	Active
TechnoExt	RegisterCalculateExtraThreatCallback	[1.0.0, ∞)	Active

AttachEffect

AE_Attach

Availability: [1.0.0, ∞)

HRESULT AE_Attach(
		TechnoClass* pTarget,
		HouseClass* pInvokerHouse,
		TechnoClass* pInvoker,
		AbstractClass* pSource,
		const char** effectTypeNames,
		int typeCount,
		int durationOverride,
		int delay,
		int initialDelay,
		int recreationDelay,
		int* pAttachedCount
)

Attaches one or more AttachEffect types to the target.

• 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.

  • pAttachedCount: Receives the number of effects attached.

• Returns S_OK on success, S_FALSE if no valid effect type names were found.

• Fails with E_POINTER when: pTarget, effectTypeNames, or pAttachedCount is null.

• Fails with E_INVALIDARG when: typeCount <= 0.

AE_Detach

Availability: [1.0.0, ∞)

HRESULT AE_Detach(
		TechnoClass* pTarget,
		const char** effectTypeNames,
		int typeCount,
		int* pRemovedCount
)

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.

  • pRemovedCount: Receives the number of effects removed.

• Returns S_OK on success, S_FALSE if no matching effects were found.

• Fails with E_POINTER when: pTarget, effectTypeNames, or pRemovedCount is null.

• Fails with E_INVALIDARG when: typeCount <= 0.

AE_DetachByGroups

Availability: [1.0.0, ∞)

HRESULT AE_DetachByGroups(
		TechnoClass* pTarget,
		const char** groupNames,
		int groupCount,
		int* pRemovedCount
)

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.

  • pRemovedCount: Receives the number of effects removed.

• Returns S_OK on success, S_FALSE if no matching groups were found.

• Fails with E_POINTER when: pTarget, groupNames, or pRemovedCount is null.

• Fails with E_INVALIDARG when: groupCount <= 0.

AE_TransferEffects

Availability: [1.0.0, ∞)

HRESULT AE_TransferEffects(
		TechnoClass* pSource,
		TechnoClass* pTarget
)

Transfers all attached effects from source to target.

• Parameters:

  • pSource: Source unit.

  • pTarget: Target unit.

• Returns S_OK on success.

• Fails with E_POINTER when: pSource or pTarget is null.

Vanilla class extension

TechnoExt

ConvertToType_Phobos

Availability: [1.0.0, ∞)

HRESULT ConvertToType_Phobos(FootClass* pThis, TechnoTypeClass* toType)

Converts a FootClass instance to another TechnoType.

• Parameters:

  • pThis: Unit to convert.

  • toType: Destination TechnoType.

• Returns S_OK if conversion succeeds.

• Returns E_INVALIDARG if types are incompatible.

• Notes:

  • This API forwards directly to TechnoExt::ConvertToType.

RegisterCalculateExtraThreatCallback

Availability: [1.0.0, ∞)

typedef double (*CalculateExtraThreatCallback)(TechnoClass* pThis, ObjectClass* pTarget, double originalThreat);

HRESULT RegisterCalculateExtraThreatCallback(CalculateExtraThreatCallback callback)

Registers a callback function to calculate extra threat for a unit.

• Parameters:

  • callback: Callback function pointer that returns the calculated threat modifier. Signature: double callback(TechnoClass* pThis, ObjectClass* pTarget, double originalThreat).

• Returns S_OK on success.

• Fails with E_POINTER when: callback is null.

• Behavior:

  • If callback is non-null, it is added to the internal callback list.

  • When threat calculations occur, all registered callbacks are invoked to compute additional threat contributions.

  • Multiple callbacks can be registered and are executed in registration order.

• Notes:

  • The callback invocation method is totalThreat = cb(pThis, pTarget, totalThreat).

BulletExt

Bullet_SetFirerOwner

Availability: [1.0.0, ∞)

HRESULT 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).

• Returns S_OK if the bullet extension is found and updated.

• Fails with E_POINTER when: pBullet is null.

• Fails with E_UNEXPECTED when: no BulletExt entry exists for pBullet.

EventExt

EventExt_AddEvent

Availability: [1.0.0, ∞)

HRESULT EventExt_AddEvent(EventExt* pEventExt)

Invokes AddEvent on an EventExt object.

• Parameters:

  • pEventExt: Event extension instance.

• Returns S_OK if AddEvent succeeds, S_FALSE if AddEvent returns false.

• Fails with E_POINTER when: pEventExt is null.