Types, flags, results, and limits

The SDK is a C-compatible, x64 function-table ABI presented through a C++ header. V1 currently contains 90 function pointers (720 bytes). Public structures are standard-layout, trivially copyable value types; function pointers use __cdecl. Initialize output structures with {} so their default size, version, sentinels, and reserved bytes are correct.

RockProviderHandInteractionStateV1 state{}; // correct
// Do not memset a previously versioned object and then forget size/version.

RockProviderResultV1

Every result-returning call uses the same stable values.

Result	Meaning / consumer response
Ok	The operation completed.
NotReady	ROCK or the requested subsystem is temporarily unavailable. Wait for lifecycle readiness.
InvalidArgument	Token, pointer, enum, flags, data, or combination is invalid. Fix the request; do not retry unchanged.
InvalidSize	A fixed-size structure did not match the provider's current size requirement.
UnsupportedVersion	A structure version is zero or newer than the provider supports.
CapacityFull	A fixed provider pool cannot admit the operation. Reduce rows or release state.
OwnerNotRegistered	The owner token is absent/stale. Register again only after reacquiring the API.
OwnerConflict	Another owner holds an exclusive resource, or the caller tried to clear another owner.
PermissionDenied	The required capability was not granted. Disable that feature.
WorldNotReady	The game world required by the operation is unavailable.
TargetInvalid	Target identity is malformed or unsuitable.
TargetUnavailable	The target/resource was valid in principle but does not currently exist or cannot be used.
HandUnavailable	The requested physical hand is invalid or unavailable.
HandBusy	Another current interaction prevents the request.
ObjectAlreadyOwned	The object already has incompatible ownership.
RequestQueued	The provider accepted an asynchronous command for later processing.
RequestNotFound	The command ID is unknown, expired, or not owned by the caller.
WrongThread	A live/callback-only operation was called outside ROCK's game-thread boundary.
AlreadyCommitted	A command crossed its cancellation boundary and can no longer be cancelled.

Do not collapse these into a Boolean. NotReady can be retried after state changes; PermissionDenied requires a feature downgrade; InvalidArgument requires a code fix; OwnerConflict requires respecting another owner.

Identity and sentinel rules

Value	Meaning
RockProviderHand::Right / Left	Physical controller identity, independent of primary/offhand role.
RockProviderHand::None	No hand; accepted only by APIs that explicitly document it.
body ID 0x7FFF'FFFF	Invalid/unavailable body identity.
form ID 0	No resolved Bethesda form.
owner/callback/command/scope token 0	Invalid token.
generation 0 in a request guard	Wildcard: do not constrain that generation.
pointer-sized field 0	No current identity witness.

Pointer-sized fields such as node, sourceRoot, interactionRoot, and weaponNode are non-owning identity witnesses. Never dereference them through the SDK and never retain them across a frame or generation change.

Transforms and coordinates

RockProviderTransform contains a row-major 3×3 rotation, three-value translation, and uniform scale. The structure alone does not define its space; the field name or associated enum does:

• game/world fields use Fallout game units;
• weaponRootLocal is local to the equipped weapon root;
• sourceParentLocal is local to the source node's parent;
• hand-in-weapon values are weapon-local;
• external-contact vectors explicitly named Havok use Havok space.

RockProviderPoint3 and RockProviderBounds3 are game-space value helpers. Optional vectors and transforms always have an accompanying validity field or flag. Zero is a legitimate coordinate and is not a validity signal.

Flag handling

Most public flags fields store an integer bitmask even when the named bits are an enum class. Use the supplied helpers where available:

if (hasLifecycleFlag(frame.lifecycleFlags,
        RockProviderLifecycleFlag::PhysicsWriteAllowed)) {
    // Safe to consider a write operation.
}

if (hasConsumerCapabilityV1(handle.grantedCapabilities,
        RockProviderConsumerCapabilityV1::ProviderEvents)) {
    // The owner may use the provider-event stream.
}

Header helpers include hasLifecycleFlag, hasConsumerCapabilityV1, hasFeatureBitV1, hasFeatureBit2V1, hasHandInputSuppressionFlagV1, hasWeaponPartTargetFlagV1, hasWeaponKeywordFlagV1, hasNativeAnimationAuthorityFlagV1, and hasEquippedWeaponHandlingFlagV1.

The two advertised feature-mask families are RockProviderFeatureBitV1 and RockProviderFeatureBit2V1. They describe provider implementation support; they do not replace owner capability grants.

Unknown bits must not be sent to a setter. On readback, ignore unknown bits so future compatible providers can enrich a mask without breaking your consumer.

