Types

All types are importable from @carverjs/core/types.

import type {
  WorldMode,
  WorldPhysicsConfig,
  CameraProps2D,
  CameraProps3D,
  SkyProps,
  EnvironmentProps,
  OrbitControlsProps,
  AmbientLightProps,
  DirectionalLightProps,
  ActorTransformProps,
  ActorEventProps,
  ActorPhysicsProps,
  PrimitiveShape,
  PrimitiveMaterialType,
  CameraType,
  CameraControlsType,
  CameraFollowConfig,
  PerspectiveCameraProps,
  OrthographicCameraProps,
  MapControlsProps,
  PointerLockControlsProps,
  UseCameraOptions,
  UseCameraReturn,
  GameLoopStage,
  GamePhase,
  UseGameLoopOptions,
  UseGameLoopReturn,
  GameLoopCallback,
  KeyState,
  PointerState,
  ActionMap,
  UseInputOptions,
  UseInputReturn,
  ColliderShape,
  ColliderDef,
  AABBColliderDef,
  SphereColliderDef,
  CircleColliderDef,
  CollisionEvent,
  CollisionCallback,
  UseCollisionOptions,
  UseCollisionReturn,
  GridCollisionConfig,
  GridCellCallback,
  UseGridCollisionOptions,
  UseGridCollisionReturn,
  RigidBodyType,
  PhysicsColliderType,
  UsePhysicsReturn,
  AudioChannel,
  AudioFormat,
  SoundState,
  AudioSpriteRegion,
  AudioSpriteMap,
  SoundDefinition,
  PanningModel,
  DistanceModel,
  SpatialAudioOptions,
  PlaySoundOptions,
  SoundHandle,
  CrossfadeOptions,
  MusicOptions,
  SoundMap,
  UseAudioOptions,
  UseAudioReturn,
  AudioListenerConfig,
  AssetType,
  AssetEntry,
  AssetManifest,
  AssetGroupConfig,
  LoadingProgress,
  AssetLoadError,
  CacheEntry,
  EasingFn,
  EasingPreset,
  EasingInput,
  TweenState,
  TweenDirection,
  TweenConfig,
  NumberTweenConfig,
  TweenControls,
  TweenGroupControls,
  TimelineConfig,
  TimelineControls,
  TimelinePosition,
  UseTweenReturn,
  EmitterShape,
  EmitterShapeConfig,
  PointShapeConfig,
  ConeShapeConfig,
  SphereShapeConfig,
  RectangleShapeConfig,
  EdgeShapeConfig,
  RingShapeConfig,
  ValueRange,
  ColorRange,
  CurveKeyframe,
  LifetimeCurve,
  ColorGradientStop,
  ColorGradient,
  ParticleBlendMode,
  SpriteSheetConfig,
  EmissionMode,
  BurstConfig,
  ParticleSpace,
  ParticlePropertyConfig,
  OverLifetimeConfig,
  ParticleEmitterConfig,
  ParticlePreset,
  ParticleData,
  UseParticlesOptions,
  UseParticlesReturn,
  ParticleEmitterProps,
} from "@carverjs/core/types";

Game & World Types #

Type	Definition	Used by	Description
`WorldMode`	`"2d" \| "3d"`	Game	Scene mode
`CameraProps2D`	`Partial<Omit<OrthographicCameraProps, "makeDefault">>`	World	Overrides for the 2D camera
`CameraProps3D`	`Partial<Omit<PerspectiveCameraProps, "makeDefault">>`	World	Overrides for the 3D camera
`SkyProps`	`Partial<drei.SkyProps>`	Game	Overrides for the Sky component
`EnvironmentProps`	`Partial<drei.EnvironmentProps>`	Game	Overrides for the Environment component
`OrbitControlsProps`	`Partial<drei.OrbitControlsProps>`	World	Overrides for OrbitControls
`AmbientLightProps`	`Partial<ThreeElements["ambientLight"]>`	Game	Overrides for ambient light
`DirectionalLightProps`	`Partial<ThreeElements["directionalLight"]>`	Game	Overrides for directional light
`WorldPhysicsConfig`	`{ gravity?, timestep?, interpolation?, debug? }`	World	Physics configuration for a World

Actor Types #

`ActorTransformProps` #

Field	Type	Description
`position`	`Vector3`	World position — `[x, y, z]` or a Three.js `Vector3`
`rotation`	`Euler`	Rotation — `[x, y, z]` or a Three.js `Euler`
`scale`	`Vector3`	Scale — `[x, y, z]`, uniform number, or a Three.js `Vector3`. Overrides `size`
`size`	`number`	Uniform scale factor — scales all axes equally to preserve aspect ratio

`ActorEventProps` #

All R3F pointer/interaction events on a <group>:

onClick, onContextMenu, onDoubleClick, onPointerUp, onPointerDown, onPointerOver, onPointerOut, onPointerEnter, onPointerLeave, onPointerMove, onPointerMissed, onWheel

`PrimitiveShape` #

type PrimitiveShape =
  | "box" | "sphere" | "cylinder" | "cone" | "torus"
  | "plane" | "circle" | "capsule" | "ring";

`PrimitiveMaterialType` #

type PrimitiveMaterialType = "standard" | "basic" | "phong" | "lambert" | "toon";

Camera Types #

Type	Definition	Description
`CameraType`	`"perspective" \| "orthographic"`	Camera projection type
`CameraControlsType`	`"orbit" \| "map" \| "pointerlock" \| "none"`	Controls mode
`PerspectiveCameraProps`	`Partial<Omit<drei.PerspectiveCameraProps, "makeDefault">>`	Overrides for PerspectiveCamera
`OrthographicCameraProps`	`Partial<Omit<drei.OrthographicCameraProps, "makeDefault">>`	Overrides for OrthographicCamera
`MapControlsProps`	`Partial<drei.MapControlsProps>`	Overrides for MapControls
`PointerLockControlsProps`	`Partial<drei.PointerLockControlsProps>`	Overrides for PointerLockControls

