Skip to main content

Core, discovery, and consumers

These calls establish the connection and owner identity used by every other stateful API family. They are not callback-only.

RockProviderApi::initialize​

static int initialize(
    std::uint32_t minVersion = ROCK_PROVIDER_API_VERSION,
    std::uint32_t minProviderApiByteSize = 0);

Finds the loaded ROCK.dll, prefers its safe V1 descriptor, validates minimum version and table extent, and sets the process-local static fields:

  • RockProviderApi::inst;
  • negotiatedApiVersion;
  • negotiatedTableByteSize;
  • negotiatedFeatureBits;
  • negotiatedFeatureBits2.

Returns codes 0 through 6 documented in Install and build. Pass a non-zero byte constant for every new integration.

ROCKAPI_GetDescriptorV1​

const RockProviderApiDescriptorV1* ROCK_PROVIDER_CALL
ROCKAPI_GetDescriptorV1();

Preferred DLL export. Returns an immutable, export-owned descriptor containing the exact table byte size, both feature words, API version, and table pointer. The returned descriptor/table live for the process lifetime; consumers must not modify either.

Normal code should use initialize, which validates the descriptor before touching its table pointer.

ROCKAPI_GetProviderApi​

const RockProviderApi* ROCK_PROVIDER_CALL ROCKAPI_GetProviderApi();

Legacy direct table accessor. It carries no independent extent metadata. It is retained for old V1 consumers; new consumers that use appended slots should use descriptor-first initialization.

ROCKAPI_GetApi​

const rock::api::ROCKApi* ROCK_PROVIDER_CALL ROCKAPI_GetApi();

Compatibility alias declared by ROCKApi.h. It returns the same function table as ROCKAPI_GetProviderApi; it is not a second API family.

getVersion · slot 0​

std::uint32_t getVersion();

Returns ROCK_PROVIDER_API_VERSION, currently 1. This identifies the contract family only. Because pre-launch V1 is append-only, still check table extent and feature bits.

getModVersion · slot 1​

const char* getModVersion();

Returns a ROCK-owned, process-lifetime diagnostic string (currently "0.5.0"). Display or log it; do not parse it to discover API features.

isProviderReady · slot 2​

bool isProviderReady();

Returns whether ROCK's live interaction provider currently exists and is initialized. It can become false during provider loss or shutdown after the table was successfully acquired.

For coherent per-frame decisions, prefer ProviderReady in RockProviderFrameSnapshot::lifecycleFlags together with the relevant physics or visual write flag.

registerConsumerV1 · slot 18​

RockProviderResultV1 registerConsumerV1(
    const RockProviderConsumerRegistrationV1* registration,
    RockProviderConsumerHandleV1* outHandle);

Registers one unique mod name and returns a ROCK-issued owner token.

Input requirements:

  • both pointers are non-null;
  • both structures have the exact current public size;
  • registration.version is 1;
  • modName is non-empty and null-terminated within 64 bytes;
  • at most 64 consumers are registered;
  • the name is not already registered.

requestedCapabilities is masked to implemented capabilities. A successful call can therefore return a partial grant. Always compare outHandle.grantedCapabilities with the complete mask your feature requires.

Returns Ok, InvalidArgument, InvalidSize, UnsupportedVersion, OwnerConflict, or CapacityFull.

The handle also reports the provider generation current at registration. Use current frame generations for later guarded work; do not assume the registration generation remains current forever.

unregisterConsumerV1 · slot 19​

RockProviderResultV1 unregisterConsumerV1(std::uint64_t ownerToken);

Invalidates the owner and clears every owner-bound callback, command, suppression, part target/drive, body/scope, reservation, authority, runtime publication, handling policy, overlay/collider focus, and touch-target scope.

Returns:

  • Ok when cleanup completed;
  • InvalidArgument for token 0;
  • OwnerNotRegistered for an unknown or already removed token.

Call explicit family clear/release operations during normal feature shutdown when useful, then call this once during plugin shutdown. See the callback in-flight caveat in the runtime contract.

getGrantedCapabilitiesV1 · slot 20​

std::uint32_t getGrantedCapabilitiesV1(std::uint64_t ownerToken);

Returns the owner's current capability mask. Returns 0 for an unknown token; there is no distinct error channel. The registration handle is normally the best place to perform the initial exact-grant check.

getProviderLimitsV1 · slot 21​

bool getProviderLimitsV1(RockProviderLimitsV1* outLimits);

Copies the compatible base limit prefix. The caller's size must reach at least through featureBits. ROCK copies min(callerSize, providerSize), then writes the copied byte count back to size.

Use it for primary feature bits and older capacities. Prefer the header helper:

RockProviderLimitsV1 limits{};
if (!queryProviderLimitsV1(limits)) {
    return false;
}

getProviderLimitsExtV1 · slot 54​

bool getProviderLimitsExtV1(RockProviderLimitsExtV1* outLimits);

Copies the complete prefix-compatible capacity contract, including both feature words and maxima for all registries, rings, arrays, and leases. The caller's size must reach through featureBits2; the copied prefix size is returned in size.

Use queryProviderLimitsExtV1 or supportsExtendedLimitsV1 before direct use. Do not hardcode capacities when the returned limit controls an allocation or poll batch.

Important current maxima include 64 consumers, 16 frame callbacks, 2,048 external bodies, 256 child scopes, 512 retained external contacts, 32 queued commands, 256 provider events, 128 part targets, 64 part drives, and 120-frame leases for most rolling publications. It also publishes 256 touch targets in 64 scopes and eight world raycasts per owner per frame. The returned structure is authoritative.

getPublicStructureSizeV1 · slot 55​

std::uint32_t getPublicStructureSizeV1(
    RockProviderStructureIdV1 structureId);

Returns ROCK's exact compiled byte size for any of the 66 public structure IDs. Returns 0 for an unknown ID.

Use this for ABI diagnostics, header-sync tests, or a clear compatibility log:

const auto remoteSize = RockProviderApi::inst->getPublicStructureSizeV1(
    RockProviderStructureIdV1::ScopeSightState);

if (remoteSize != sizeof(RockProviderScopeSightStateV1)) {
    // Report the header mismatch and disable this family.
}

Do not use a returned size to reinterpret a structure layout your header does not define.

Discovery helper reference​

bool queryProviderLimitsV1(RockProviderLimitsV1& out);
bool queryProviderLimitsExtV1(RockProviderLimitsExtV1& out);

bool providerApiTableSupportsV1(
    const RockProviderLimitsV1& limits,
    std::uint32_t requiredByteSize);
bool providerApiTableSupportsV1(std::uint32_t requiredByteSize);

bool providerSupportsFeature2V1(
    std::uint32_t requiredByteSize,
    RockProviderFeatureBit2V1 feature);

The query helpers check instance, table extent, and function pointer before calling. providerApiTableSupportsV1 uses negotiated descriptor bytes when available and base limits for legacy fallback. providerSupportsFeature2V1 requires both table extent and the extended feature bit.

See Discovery and capabilities for the complete named helper list and capability map.