Animation & 3D Components

This document describes the 3D components that are currently used in the runtime.

Runtime Components

Domain	Component	Role
Interaction	`InteractableObject`	Focus detection through distance and raycasting
Interaction	`TriggerObject`	Press-to-trigger interactions, optional sound, optional spawned model
Interaction	`GrabbableObject`	Physics grab and hand-tracking grab behavior
Model	`AnimatedModel`	GLTF animation playback with fade, speed, and context controls
Model	`ExplodableModel`	Split/reassemble a GLTF model into separated parts
Model	`SimpleModel`	Lightweight static GLTF render helper
Gameplay	`RepairCaseModel`	Repair case lid animation, proximity float, and wobble

Continuous Animation

Use useFrame for per-frame 3D behavior. Current examples:

GrabbableObject updates held object velocity every frame.
ExplodableModel updates split part positions every frame.
RepairCaseModel updates proximity float and rotation wobble every frame.
SkyModel follows the camera position every frame.

Timeline Animation

Use GSAP only for discrete timeline-style transitions. Current example:

RepairCaseModel animates the case lid between open and closed rotations.

Animated Models

src/components/three/models/AnimatedModel.tsx wraps drei useAnimations() around a loaded GLTF scene.

It supports:

default animation playback
optional autoplay
fade duration
speed multiplier
onLoaded
onAnimationEnd
context controls through AnimatedModelContext

The debug physics scene currently uses it to preview:

public/models/electricienne-animated/model.gltf

with the Dance animation.

GLTF Reuse

Use useClonedObject when a GLTF scene is reused by a component instance. It memoizes scene.clone(true) and keeps clone creation out of render churn.

File Structure

src/components/three/
├── gameplay/
│   ├── RepairCaseModel.tsx
│   ├── RepairGame.tsx
│   └── RepairRepairingStep.tsx
├── interaction/
│   ├── GrabbableObject.tsx
│   ├── InteractableObject.tsx
│   └── TriggerObject.tsx
├── models/
│   ├── AnimatedModel.tsx
│   ├── ExplodableModel.tsx
│   └── SimpleModel.tsx
└── world/
    └── SkyModel.tsx

2.7 KiB Raw Blame History