Public limits

Read limits from getProviderLimitsV1/getProviderLimitsExtV1 at runtime. The header constants provide compile-time storage ceilings for this SDK snapshot.

Resource	Current V1 maximum
Consumers	64
Owner frame callbacks	16
Animation phase callbacks	16
Compact frame weapon body IDs	8
Complete weapon evidence details	100
Points per evidence detail	252
External bodies	2,048
External child scopes	256
External contact records	512
Body contacts	128
Queued interaction commands	32
Retained completed commands	64
Input-suppression owners	32
Weapon-part targets / drives	128 / 64
Weapon emitters	32
Provider events	256
Weapon composition entries	64
Semantic hand contacts	20
Player collider descriptors	96
Weapon-part poses / drive results	128 / 64
Held body IDs per hand state	8
Finger-local transforms per hand	15 (0x7FFF full mask)
Touch targets / scopes	256 / 64
World raycasts per owner per frame	8
World raycast distance	8,192 game units

Lease maxima are 120 frames for input suppression, part drives, hand visuals, native-runtime publication, equipped handling, debug overlay, and offhand reservation, touch targets, and collider focus. Native animation authority alone permits up to 1,200 frames.

Enum catalogue

The behavior-focused pages explain these values in context. This catalogue makes every public family discoverable.

Runtime, hands, and body

Type	Values
RockProviderHand	None, Right, Left
RockProviderHandStateFlag	Touching, Holding, PhysicsDisabled
RockProviderHandFrameFlagV1	Valid, Left, Primary, Offhand, HasSceneNode, RootFlattenedAuthority, PresentedVisual
RockProviderLifecycleFlag	WorldAvailable, SkeletonReady, ProviderReady, MenuBlocking, ConfigBlocking, LoadingOrWorldTransition, GeneratedBodiesValid, PhysicsWriteAllowed, VisualWriteAllowed
RockProviderLifecycleReason	None, GameLoaded, SkeletonReady, SkeletonDestroying, PowerArmorChanged, WorldAvailable, WorldChanged, WorldUnavailable, ProviderReady, ProviderLost, MenuBlocked, ConfigBlocked, GeneratedBodiesRebuilt, GeneratedBodiesInvalidated, TransitionSettled, Shutdown
RockProviderBodyZoneSide	Center, Left, Right
RockProviderBodyZoneKind	pelvis, spine, chest, neck/head, left/right shoulder, upper arm, forearm, hand, hip, thigh, calf, and foot zones
RockProviderBodyContactTargetKind	Unknown, Hand, Weapon, HeldObject, Body, External, WorldSurface, DynamicProp, Actor, QueryOnly
RockProviderFrameEnrichmentFlagV1	delta, HMD transform/forward, coherent hand roles, state sequence, collision generation, and equipped-transition sequence validity
RockProviderFrameStateChangeFlagV1	lifecycle, right hand, left hand, weapon, equipped transition, collision, and hand-role changes

Interaction and input

Type	Values
RockProviderInteractionCommandKindV1	ForceGrab, ForceRelease, ThrownDrop
RockProviderInteractionCommandStateV1	Queued, Succeeded, Rejected, Cancelled
RockProviderCommandStageV1	Accepted, Queued, Committed, Applied, Terminal
RockProviderInteractionFailureV1	provider/write/owner/request/generation/target/hand/ownership mismatch reasons
RockProviderForceGrabFlagV1	UsePreferredGrabPointGame
RockProviderForceReleaseFlagV1	ImmediateCollisionRestore, RequireMatchingTarget, UseVelocityHavok
RockProviderThrownDropFlagV1	ImmediateCollisionRestore, RequireMatchingTarget, UseVelocityHavok
RockProviderHandInputSuppressionFlagV1	normal grab press/release, held-weapon trigger equip, gameplay candidates, OpenVR game input, native VATS release, native V.A.N.S. hold, and SuppressConfigModeChord combination
RockProviderInputAvailabilityReasonV1	Available, HookNotSampled, BlockingMenu, ReleaseToRearm, InvalidButton
RockProviderSuppressionInvalidationReasonV1	None, Expired, GenerationChanged, OwnerUnregistered, ProviderLost, ExplicitClear, CallbackFault
RockProviderOffhandReservation	Normal, ReloadReserved, ReloadPoseOverride

Weapon parts and classification