`CameraFollowConfig` #

Field	Type	Default	Description
`target`	`RefObject<Object3D>`	—	Ref to the Object3D to follow
`offset`	`[number, number, number]`	`[0, 5, 10]`	Position offset from the target
`smoothing`	`number`	`0.1`	Lerp factor (0–1)
`lookAt`	`boolean`	`true`	Whether the camera looks at the target
`lookAtOffset`	`[number, number, number]`	`[0, 0, 0]`	Offset for the look-at point

`UseCameraOptions` #

Field	Type	Description
`follow`	`CameraFollowConfig`	Follow configuration

`UseCameraReturn` #

Field	Type	Description
`shake`	`(intensity?: number, duration?: number) => void`	Trigger camera shake
`moveTo`	`(position: [number, number, number], duration?: number) => void`	Smooth transition to a position
`lookAt`	`(target: [number, number, number]) => void`	Look at a world position

Game Loop Types #

Type	Definition	Description
`GameLoopStage`	`"earlyUpdate" \| "fixedUpdate" \| "update" \| "lateUpdate"`	Update stage for a game loop callback
`GamePhase`	`"loading" \| "playing" \| "paused" \| "gameover"`	Global game phase
`GameLoopCallback`	`(delta: number, elapsed: number) => void`	Per-frame callback signature

`UseGameLoopOptions` #

Field	Type	Default	Description
`stage`	`GameLoopStage`	`"update"`	Update stage
`fixedTimestep`	`boolean`	`false`	Fixed-timestep mode
`fixedDelta`	`number`	`1/60`	Seconds per fixed tick
`maxDelta`	`number`	`0.1`	Max raw delta cap
`enabled`	`boolean`	`true`	Whether this instance is active

`UseGameLoopReturn` #

Field	Type	Description
`phase`	`GamePhase`	Current game phase
`isPaused`	`boolean`	True when phase is paused or gameover
`elapsed`	`number`	Total elapsed seconds while playing

Input Types #

`KeyState` #

Field	Type	Description
`pressed`	`boolean`	Key is currently held down
`justPressed`	`boolean`	Key was first pressed this frame
`justReleased`	`boolean`	Key was released this frame

`PointerState` #

Field	Type	Description
`position`	`{ x: number, y: number }`	Screen-space position in pixels
`isDown`	`boolean`	Primary pointer button is held
`justDown`	`boolean`	Button was pressed this frame
`justUp`	`boolean`	Button was released this frame

`ActionMap` #

type ActionMap = Record<string, string[]>;

Maps logical action names to arrays of KeyboardEvent.code values.

`UseInputOptions` #

Field	Type	Default	Description
`keys`	`string[]`	—	Subscribe to specific key codes only
`actions`	`ActionMap`	`{}`	Logical action map
`enabled`	`boolean`	`true`	Toggle this hook on/off

`UseInputReturn` #

Field	Type	Description
`isPressed`	`(code: string) => boolean`	Key is currently held
`isJustPressed`	`(code: string) => boolean`	Key was pressed this frame
`isJustReleased`	`(code: string) => boolean`	Key was released this frame
`isAction`	`(action: string) => boolean`	Any bound key for the action is held
`isActionJustPressed`	`(action: string) => boolean`	Any bound key for the action was just pressed
`getAxis`	`(neg: string, pos: string) => number`	Returns -1, 0, or 1
`pointer`	`PointerState`	Live pointer state

Collision Types (Built-in) #

`ColliderShape` #

type ColliderShape = "aabb" | "sphere" | "circle";

`ColliderDef` #

type ColliderDef = AABBColliderDef | SphereColliderDef | CircleColliderDef;

`AABBColliderDef` #

Field	Type	Description
`shape`	`"aabb"`	Shape discriminator
`halfExtents`	`[number, number, number]`	Half-width, half-height, half-depth
`offset`	`[number, number, number]`	Offset from Actor position. Default: `[0, 0, 0]`

`SphereColliderDef` #

Field	Type	Description
`shape`	`"sphere"`	Shape discriminator
`radius`	`number`	Sphere radius
`offset`	`[number, number, number]`	Offset from Actor position. Default: `[0, 0, 0]`

`CircleColliderDef` #

Field	Type	Description
`shape`	`"circle"`	Shape discriminator
`radius`	`number`	Circle radius
`offset`	`[number, number, number]`	Offset from Actor position. Default: `[0, 0, 0]`

`CollisionEvent` #

Field	Type	Description
`otherName`	`string`	Name of the other collider
`otherUserData`	`Record<string, unknown>`	The other collider's userData
`otherRef`	`RefObject<Object3D>`	The other collider's Object3D ref
`isSensor`	`boolean`	Whether the other collider is a sensor

`CollisionCallback` #

type CollisionCallback = (event: CollisionEvent) => void;

`UseCollisionOptions` #

Field	Type	Default	Description
`ref`	`RefObject<Object3D>`	—	Required. Actor group ref
`collider`	`ColliderDef`	—	Required. Collider shape
`name`	`string`	`""`	Identifier in collision events
`userData`	`Record<string, unknown>`	`{}`	Passed through to events
`layer`	`number`	`0xFFFFFFFF`	Collision layer bitmask
`mask`	`number`	`0xFFFFFFFF`	Layers to check against
`sensor`	`boolean`	`false`	Trigger mode
`onCollisionEnter`	`CollisionCallback`	—	First frame of overlap
`onCollisionExit`	`CollisionCallback`	—	Last frame of overlap
`onCollisionStay`	`CollisionCallback`	—	Every frame while overlapping
`enabled`	`boolean`	`true`	Toggle on/off

