@carverjs/core

@carverjs/core

The CarverJS game engine — build declarative 2D and 3D games as composable React components, on top of Three.js and React Three Fiber.

Beta: CarverJS is under active development. APIs may change between minor versions until 1.0.

Install

npm install @carverjs/core
# peer dependencies (most React + Three projects already have these)
npm install react react-dom three @react-three/fiber @react-three/drei zustand
# optional — rigid-body physics (usePhysics, powered by Rapier)
npm install @react-three/rapier

Quick start

A complete 2D game — a circle you move with WASD:

import { useRef } from "react";
import { Game, World, Actor } from "@carverjs/core/components";
import { useGameLoop, useInput } from "@carverjs/core/hooks";

function Player() {
  const ref = useRef(null);
  const { getAxis } = useInput();

  useGameLoop((dt) => {
    if (!ref.current) return;
    ref.current.position.x += getAxis("KeyA", "KeyD") * 5 * dt;
    ref.current.position.y += getAxis("KeyS", "KeyW") * 5 * dt;
  });

  return (
    <Actor ref={ref} type="primitive" shape="circle" color="royalblue"
      geometryArgs={[0.5, 24]} />
  );
}

export default function App() {
  return (
    <Game mode="2d">
      <World>
        <Player />
      </World>
    </Game>
  );
}

Switch to 3D by changing a single prop: <Game mode="3d">.

Entry points

@carverjs/core ships as focused subpath exports, so you import only what you use:

Import	Contents
@carverjs/core/components	<Game>, <World>, <Actor>, <Camera>, <Scene>, <SceneManager>, <AssetLoader>, <LoadingScreen>, <ParticleEmitter>, <AudioListener>
@carverjs/core/hooks	game loop, input, collision, physics, camera, animation, audio, assets, particles, tweening
@carverjs/core/systems	engine systems — actor registry, asset / audio / collision managers, easing
@carverjs/core/store	Zustand stores (gameStore, sceneStore)
@carverjs/core/types	shared TypeScript types

Components

Component	Purpose
<Game>	Root canvas. Set mode to 2d or 3d; configure lighting, sky, DPR, and shadows.
<World>	Scene-graph container for your actors.
<Actor>	A game object — primitive, sprite, or model. Forwards a ref to its Object3D.
<Camera>	Perspective or orthographic camera with optional follow controls.
<Scene> / <SceneManager>	Multi-scene apps and transitions.
<AssetLoader> / <LoadingScreen>	Preload models, textures, and audio behind a loading screen.
<ParticleEmitter>	Particle effects.
<AudioListener>	Spatial audio listener.

Hooks

Hook	Purpose
useGameLoop(cb)	Fixed / variable-step update loop with delta time.
useInput()	Keyboard and pointer state, axes, and action maps.
useCollision() / useGridCollision()	AABB / sphere / circle and grid collision.
usePhysics()	Rigid-body physics (requires the optional @react-three/rapier peer).
useCamera() / useCameraDirection()	Camera control and facing.
useAnimation()	Skeletal and clip animation playback.
useAudio()	Sound effects and music with channels and audio sprites.
useAssets() / useAssetProgress()	Access loaded assets and load progress.
useParticles()	Imperative particle bursts.
useTween()	Value tweening with easing.
useScene()	Scene navigation.
useActorRegistry()	Look up live actors by id.

Add multiplayer

Make any CarverJS game networked with @carverjs/multiplayer — serverless peer-to-peer over WebRTC, with no game server to run.

Links

• Documentation: docs.carverjs.dev
• Community: Discord
• Issues: github.com/MoneyTales/carverjs/issues

License

MIT — MoneyTales EduTech Private Limited