Type	Values
RockProviderWeaponPartGrabModeV1	None, FullTwoHandAuthority, AttachOnly
RockProviderWeaponPartTargetFlagV1	body/root/name/part/reload/support/socket/action matchers and NonExclusive
RockProviderWeaponPartDriveSpaceV1	WeaponRootLocal, SourceParentLocal
RockProviderWeaponPartGripKindV1	None, FiringGrip, SupportFullAuthority, SupportVisualOnly, PartCarry, AttachOnly
RockProviderWeaponPartGripLocalSpaceV1	WeaponRootLocal, PartSourceLocal
RockProviderWeaponPartDriveApplicationV1	Unknown, Applied, Unresolved, StaleGeneration, MissingParent, LostPriority, InvalidTransform, CapacityRejected, Restored
RockProviderWeaponPartPoseFlagV1	Valid, SourceParentLocalValid, WeaponRootLocalValid
RockProviderWeaponPartClassificationSourceV1	NameToken, SlotAnchor, RigAnchor, AttachmentEvidence
RockProviderWeaponPartKindV1	receiver, barrel, handguard, foregrip, pump, stock, grip, magazine, magwell, bolt, slide, charging handle, break action, cylinder, chamber, shell, round, laser cell, lever, sight, accessory, cosmetic ammo, other, laser sight, flashlight, laser/flashlight combo, scope, muzzle device, bipod
RockProviderWeaponActionRoleV1	None, Bolt, Slide, ChargingHandle, Pump, BreakAction, Cylinder, Lever, Latch
RockProviderWeaponSizeClassV1	Melee, Pistol, Rifle, Heavy
RockProviderWeaponClassificationSourceV1	None, Keyword, WeightFallback, Default
RockProviderWeaponClassificationProvenanceFlagV1	KeywordEvidence, MeshBoundsFallback, GenerationBound
RockProviderWeaponKeywordFlagV1	weapon-family/material/behavior keyword bits from Pistol through Automatic
RockProviderWeaponEmitterKindV1	Unknown, Flashlight, Laser, Reticle
RockProviderWeaponEmitterSourceV1	Unknown, EffectGeometry, AddOnNode
RockProviderWeaponEmitterFlagV1	transform, direction, effect-state, addon-node, OMOD, and attach-point validity
RockProviderWeaponCompositionFlagV1	Active, Disabled, AttachPointResolved, SemanticEvidenceMatched
RockProviderScopeActivationSourceV1	None, NativeGeometry, RockGeometry, ManualInput
RockProviderScopeSightFlagV1	availability/activity/menu, anchor/bounds/native-overlay validity, and manual direct-transition requirement

Animation, presentation, and equipped weapon

Type	Values
RockProviderNativeAnimationAuthorityFlagV1	Arms, Hands, Weapon, combined ReloadPose
RockProviderNativeAnimationAuthorityStatusFlagV1	hook/runtime/capture/test/failure/thread/fault/provider status
RockProviderAnimationPhaseV1	BeforeRock, AfterRock, Complete, NativeGraphOutput
RockProviderAnimationPhaseContextFlagV1	ROCK/provider/skeleton readiness, menu/config blocking, visual-write permission
RockProviderEquippedWeaponGripStateFlagV1	validity, two-hand grip, firing-hand side, transform ownership, world/hand-transform validity
RockProviderEquippedWeaponHandlingFlagV1	firing ownership, detach, handoff, grip-zone equip/haptics, proximity support, shoulder stash, Pip-Boy-hand equip, visual-bridge tuning
RockProviderEquippedWeaponHandlingRuntimeFlagV1	authority/fixed hand/current hand/infrastructure/manual/part-carry/grip/weapon state
RockProviderHandVisualAuthorityFlagV1	WorldTransform, FingerLocalTransforms
RockProviderAuthoredGripSourceV1	Unknown, LiveEquippedGraph, NativeIdlePreharvest, RuntimeCanonical
RockProviderAuthoredGripPoseFlagV1	pose and per-hand/per-finger validity
RockProviderPresentedHandPoseFlagV1	pose/world/finger validity and root-flattened readback
RockProviderEquippedWeaponTransitionSourceV1	observed/trigger/grip-zone equip, menu exit, workbench exit
RockProviderEquippedWeaponTransitionResultV1	completion and terminal loss/timeout/handoff/recovery/provider/shutdown reasons
RockProviderEquippedWeaponStateFlagV1	validity, identity/draw pending, bridge/native render, handoff, recovery, transition state

Contacts, events, and diagnostics