`UseCollisionReturn` #

Field	Type	Description
`isOverlapping`	`(name: string) => boolean`	Check overlap with a named collider
`getOverlaps`	`() => string[]`	Get all current overlap names

Grid Collision Types #

`GridCollisionConfig` #

Field	Type	Default	Description
`width`	`number`	—	Required. Cells along X
`height`	`number`	—	Required. Cells along Y
`cellSize`	`number`	`1`	World-space cell size
`origin`	`[number, number]`	`[0, 0]`	World-space origin offset

`GridCellCallback` #

type GridCellCallback = (x: number, y: number, value: number) => void;

`UseGridCollisionOptions` #

Field	Type	Description
`config`	`GridCollisionConfig`	Required. Grid configuration

`UseGridCollisionReturn` #

Field	Type	Description
`setCell`	`(x, y, value) => void`	Set cell value (`0` = empty)
`getCell`	`(x, y) => number`	Get cell value
`clearCell`	`(x, y) => void`	Clear a cell
`isCellOccupied`	`(x, y) => boolean`	Check if cell is non-zero
`worldToGrid`	`(wx, wy) => [number, number]`	World to grid coords
`gridToWorld`	`(gx, gy) => [number, number]`	Grid to world coords (cell center)
`getNeighbors4`	`(x, y) => [number, number, number, number]`	Cardinal neighbors `[up, right, down, left]`
`getNeighbors8`	`(x, y) => number[]`	8 neighbors (cardinal + diagonal)
`clearAll`	`() => void`	Clear entire grid

Physics Types (Rapier-backed) #

`RigidBodyType` #

type RigidBodyType = "dynamic" | "kinematicPosition" | "kinematicVelocity" | "fixed";

`PhysicsColliderType` #

type PhysicsColliderType = "cuboid" | "ball" | "capsule" | "trimesh" | "convexHull" | "auto";

`WorldPhysicsConfig` #

Field	Type	Default	Description
`gravity`	`[number, number, number]`	`[0, -9.81, 0]`	Gravity vector
`timestep`	`number \| "vary"`	`1/60`	Physics timestep
`interpolation`	`boolean`	`true`	Smooth rendering between steps
`debug`	`boolean`	`false`	Show wireframe colliders

`ActorPhysicsProps` #

Field	Type	Default	Description
`bodyType`	`RigidBodyType`	`"dynamic"`	Rigid body type
`collider`	`PhysicsColliderType`	`"auto"`	Collider shape
`mass`	`number`	`1`	Mass
`restitution`	`number`	`0`	Bounciness (0-1)
`friction`	`number`	`0.5`	Friction coefficient
`sensor`	`boolean`	`false`	Trigger volume
`gravityScale`	`number`	`1`	Per-body gravity multiplier
`linearDamping`	`number`	`0`	Linear damping
`angularDamping`	`number`	`0`	Angular damping
`ccd`	`boolean`	`false`	Continuous collision detection
`enabledTranslations`	`[boolean, boolean, boolean]`	—	Lock/unlock per-axis translation
`enabledRotations`	`[boolean, boolean, boolean]`	—	Lock/unlock per-axis rotation
`onCollisionEnter`	`CollisionCallback`	—	Collision start callback
`onCollisionExit`	`CollisionCallback`	—	Collision end callback

`UsePhysicsReturn` #

Field	Type	Description
`applyImpulse`	`([number, number, number]) => void`	Instantaneous force
`applyForce`	`([number, number, number]) => void`	Continuous force
`setLinearVelocity`	`([number, number, number]) => void`	Set linear velocity
`getLinearVelocity`	`() => [number, number, number]`	Get linear velocity
`setAngularVelocity`	`([number, number, number]) => void`	Set angular velocity
`setTranslation`	`([number, number, number]) => void`	Teleport body
`getTranslation`	`() => [number, number, number]`	Get position
`setRotation`	`([number, number, number, number]) => void`	Set rotation (quaternion)
`setEnabled`	`(boolean) => void`	Enable/disable body

Audio Types #

`AudioChannel` #

type AudioChannel = "master" | "sfx" | "music" | "ui" | "ambient" | "voice";

`AudioFormat` #

type AudioFormat = "mp3" | "ogg" | "wav" | "webm" | "aac" | "flac";

`SoundState` #

type SoundState = "playing" | "paused" | "stopped";

`AudioSpriteRegion` #

Field	Type	Default	Description
`start`	`number`	—	Start offset in seconds
`duration`	`number`	—	Duration in seconds
`loop`	`boolean`	`false`	Loop this region

`AudioSpriteMap` #

type AudioSpriteMap = Record<string, AudioSpriteRegion>;

`SoundDefinition` #

Field	Type	Default	Description
`src`	`string \| string[]`	—	Required. Audio URL(s)
`channel`	`AudioChannel`	`"sfx"`	Volume channel
`volume`	`number`	`1`	Base volume (0–1)
`rate`	`number`	`1`	Playback rate
`loop`	`boolean`	`false`	Loop playback
`maxInstances`	`number`	`5`	Max simultaneous instances
`preload`	`boolean`	`true`	Preload on registration
`sprites`	`AudioSpriteMap`	—	Audio sprite regions
`cooldown`	`number`	—	Min seconds between plays

`SpatialAudioOptions` #

