Skip to content

Interoperability.md

Latest commit

 

History

History
285 lines (214 loc) · 9.5 KB

Interoperability.md

File metadata and controls

285 lines (214 loc) · 9.5 KB
Raw

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.