Type	Values
RockProviderExternalBodyRole	reload mobile/socket/action/proxy and actor ragdoll bone
RockProviderExternalBodyContactPolicy	hand reporting, all-source reporting, ROCK dynamic-push suppression
RockProviderExternalSourceKind	Unknown, Hand, Weapon, HeldObject
RockProviderExternalContactQuality	BodyPairOnly, AggregateImpulse, RawPoint
RockProviderExternalContactFlagV1	velocity/point/normal validity, measured/estimated point, collision availability, transition suppression
RockProviderExternalContactStreamFlagV1	gap and overwrite indicators
RockProviderSemanticHandContactFlagV1	point/normal/form/relation/collision/transition validity
RockProviderSemanticContactStateV1	Begin, Continued, End
RockProviderPlayerColliderKindV1	Hand, Body
RockProviderPlayerColliderFlagV1	validity, enabled, palm anchor, transform, power armor
RockProviderHandCollisionAvailabilityFlagV1	body/twin/write/collision readiness and transition/menu/disabled suppression
RockProviderHandInteractionPhaseV1	idle through touching/selecting/pulling/catching/holding/releasing/stash/consume candidate
RockProviderHandInteractionFlagV1	hand role, object/weapon/grip type, suppression, collision, transition, touch grab, fixed/global surface latch, valid surface anchor, mesh authority/finger pose/fallback, and truncation state
RockProviderEventKindV1	lifecycle, equipped transition, authority loss, command terminal, grab state
RockProviderEventStreamFlagV1	gap and overwrite indicators
RockProviderAuthorityKindV1	input, drives, native animation/runtime, equipped handling, reservation, visuals, overlay, targets
RockProviderDebugOverlayTextFlagV1	WorldAnchored
RockProviderTouchGrabKindV1	FixedAnchor, LimitedHinge, LimitedPrismatic
RockProviderSurfaceGripModeV1	CollisionAnchor, MeshAnchor, CollisionFallback
RockProviderTouchGrabTargetFlagV1	right/left/two-hand eligibility, latch-on-release, wildcard body matching, and static/keyframed/dynamic motion masks
RockProviderTouchGrabPhaseV1	Inactive, Armed, Held, Latched, Yielded, Invalidated
RockProviderTouchGrabReleaseReasonV1	grip release, owner yield, target removal, expiry, generation/world/target/hand invalidation
RockProviderTouchGrabStateFlagV1	contact point/normal/coordinate validity, fixed-anchor state, original keyframed/dynamic motion, mesh authority, active mesh finger pose, and collision fallback
RockProviderWorldRaycastResultFlagV1	Hit, NormalValid

Public structure catalogue

RockProviderStructureIdV1 assigns stable IDs to 66 public structures so a consumer can query sizes before constructing a type shared with a newer V1 provider.

IDs	Structures	Detailed reference
1–5	API descriptor, consumer registration/handle, base and extended limits	Core and discovery
6–7	frame snapshot, hand frame	Frames, hands, and events
8–11	hand interaction, provider event/stream, equipped-weapon state	Frames, hands, and events
12–15	external registration, legacy/scoped contact, contact stream	Contacts and external bodies
16–19	part resolution query/result, part pose, drive result	Weapon-part interaction
20–22	scope state and weapon composition state/entry	Weapon data and optics
23–24	authored grip pose, presented hand pose	Animation and visuals
25–27	semantic contact, collider descriptor, collision availability	Contacts and external bodies
28–30	suppression state and offhand reservation request/state	Input and offhand
31–34	force-grab/release/drop requests and command result	Interaction commands
35–36	input-suppression request and raw-button state	Input and offhand
37–40	part target, transform, drive target, grip state	Weapon-part interaction
41–46	contact query/result, classification, point, bounds, emitter	Weapon data and weapon parts
47–50	native authority request/state, phase context, grip state	Animation and visuals
51–52	equipped handling request/state	Equipped-weapon handling
53–54	hand visual request and native runtime publication	Animation and visuals
55–57	debug line, text, and publication	Shared debug overlay
58–59	weapon evidence detail and body contact	Weapon data and contacts
60	complete API function table	Every API function
61–62	touch-grab target and state	Touch mechanisms and world tools
63	equipped-weapon hand request	Equipped-weapon handling
64–65	world raycast request/result	Touch mechanisms and world tools
66	collider visualization request	Shared debug overlay

ABI-safe structure use

For a setter, follow the API's exact-size and supported-version rules. For a getter, construct the output with {} and let its default member initializers advertise your compiled size/version. Use getPublicStructureSizeV1 when loading types dynamically or validating a generated binding.

Reserved fields must remain zero. Never serialize raw public structures as a permanent file format: tokens, pointer witnesses, generation values, table extent, and future reserved meaning are runtime contracts, not save data.