Field	Type	Default	Description
`ref`	`RefObject<Object3D>`	—	Required. Emitter Object3D
`panningModel`	`"HRTF" \| "equalpower"`	`"HRTF"`	Panning algorithm
`distanceModel`	`"linear" \| "inverse" \| "exponential"`	`"inverse"`	Volume rolloff model
`refDistance`	`number`	`1`	Full-volume distance
`maxDistance`	`number`	`100`	Max audible distance
`rolloffFactor`	`number`	`1`	Rolloff speed
`coneInnerAngle`	`number`	`360`	Full-volume cone (degrees)
`coneOuterAngle`	`number`	`360`	Outer cone (degrees)
`coneOuterGain`	`number`	`0`	Volume outside outer cone
`trackPosition`	`boolean`	`true`	Auto-update position each frame

`PlaySoundOptions` #

Field	Type	Default	Description
`volume`	`number`	—	Override volume
`rate`	`number`	—	Override rate
`loop`	`boolean`	—	Override loop
`sprite`	`string`	—	Named sprite region
`spatial`	`SpatialAudioOptions`	—	3D spatial configuration
`fadeIn`	`number`	`0`	Fade-in duration (seconds)
`delay`	`number`	`0`	Delay before playback (seconds)
`onEnd`	`() => void`	—	Called when playback finishes
`onError`	`(Error) => void`	—	Called on failure

`SoundHandle` #

Field	Type	Description
`id`	`number`	Unique instance ID
`state`	`SoundState`	Current state
`stop`	`() => void`	Stop the instance
`pause`	`() => void`	Pause the instance
`resume`	`() => void`	Resume the instance
`fade`	`(from, to, duration) => void`	Fade volume
`setVolume`	`(number) => void`	Set volume
`setRate`	`(number) => void`	Set playback rate

`CrossfadeOptions` #

Field	Type	Default	Description
`duration`	`number`	`2`	Crossfade duration in seconds

`MusicOptions` #

Field	Type	Default	Description
`volume`	`number`	`1`	Music volume (0–1)
`loop`	`boolean`	`true`	Loop the track
`crossfade`	`CrossfadeOptions`	—	Crossfade settings

`UseAudioOptions` #

Field	Type	Default	Description
`sounds`	`SoundMap`	`{}`	Sound definitions to register
`enabled`	`boolean`	`true`	Toggle audio on/off

`UseAudioReturn` #

Field	Type	Description
`play`	`(name, options?) => SoundHandle \| null`	Play a registered sound
`stop`	`(name) => void`	Stop all instances of a sound
`pause`	`(name) => void`	Pause instances
`resume`	`(name) => void`	Resume instances
`isPlaying`	`(name) => boolean`	Check if playing
`playMusic`	`(src, options?) => void`	Play music with crossfade
`stopMusic`	`(fadeOut?) => void`	Stop music
`pauseMusic`	`() => void`	Pause music
`resumeMusic`	`() => void`	Resume music
`isMusicPlaying`	`() => boolean`	Check if music is playing
`setVolume`	`(channel, volume) => void`	Set channel volume
`getVolume`	`(channel) => number`	Get channel volume
`setMute`	`(channel, muted) => void`	Mute/unmute channel
`isMuted`	`(channel) => boolean`	Check mute state
`setMasterMute`	`(muted) => void`	Mute/unmute all
`preload`	`(name) => Promise<void>`	Preload a sound
`preloadAll`	`(names) => Promise<void>`	Preload multiple sounds
`isUnlocked`	`boolean`	AudioContext unlocked
`isReady`	`boolean`	Audio system ready

`AudioListenerConfig` #

Field	Type	Description
`listenerRef`	`RefObject<Object3D>`	Custom listener source. Defaults to active camera

Asset Types #

`AssetType` #

type AssetType = "gltf" | "texture" | "audio" | "json" | "binary";

`AssetEntry` #

Field	Type	Default	Description
`url`	`string`	—	Required. URL to load
`key`	`string`	`url`	Unique key for cache lookup
`type`	`AssetType`	Auto-detected	Asset type override
`priority`	`"critical" \| "high" \| "normal" \| "low" \| "lazy" \| number`	`"normal"`	Loading priority
`group`	`string`	—	Group name for batch operations
`sizeHint`	`number`	—	Expected file size in bytes
`loaderOptions`	`Record<string, unknown>`	—	Loader-specific options

`AssetManifest` #

Field	Type	Default	Description
`version`	`1`	—	Schema version
`baseUrl`	`string`	`""`	Base URL for relative asset paths
`assets`	`AssetEntry[]`	—	Required. Array of asset entries
`groups`	`Record<string, AssetGroupConfig>`	—	Group configuration

`AssetGroupConfig` #

Field	Type	Default	Description
`label`	`string`	—	Human-readable label
`preload`	`boolean`	`true`	Preload this group upfront
`exclusive`	`boolean`	`false`	Auto-unload when another exclusive group loads

`LoadingProgress` #

Field	Type	Description
`phase`	`"idle" \| "loading" \| "complete" \| "error"`	Current loading phase
`loaded`	`number`	Assets finished loading
`total`	`number`	Total assets to load
`progress`	`number`	Fraction complete (0 to 1)
`currentAsset`	`string \| null`	Asset currently loading
`currentGroup`	`string \| null`	Group currently loading
`errors`	`AssetLoadError[]`	Errors encountered

`AssetLoadError` #

Field	Type	Description
`key`	`string`	Asset key that failed
`url`	`string`	Asset URL that failed
`message`	`string`	Error message
`retries`	`number`	Retry attempts made
`recoverable`	`boolean`	Whether the error is recoverable

`CacheEntry` #

