Actor

An Actor is any renderable entity you place in a scene. Every actor shares a common set of transform and event props, but the type field determines what gets rendered:

import { Actor } from "@carverjs/core/components";

Choosing an Actor Type #

Not sure which type to use? Here's a guide.

Model (type: "model") #

Loads a pre-made 3D model file (.glb / .gltf) created in tools like Blender, Maya, or downloaded from asset stores.

Use for: Complex, detailed 3D objects — characters, buildings, vehicles, weapons, furniture. Anything that has detailed geometry, textures, and potentially skeletal animations baked into the file.

<Actor type="model" src="/character.glb" animationName="idle" />

• Full 3D with complex geometry and textures from the file

• Supports built-in skeletal animations (walk, idle, attack cycles)

• Requires an external .glb/.gltf asset file

• Heaviest option (file download + GPU resources)

Sprite (type: "sprite") #

A flat 2D image (.png, .jpg) rendered in the 3D/2D world. Sprites come in three flavours:

• Static — a single image displayed as-is

• Grid-based animation — a spritesheet image where all frames are arranged in a grid (no extra files needed)

• Atlas-based animation — a spritesheet image paired with a JSON atlas that describes each frame's position and size

Use for: 2D games, UI elements in 3D space, particle-like effects, trees/foliage in retro-style games, health bars, damage numbers. Think classic 2D game characters or "billboard" elements that always face the camera.

// Static image
<Actor type="sprite" src="/tree.png" />

// Grid-based animated spritesheet (image only, no JSON needed)
<Actor
  type="sprite"
  src="/character-run.png"
  spriteAnimation={{ numberOfFrames: 10, fps: 8, loop: true }}
/>

// Atlas-based animated spritesheet (image + JSON atlas)
<Actor
  type="sprite"
  src="/player.png"
  atlasUrl="/player.json"
  spriteAnimation={{ fps: 12, loop: true }}
/>

• Flat 2D image, no 3D depth

• Optionally billboards (always faces camera) — great for 2D characters in 3D worlds

• Two animation methods: grid-based (just an image) or atlas-based (image + JSON)

• Lighter than models, requires image assets

Primitive (type: "primitive") #

A basic geometric shape (box, sphere, cylinder, etc.) generated entirely by code — no external files needed.

Use for: Prototyping, debug visuals, simple game objects (platforms, walls, collectible orbs, ground planes), placeholder art during development, or minimalist/abstract game styles.

<Actor type="primitive" shape="sphere" color="red" />
<Actor type="primitive" shape="box" wireframe color="lime" />

• No asset files needed — pure code

• 9 shapes: box, sphere, cylinder, cone, torus, plane, circle, capsule, ring

• 5 material types with color, wireframe, and opacity control

• Lightest option, instant rendering

• No animation support (geometry only)

At a Glance #

Quick Start #

A few copy-paste examples to get you going.

Primitive — a red box #

<Actor type="primitive" shape="box" color="#ff0000" position={[0, 1, 0]} castShadow />

Model — a character with an animation #

<Actor type="model" src="/models/character.glb" animationName="Idle" position={[0, 0, 0]} />

Sprite — a billboard tree #

<Actor type="sprite" src="/textures/tree.png" position={[3, 1, 0]} billboard />

Sprite — grid-based animated spritesheet #

If your spritesheet is a single image with frames arranged in a grid, just pass spriteAnimation with a numberOfFrames count. CarverJS automatically calculates the rows and columns from the image dimensions.

<Actor
  type="sprite"
  src="/sprites/hero-run.png"
  spriteAnimation={{ numberOfFrames: 10, fps: 8, loop: true }}
/>

Sprite — atlas-based animated spritesheet #

If you have a JSON atlas file (exported from tools like TexturePacker or Aseprite), pass it via atlasUrl alongside the spritesheet image.

<Actor
  type="sprite"
  src="/sprites/hero.png"
  atlasUrl="/sprites/hero.json"
  spriteAnimation={{ fps: 12, loop: true, autoPlay: true }}
/>

Props Reference #

Actor is a discriminated union on the type field. All three variants share a common base of transform, visibility, and event props.

Common Props #

These apply to every actor regardless of type.

Event Props #

All R3F pointer, click, and wheel events are supported:

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

Model Props #

Additional props when type is "model".

Sprite Props #

Additional props when type is "sprite".

How Sprites Render #

The combination of atlasUrl and spriteAnimation determines what gets rendered:

spriteAnimation Fields #

Primitive Props #

Additional props when type is "primitive".

Available Shapes #

Available Material Types #

Physics Props #

When the parent World has a physics prop, you can add physics to individual Actors via the physics prop. The Actor is wrapped in a Rapier <RigidBody>.

<Actor
  type="primitive" shape="box" color="red" position={[0, 5, 0]}
  physics={{ bodyType: "dynamic", mass: 2, restitution: 0.5 }}
/>

Ref #

Actor forwards a ref to its root <group>, giving you direct access to the Three.js object for imperative control:

const actorRef = useRef<Group>(null);
<Actor ref={actorRef} type="primitive" shape="sphere" />

Type Definitions #

See Types for all type definitions including ActorProps, ModelActorProps, SpriteActorProps, PrimitiveActorProps, ActorTransformProps, ActorEventProps, ActorPhysicsProps, PrimitiveShape, and PrimitiveMaterialType.