What to build with the ROCK SDK

ROCK is a shared VR interaction provider. It observes and coordinates physical hands, the equipped weapon, generated collision, contacts, input ownership, animation boundaries, and short-lived authority. A consumer plugin can build a focused experience on top without copying ROCK's hooks, collision setup, or scene classification.

Fallout 4 VR + hFRIK
          │
          ▼
 ROCK: hands · weapon · collision · input · lifecycle · arbitration
          │
          ├── reload / weapon-part consumer
          ├── scope / optic consumer
          ├── ragdoll / damage consumer
          ├── animation / presentation consumer
          ├── accessibility / input consumer
          └── diagnostics / tooling consumer

ROCK owns the common physical truth. Each addon owns only its product logic and publishes intent through a bounded API.

Generic example mods

The provider model works best when each mod owns one clear product domain:

• a physical reload mod resolves magazines, bolts, slides, cylinders, and shells; publishes short part-target/drive leases; and coordinates offhand input without duplicating weapon collision;
• an active-ragdoll damage mod registers actor-bone bodies by scope and interprets enriched hand/weapon/held-object contact evidence through its own gameplay safeguards;
• an ambidextrous handling mod owns one bounded weapon-handling lease and requests canonical left/right carry instead of attaching a second weapon;
• a native animation bridge captures graph output at explicit phases, publishes executor health, and hands final root/finger presentation back through visual authority;
• an optic/emitter mod consumes composition, sight state, muzzle/emitter transforms, and bounded raycasts without rediscovering weapon nodes;
• a wearable storage mod registers its own bodies and reacts to scoped hand/body contacts while keeping inventory rules in its own domain;
• a physical world-control mod publishes fixed, hinged, or sliding touch targets and yields them cleanly before scripted motion;
• a runtime inspector presents limits, generations, contacts, part resolution, and exact collider focus through ROCK's shared overlay.

See Minimal example mods for four buildable starting points without product-specific dependencies.

Product map

Product	Read from ROCK	Publish to ROCK	Core capabilities
Physical reload system	weapon evidence/composition, part poses, grips, contacts, hand state	part targets/drives, offhand reservation, input suppression, optional animation authority	WeaponPartInteraction, WeaponPartObservability, WeaponComposition, OffhandReservation, HandInputSuppression
Physical scopes and optics	scope state, emitters, composition, weapon/hand pose, input	optional input suppression and debug visualization	ScopeSightState, WeaponComposition, PoseReadback, InputObservability
Ambidextrous weapon handling	equipped weapon/hand state and grip state	equipped handling lease	EquippedWeaponHandlingAuthority, EquippedWeaponGripState
Native reload/reanimation bridge	authored grip pose, phase context, weapon grip state	animation authority, runtime health, hand visuals	NativeAnimationAuthority, AnimationPhases, NativeAnimationRuntimeProvider, PoseReadback, HandVisualAuthority
Active-ragdoll interaction or damage	player colliders, semantic/body contacts, external contact stream	actor-bone external-body scopes	ExternalBodyScopes, ExternalContacts, PlayerColliderDescriptors, SemanticHandContacts
Backpack or wearable interaction	hand state, body zones/colliders, contacts	wearable bodies, offhand/input reservation as needed	ExternalBodies or ExternalBodyScopes, ExternalContacts, HandInteractionState
Interaction automation	lifecycle, hand state, event stream, command results	force grab/release/thrown drop	InteractionCommands, ProviderEvents, HandInteractionState
Accessibility input layer	physical hand roles, raw button level/age, suppression state	narrow suppression leases and optional handling policy	InputObservability, HandInputSuppression, optionally EquippedWeaponHandlingAuthority
Presentation or spectator addon	final presented hands, equipped transition state, scope state	normally read-only	PoseReadback, ScopeSightState, ProviderEvents
Weapon compatibility profiler	classification, OMOD composition, evidence, emitters, part poses	optional diagnostic overlay	WeaponComposition, WeaponPartObservability, DebugOverlayPublication
Runtime inspector / prober	limits, lifecycle, events, contacts, resolution, poses	bounded debug lines/text	read capabilities relevant to the inspected system plus DebugOverlayPublication
Surface climbing	hand state, lifecycle, touch-target phase/contact	two independently leased wildcard fixed anchors	FrameSnapshots, TouchGrabTargets
Hinged or sliding world control	touch state, coordinate/velocity, lifecycle	exact-body hinge/prismatic targets and explicit yield	TouchGrabTargets
Short world probe / aim helper	frame generations, muzzle/HMD direction	bounded provider-filtered raycast	WorldRaycasts, plus the relevant weapon/pose read capability

1. Physical reloads and weapon controls

Build a reload state machine around stable weapon generation and concrete part identity:

1. Read composition/evidence after a new weapon generation appears.
2. Identify the magazine, bolt, pump, cylinder, or other part.
3. Publish a short part-target set for the active reload phase.
4. Drive only a concrete resolved part, with generation guards.
5. Observe drive results and physical grip state.
6. Reserve the offhand and suppress only conflicting input.
7. End with explicit target, drive, input, and reservation cleanup.