Field	Type	Description
`data`	`T`	The cached asset data
`key`	`string`	Cache key
`type`	`AssetType`	Asset type
`sizeBytes`	`number`	Estimated size in bytes
`lastAccessedAt`	`number`	Timestamp of last access
`refCount`	`number`	Active references (prevents eviction)

Tween Types #

`EasingFn` #

type EasingFn = (t: number) => number;

Normalized easing function: takes t in [0, 1], returns eased value.

`EasingPreset` #

type EasingPreset =
  | "linear"
  | "quad.in" | "quad.out" | "quad.inOut"
  | "cubic.in" | "cubic.out" | "cubic.inOut"
  | "quart.in" | "quart.out" | "quart.inOut"
  | "quint.in" | "quint.out" | "quint.inOut"
  | "sine.in" | "sine.out" | "sine.inOut"
  | "expo.in" | "expo.out" | "expo.inOut"
  | "circ.in" | "circ.out" | "circ.inOut"
  | "back.in" | "back.out" | "back.inOut"
  | "elastic.in" | "elastic.out" | "elastic.inOut"
  | "bounce.in" | "bounce.out" | "bounce.inOut"
  | "spring";

`EasingInput` #

type EasingInput = EasingPreset | EasingFn | [number, number, number, number];

Accepts a preset name, a custom function, or a cubic-bezier control point tuple.

`TweenState` #

type TweenState = "idle" | "pending" | "delayed" | "playing" | "completed" | "killed";

`TweenDirection` #

type TweenDirection = "forward" | "reverse";

`TweenConfig<T>` #

Field	Type	Default	Description
`target`	`T extends object`	—	Required. Object to animate
`to`	`Record<string, number>`	—	Required. End values (supports dot-notation)
`from`	`Record<string, number>`	—	Start values. If omitted, current values are captured
`duration`	`number`	`0.3`	Duration in seconds
`ease`	`EasingInput`	`"quad.out"`	Easing function or preset
`delay`	`number`	`0`	Delay before starting (seconds)
`repeat`	`number`	`0`	Additional repeats. `-1` = infinite
`repeatDelay`	`number`	`0`	Delay between repeats (seconds)
`yoyo`	`boolean`	`false`	Reverse on each repeat
`speed`	`number`	`1`	Playback speed multiplier
`group`	`string`	`""`	Named group for batch control
`persist`	`boolean`	`false`	Keep alive after completion
`ignorePause`	`boolean`	`false`	Continue when game is paused
`onStart`	`() => void`	—	Start callback
`onUpdate`	`(progress: number) => void`	—	Per-frame callback with eased progress
`onComplete`	`() => void`	—	Completion callback
`onRepeat`	`(count: number) => void`	—	Repeat callback
`onYoyo`	`(direction: TweenDirection) => void`	—	Direction reversal callback
`onKill`	`() => void`	—	Kill callback

`NumberTweenConfig` #

Same as TweenConfig except: no target/to/from fields. Instead has from: number and to: number. The onUpdate callback is (value: number, progress: number) => void.

`TweenControls` #

Field	Type	Description
`id`	`number`	Unique tween ID
`state`	`TweenState`	Current state
`progress`	`number`	Eased progress (0–1)
`pause()`	`() => TweenControls`	Pause the tween
`resume()`	`() => TweenControls`	Resume the tween
`kill()`	`() => TweenControls`	Stop and release
`restart()`	`() => TweenControls`	Restart from beginning
`seek(progress)`	`(number) => TweenControls`	Seek to progress (0–1)
`setSpeed(multiplier)`	`(number) => TweenControls`	Set playback speed
`chain(config)`	`(TweenConfig) => TweenControls`	Chain a follow-up tween
`finished`	`Promise<void>`	Resolves on completion

`TweenGroupControls` #

Field	Type	Description
`pause()`	`() => void`	Pause all tweens in the group
`resume()`	`() => void`	Resume all tweens in the group
`kill()`	`() => void`	Kill all tweens in the group
`count`	`number`	Active tween count in the group

`TimelinePosition` #

type TimelinePosition = number | string;

A number is an absolute time in seconds. Strings support relative positioning: "+=0.5", "-=0.2", "<", "<+=0.5", "label", "label+=0.3".

`TimelineConfig` #

Field	Type	Default	Description
`repeat`	`number`	`0`	Additional repeats. `-1` = infinite
`repeatDelay`	`number`	`0`	Delay between repeats
`yoyo`	`boolean`	`false`	Reverse on each repeat
`speed`	`number`	`1`	Playback speed
`paused`	`boolean`	`false`	Start paused
`ignorePause`	`boolean`	`false`	Continue when game is paused
`group`	`string`	—	Named group
`onStart`	`() => void`	—	Start callback
`onUpdate`	`(progress: number) => void`	—	Per-frame progress callback
`onComplete`	`() => void`	—	Completion callback
`onRepeat`	`(count: number) => void`	—	Repeat callback

`TimelineControls` #

Field	Type	Description
`id`	`number`	Unique timeline ID
`state`	`TweenState`	Current state
`progress`	`number`	Overall progress (0–1)
`duration`	`number`	Total duration in seconds
`add(config, position?)`	Adds a tween entry	Returns self
`addCallback(fn, position?)`	Adds a callback entry	Returns self
`addLabel(name, position?)`	Adds a named label	Returns self
`play()`	Start playing	Returns self
`pause()`	Pause	Returns self
`resume()`	Resume	Returns self
`kill()`	Kill and clean up	Returns self
`restart()`	Restart from beginning	Returns self
`seek(timeOrLabel)`	Seek to time or label	Returns self
`setSpeed(multiplier)`	Set playback speed	Returns self
`finished`	`Promise<void>`	Resolves on completion

