useCamera

Provides imperative camera controls — shake, smooth transitions, and look-at. Used internally by the Camera component, but available directly for advanced use cases.

You typically don't need this hook directly — the `Camera` component exposes the same API via its `onReady` callback. Use this hook when you need camera control outside of a `Camera` component.

Import #

tsx

import { useCamera } from "@carverjs/core/hooks";

Signature #

function useCamera(options?: UseCameraOptions): UseCameraReturn;

Parameters #

Parameter	Type	Description
`options`	`UseCameraOptions`	Optional configuration

`UseCameraOptions` #

Field	Type	Description
`follow`	`CameraFollowConfig`	Follow a target object. See Camera — CameraFollowConfig

Return Value (`UseCameraReturn`) #

Method	Signature	Description
`shake`	`(intensity?: number, duration?: number) => void`	Trigger a camera shake. Default: intensity `0.3`, duration `0.3s`
`moveTo`	`(position: [x, y, z], duration?: number) => void`	Smoothly transition to a position. Default duration: `1s`. Uses smooth-step easing
`lookAt`	`(target: [x, y, z]) => void`	Immediately point the camera at a world position

Usage #

Shake on hit #

tsx

const { shake } = useCamera();

function onPlayerHit() {
  shake(0.5, 0.3);
}

Cinematic pan #

tsx

const { moveTo, lookAt } = useCamera();

function startCutscene() {
  moveTo([10, 5, 0], 2); // glide to position over 2 seconds
  lookAt([0, 0, 0]);      // look at the origin
}

Follow a player #

tsx

const playerRef = useRef<Group>(null);

const { shake } = useCamera({
  follow: {
    target: playerRef,
    offset: [0, 8, 12],
    smoothing: 0.05,
  },
});

Type Definitions #

See Types for UseCameraOptions, UseCameraReturn, and CameraFollowConfig.