ROCK supplies discovery, collision, arbitration, and cleanup. Your addon owns weapon-specific sequencing, authored transforms, ammo/gameplay integration, and user configuration.

Start with weapon data, weapon parts, and input/offhand ownership.

2. Scope and optic systems

Use getScopeSightStateV1 as the canonical state transition, rather than inferring scope activity from a node name alone. It connects:

• equipped weapon generation;
• installed OMOD/attach-point composition;
• resolved sight body and weapon-local bounds;
• native versus ROCK geometry activation;
• native overlay availability and manual transition requirements.

An optic addon can choose a render mode, reticle source, magnification profile, or direct/manual activation path based on those value fields. Cache by weapon generation plus composition signature; invalidate on provider/equipped events.

3. Ambidextrous handling

Use one EquippedWeaponHandlingAuthority lease to enable firing-grip ownership, detach, handoff, grip-zone equip, and shoulder stash as a coherent policy. Observe getEquippedWeaponHandlingStateV1 to distinguish configured handedness from the physical hand that currently owns firing.

Do not implement a parallel weapon attach state machine. It will race ROCK's native render recovery and produce half-equipped visual/physics states.

4. Animation and reanimation

An animation consumer should use phase callbacks as explicit boundaries:

• capture authored output at NativeGraphOutput without mutating it;
• request bounded native authority for the required chains;
• publish executor health if it is the one runtime provider;
• read selected authored grip targets;
• apply final world/finger presentation through hand visual authority;
• verify what was actually presented.

This model keeps native animation, hFRIK, weapon physics, and final hand visuals connected by generations and leases instead of implicit update order.

5. Actor physics, damage, and wearables

Register addon-owned bodies by child scope. For an actor, use a stable actor or ragdoll-session token as scopeToken, and a separate body generation whenever the ragdoll is rebuilt. Consume the cursor stream and treat ring gaps as an explicit loss of continuous history.

ROCK's contact weight is evidence, not a physical impulse magnitude. A damage system should combine contact quality, source velocity validity, target role, its own mass/material rules, cooldowns, and gameplay safeguards.

6. Accessibility and remapping

The raw button API exposes physical level plus sample freshness even while ROCK suppresses the corresponding native action. Build edges locally from sampleSequence and prior state. Pair a narrow suppression lease with the exact actions your feature replaces.

Good accessibility products include:

• configurable grip-zone sizes and settle times;
• left/right physical firing ownership without changing native handedness;
• hold/toggle conversions implemented from fresh raw level samples;
• mode chords that temporarily suppress conflicting grab/equip actions;
• visible diagnostics explaining which owner currently suppresses input.

Do not suppress broad OpenVR game input unless your feature truly owns all of the affected behavior for that hand.

7. Diagnostics and compatibility tooling

The SDK can power an in-game inspector showing:

• table extent, provider limits, features, and granted capabilities;
• lifecycle/generation transitions;
• equipped weapon classification, OMODs, evidence, and emitters;
• target arbitration and drive-application results;
• current hand state, contacts, and colliders;
• authority loss and command-terminal events.

Publish only selected lines/labels through the shared overlay and write durable logs outside hot callbacks. A diagnostic tool should never change behavior just because it is observing it.

Recommended consumer architecture

Keep provider integration narrow:

RockClient
├── discovery + extent/feature checks
├── owner registration + granted capabilities
├── callback and cursor ownership
├── immutable per-frame value cache
└── deterministic shutdown
        │
        ▼
Product domain
├── reload / optic / ragdoll / accessibility state machine
├── authored configuration and persistence
└── bounded publications expressed as SDK values

The RockClient boundary should be the only code that knows about function table slots and owner tokens. Product code consumes copied domain values and returns intent. This makes provider loss, capability downgrade, and unit tests manageable.

What the SDK intentionally does not provide

The public contract does not authorize:

• arbitrary scene-graph traversal or writable scene pointers;
• arbitrary Havok body mutation;
• direct ownership of ROCK's listeners, constraints, or generated colliders;
• arbitrary inventory/equipment commands beyond the documented interaction and handling surfaces;
• private hooks, addresses, offsets, or internal object layouts;
• unbounded event history or guaranteed diagnostic rendering;
• a stable serialization format for runtime structures.

If a product requires one of those, first express the needed outcome as a bounded value/query/command suitable for a provider API. Do not build against pointer witnesses or ROCK internals.

Selecting a first project

For a minimal read-only integration, build a weapon/hand inspector using frame snapshots, weapon classification, composition, and provider events.

For a minimal stateful integration, build a short-lived input suppression or debug-overlay publication. Those exercise owner registration, capabilities, generation guards, callback threading, leases, and cleanup without taking weapon physics ownership.

For a full integration, follow the consumer recipes and minimal example mods, then apply the production checklist.