`UseTweenReturn` #

Field	Type	Description
`tween`	`<T extends object>(TweenConfig<T>) => TweenControls`	Create a property tween
`tweenNumber`	`(NumberTweenConfig) => TweenControls`	Create a number tween
`timeline`	`(TimelineConfig?) => TimelineControls`	Create a timeline
`killAll`	`() => void`	Kill all hook-owned tweens
`pauseAll`	`() => void`	Pause all active tweens
`resumeAll`	`() => void`	Resume all paused tweens

Particle Types #

`EmitterShape` #

type EmitterShape = "point" | "cone" | "sphere" | "rectangle" | "edge" | "ring";

`EmitterShapeConfig` #

type EmitterShapeConfig =
  | PointShapeConfig
  | ConeShapeConfig
  | SphereShapeConfig
  | RectangleShapeConfig
  | EdgeShapeConfig
  | RingShapeConfig;

`ValueRange` #

type ValueRange = number | [number, number];

A single value or [min, max] range for per-particle randomization.

`ColorRange` #

type ColorRange = ColorRepresentation | [ColorRepresentation, ColorRepresentation];

A single color or [startColor, endColor] for random interpolation.

`CurveKeyframe` #

Field	Type	Description
`t`	`number`	Normalized lifetime (0 = birth, 1 = death)
`value`	`number`	Value at this point

`LifetimeCurve` #

type LifetimeCurve = CurveKeyframe[];

`ColorGradientStop` #

Field	Type	Description
`t`	`number`	Normalized lifetime (0–1)
`color`	`ColorRepresentation`	Color at this point

`ColorGradient` #

type ColorGradient = ColorGradientStop[];

`ParticleBlendMode` #

type ParticleBlendMode = "normal" | "additive" | "multiply" | "screen";

`ParticlePreset` #

type ParticlePreset = "fire" | "smoke" | "explosion" | "sparks" | "rain" | "snow" | "magic" | "confetti";

`BurstConfig` #

Field	Type	Default	Description
`time`	`number`	`0`	Time offset from emitter start (seconds)
`count`	`ValueRange`	—	Required. Particles to emit
`cycles`	`number`	`1`	Burst cycles. `0` = infinite
`interval`	`number`	`1`	Interval between cycles (seconds)

`SpriteSheetConfig` #

Field	Type	Default	Description
`texture`	`Texture \| string`	—	Required. Sprite sheet texture
`columns`	`number`	—	Required. Grid columns
`rows`	`number`	—	Required. Grid rows
`totalFrames`	`number`	`columns * rows`	Total frame count
`fps`	`number`	`30`	Animation speed
`startFrame`	`number`	`0`	Starting frame index
`loop`	`boolean`	`true`	Loop animation
`randomStart`	`boolean`	`false`	Randomize start frame per particle

`ParticlePropertyConfig` #

Field	Type	Default	Description
`speed`	`ValueRange`	`5`	Initial speed
`lifetime`	`ValueRange`	`1`	Lifetime in seconds
`size`	`ValueRange`	`1`	Initial scale
`rotation`	`ValueRange`	`0`	Initial rotation (radians)
`rotationSpeed`	`ValueRange`	`0`	Rotation speed (radians/sec)
`color`	`ColorRange`	`"#ffffff"`	Initial color
`alpha`	`ValueRange`	`1`	Initial opacity
`acceleration`	`[number, number, number]`	`[0, 0, 0]`	Constant acceleration
`gravity`	`number`	`0`	Downward gravity force
`drag`	`number`	`0`	Linear drag (0–1)

`OverLifetimeConfig` #

Field	Type	Description
`size`	`LifetimeCurve`	Size multiplier over lifetime
`alpha`	`LifetimeCurve`	Alpha multiplier over lifetime
`color`	`ColorGradient`	Color gradient over lifetime (replaces initial color)
`rotationSpeed`	`LifetimeCurve`	Rotation speed multiplier
`speed`	`LifetimeCurve`	Speed multiplier

`ParticleEmitterConfig` #

Field	Type	Default	Description
`name`	`string`	—	Unique name for lookups
`maxParticles`	`number`	`1000`	Max alive particles
`emission`	`"stream" \| "burst"`	`"stream"`	Emission mode
`rate`	`ValueRange`	`50`	Particles/sec (stream mode)
`bursts`	`BurstConfig[]`	—	Burst schedule
`duration`	`number`	`Infinity`	Emission duration (0 = one-shot)
`loop`	`boolean`	`true`	Loop after duration
`startDelay`	`number`	`0`	Delay before first emission
`shape`	`EmitterShapeConfig`	`{ shape: "point" }`	Emission shape
`particle`	`ParticlePropertyConfig`	—	Per-particle initial properties
`overLifetime`	`OverLifetimeConfig`	—	Over-lifetime modifiers
`blendMode`	`ParticleBlendMode`	`"normal"`	Blend mode
`texture`	`Texture \| string`	—	Particle texture
`spriteSheet`	`SpriteSheetConfig`	—	Sprite sheet config
`billboard`	`boolean`	`true`	Particles face camera
`space`	`"world" \| "local"`	`"world"`	Simulation space
`sortByDistance`	`boolean`	`false`	Sort for transparency
`autoPlay`	`boolean`	`true`	Auto-start
`onParticleBorn`	`(index: number) => void`	—	Birth callback
`onParticleDeath`	`(index: number) => void`	—	Death callback
`onComplete`	`() => void`	—	All particles died after emission stopped

`UseParticlesOptions` #

Extends ParticleEmitterConfig with:

Field	Type	Default	Description
`preset`	`ParticlePreset`	—	Base preset to merge with
`enabled`	`boolean`	`true`	Enable/disable emitter

`UseParticlesReturn` #

Field	Type	Description
`ref`	`RefObject<Object3D>`	Attach to a `<group>` for positioning
`burst(count?)`	`(number?) => void`	Emit a burst
`start()`	`() => void`	Start continuous emission
`stop()`	`() => void`	Stop emission
`clear()`	`() => void`	Stop and kill all particles
`setRate(rate)`	`(number) => void`	Change stream rate
`getActiveCount()`	`() => number`	Alive particle count
`isEmitting()`	`() => boolean`	Whether currently emitting
`reset()`	`() => void`	Reset to initial state

`ParticleEmitterProps` #

Extends ParticleEmitterConfig with:

Field	Type	Default	Description
`preset`	`ParticlePreset`	—	Base preset to merge with
`position`	`Vector3`	`[0, 0, 0]`	Emitter position
`rotation`	`Euler`	—	Emitter rotation
`enabled`	`boolean`	`true`	Enable/disable emitter

Hook Types #

Importable from @carverjs/core/hooks:

Type	Description
`UseAnimationOptions`	Options for `useAnimation` — `clipName`, `paused`, `speed`, `loop`
`UseAnimationReturn`	Return value of `useAnimation` — `ref`, `clipNames`, `activeAction`, `mixer`, `actions`, `play`, `stopAll`, `crossFadeTo`
`UseCameraOptions`	Options for `useCamera` — `follow`
`UseCameraReturn`	Return value of `useCamera` — `shake`, `moveTo`, `lookAt`
`UseGameLoopOptions`	Options for `useGameLoop` — `stage`, `fixedTimestep`, `fixedDelta`, `maxDelta`, `enabled`
`UseGameLoopReturn`	Return value of `useGameLoop` — `phase`, `isPaused`, `elapsed`
`GameLoopCallback`	Callback type for `useGameLoop`
`GameLoopStage`	Stage enum: earlyUpdate, fixedUpdate, update, lateUpdate
`GamePhase`	Phase enum: loading, playing, paused, gameover
`UseInputOptions`	Options for `useInput` — `keys`, `actions`, `enabled`
`UseInputReturn`	Return value of `useInput` — `isPressed`, `isJustPressed`, `isJustReleased`, `isAction`, `isActionJustPressed`, `getAxis`, `pointer`
`KeyState`	Key state: `pressed`, `justPressed`, `justReleased`
`PointerState`	Pointer state: `position`, `isDown`, `justDown`, `justUp`
`ActionMap`	Maps action names to key code arrays
`UseCollisionOptions`	Options for `useCollision` — `ref`, `collider`, `name`, `layer`, `mask`, callbacks
`UseCollisionReturn`	Return value of `useCollision` — `isOverlapping`, `getOverlaps`
`ColliderDef`	Collider shape definition: `AABBColliderDef \| SphereColliderDef \| CircleColliderDef`
`CollisionEvent`	Collision event data: `otherName`, `otherUserData`, `otherRef`, `isSensor`
`CollisionCallback`	Callback type for collision events
`UseGridCollisionOptions`	Options for `useGridCollision` — `config`
`UseGridCollisionReturn`	Return value of `useGridCollision` — `setCell`, `getCell`, `isCellOccupied`, etc.
`GridCollisionConfig`	Grid configuration: `width`, `height`, `cellSize`, `origin`
`UsePhysicsReturn`	Return value of `usePhysics` — `applyImpulse`, `setLinearVelocity`, `setTranslation`, etc.
`UseAudioOptions`	Options for `useAudio` — `sounds`, `enabled`
`UseAudioReturn`	Return value of `useAudio` — `play`, `stop`, `playMusic`, `setVolume`, `isUnlocked`, etc.
`SoundDefinition`	Sound config: `src`, `channel`, `volume`, `rate`, `loop`, `maxInstances`, `preload`, `sprites`, `cooldown`
`SoundMap`	Maps sound names to `SoundDefinition` objects
`PlaySoundOptions`	Per-play overrides: `volume`, `rate`, `loop`, `sprite`, `spatial`, `fadeIn`, `delay`, `onEnd`
`SoundHandle`	Handle returned by `play()` — `id`, `state`, `stop`, `pause`, `resume`, `fade`, `setVolume`, `setRate`
`SoundState`	Playback state: `"playing"`, `"paused"`, `"stopped"`
`AudioChannel`	Volume channels: `"master"`, `"sfx"`, `"music"`, `"ui"`, `"ambient"`, `"voice"`
`SpatialAudioOptions`	3D audio config: `ref`, `panningModel`, `distanceModel`, `refDistance`, `maxDistance`
`MusicOptions`	Music config: `volume`, `loop`, `crossfade`
`CrossfadeOptions`	Crossfade config: `duration`
`AudioSpriteRegion`	Sprite region: `start`, `duration`, `loop`
`AudioSpriteMap`	Maps sprite names to `AudioSpriteRegion` objects
`AudioListenerConfig`	Listener override: `listenerRef`
`AssetType`	Asset categories: `"gltf"`, `"texture"`, `"audio"`, `"json"`, `"binary"`
`AssetEntry`	Single asset definition: `url`, `key`, `type`, `priority`, `group`, `sizeHint`, `loaderOptions`
`AssetManifest`	Complete manifest: `version`, `baseUrl`, `assets`, `groups`
`AssetGroupConfig`	Group config: `label`, `preload`, `exclusive`
`LoadingProgress`	Loading state: `phase`, `loaded`, `total`, `progress`, `currentAsset`, `errors`
`AssetLoadError`	Error info: `key`, `url`, `message`, `retries`, `recoverable`
`EasingFn`	Easing function signature: `(t: number) => number`
`EasingPreset`	Named easing presets: `"linear"`, `"quad.out"`, `"bounce.in"`, `"spring"`, etc.
`EasingInput`	Easing input: `EasingPreset \| EasingFn \| [number, number, number, number]`
`TweenState`	Tween lifecycle state: `"idle"`, `"pending"`, `"delayed"`, `"playing"`, `"completed"`, `"killed"`
`TweenDirection`	Tween direction: `"forward"`, `"reverse"`
`TweenConfig`	Tween config: `target`, `to`, `from`, `duration`, `ease`, `delay`, `repeat`, `yoyo`, `speed`, callbacks
`NumberTweenConfig`	Number tween config: `from`, `to`, `duration`, `ease`, `onUpdate(value, progress)`
`TweenControls`	Tween handle: `id`, `state`, `progress`, `pause`, `resume`, `kill`, `restart`, `seek`, `chain`, `finished`
`TweenGroupControls`	Group controls: `pause`, `resume`, `kill`, `count`
`TimelineConfig`	Timeline config: `repeat`, `yoyo`, `speed`, `paused`, `ignorePause`, callbacks
`TimelineControls`	Timeline handle: `add`, `addCallback`, `addLabel`, `play`, `pause`, `kill`, `seek`, `finished`
`TimelinePosition`	Position: `number \| string` (supports `"+=0.5"`, `"-=0.2"`, `"<"`, `"label"`)
`UseTweenReturn`	Return value of `useTween` — `tween`, `tweenNumber`, `timeline`, `killAll`, `pauseAll`, `resumeAll`
`UseParticlesOptions`	Options for `useParticles` — extends `ParticleEmitterConfig` with `preset`, `enabled`
`UseParticlesReturn`	Return value of `useParticles` — `ref`, `burst`, `start`, `stop`, `clear`, `setRate`, `getActiveCount`, `isEmitting`, `reset`
`ParticleEmitterConfig`	Full emitter config: `maxParticles`, `emission`, `rate`, `shape`, `particle`, `overLifetime`, `blendMode`, `texture`, `billboard`, `space`, callbacks
`ParticlePreset`	Preset names: `"fire"`, `"smoke"`, `"explosion"`, `"sparks"`, `"rain"`, `"snow"`, `"magic"`, `"confetti"`
`EmitterShapeConfig`	Shape config: `PointShapeConfig \| ConeShapeConfig \| SphereShapeConfig \| RectangleShapeConfig \| EdgeShapeConfig \| RingShapeConfig`
`ValueRange`	Randomizable value: `number \| [number, number]`
`ColorRange`	Randomizable color: `ColorRepresentation \| [ColorRepresentation, ColorRepresentation]`
`LifetimeCurve`	Over-lifetime keyframes: `CurveKeyframe[]`
`ColorGradient`	Over-lifetime color: `ColorGradientStop[]`
`BurstConfig`	Burst schedule entry: `time`, `count`, `cycles`, `interval`
`SpriteSheetConfig`	Sprite sheet config: `texture`, `columns`, `rows`, `fps`, `loop`, `randomStart`
`ParticleBlendMode`	Blend modes: `"normal"`, `"additive"`, `"multiply"`, `"screen"`
`OverLifetimeConfig`	Over-lifetime curves: `size`, `alpha`, `color`, `rotationSpeed`, `speed`
`ParticlePropertyConfig`	Per-particle init: `speed`, `lifetime`, `size`, `rotation`, `color`, `alpha`, `acceleration`, `gravity`, `drag`

Component Prop Types #

Importable from @carverjs/core/components:

Type	Description
`GameProps`	Props for the `Game` component
`WorldProps`	Props for the `World` component
`ActorProps`	Union type: `ModelActorProps \| SpriteActorProps \| PrimitiveActorProps`
`ModelActorProps`	Props for `<Actor type="model">`
`SpriteActorProps`	Props for `<Actor type="sprite">`
`PrimitiveActorProps`	Props for `<Actor type="primitive">`
`CameraProps`	Props for the `Camera` component
`ActorPhysicsProps`	Physics configuration for an Actor
`WorldPhysicsConfig`	Physics configuration for a World
`AudioListenerConfig`	Props for the `AudioListener` component
`AssetLoaderProps`	Props for the `AssetLoader` component
`LoadingScreenProps`	Props for the `LoadingScreen` component
`ParticleEmitterProps`	Props for the `ParticleEmitter` component — extends `ParticleEmitterConfig` with `preset`, `position`, `rotation`, `enabled`

Types

Game & World Types #

Actor Types #

ActorTransformProps #

ActorEventProps #

PrimitiveShape #

PrimitiveMaterialType #

Camera Types #

CameraFollowConfig #

UseCameraOptions #

UseCameraReturn #

Game Loop Types #

UseGameLoopOptions #

UseGameLoopReturn #

Input Types #

KeyState #

PointerState #

ActionMap #

UseInputOptions #

UseInputReturn #

Collision Types (Built-in) #

ColliderShape #

ColliderDef #

AABBColliderDef #

SphereColliderDef #

CircleColliderDef #

CollisionEvent #

CollisionCallback #

UseCollisionOptions #

UseCollisionReturn #

Grid Collision Types #

GridCollisionConfig #

GridCellCallback #

UseGridCollisionOptions #

UseGridCollisionReturn #

Physics Types (Rapier-backed) #

RigidBodyType #

PhysicsColliderType #

WorldPhysicsConfig #

ActorPhysicsProps #

UsePhysicsReturn #