@characterxyz/three-character

Easily integrate characters from character.xyz into your react-three/fiber scene.

Promo

Click on the image above to watch the promo video.

Installation

Add the character library to your project using npm or yarn:

npm:

npm install @characterxyz/three-character

yarn:

yarn add @characterxyz/three-character

Setup

1. Import the Character

Firstly, you'll need to import the Character from the library:

import { Character } from '@characterxyz/three-character';

2. Create Your Customized Character Component

Set up your character in a React component:

<Character
  config={{
    scene: scene as any,
    slug: 'Tamashi-TiAJWr3sWxh79UKd1UDU',
    groundLayer: GROUND_LAYER,
  }}
/>

Note: i) When you leave the slug empty, we load the default Tamashi Character. You can also pass the slug with the actual character slug from character.xyz Eg: Tamashi's Slug - "Tamashi-TiAJWr3sWxh79UKd1UDU" ii) Ground layer is needed for the character to determine where to land when the character jumps r falls off from a cliff. we recommend setting a layer value that is different from the default layer to avoid testing with every visible object.

3. Add the Customized Character to Your Scene

Place your character into the canvas or game scene:

<Canvas style={{ display: 'block' }}>
  <ambientLight intensity={0.5} />
  <directionalLight position={[0, 10, 0]} intensity={0.5} />
  <mesh position={[0, 0, 0]} rotation={[-Math.PI / 2, 0, 0]}>
    <planeGeometry args={[10, 10]} />
    <meshStandardMaterial color="gray" />
  </mesh>
  <PlayerCharacter />
  <OrbitControls />
</Canvas>

Full Playground Example

Here's a full example of setting up a playground with a character:

import { Canvas } from '@react-three/fiber';
import { OrbitControls } from '@react-three/drei';
import { Character } from '@characterxyz/three-character';

function PlayerCharacter() {
  const { scene } = useThree();
  return <Character config={{ scene: scene, slug: '' }}></Character>;
}

export default function Playground() {
  return (
    <div
      style={{
        width: '100vw',
        height: '100vh',
        position: 'fixed',
        top: 0,
        left: 0,
        zIndex: 0,
      }}
    >
      <Canvas style={{ display: 'block' }}>
        <ambientLight intensity={0.5} />
        <directionalLight position={[0, 10, 0]} intensity={0.5} />
        <mesh position={[0, 0, 0]} rotation={[-Math.PI / 2, 0, 0]}>
          <planeGeometry args={[10, 10]} />
          <meshStandardMaterial color="gray" />
        </mesh>
        <PlayerCharacter />
        <OrbitControls />
      </Canvas>
    </div>
  );
}

Starter Project

To try more of our starter projects, please visit our github page - https://github.com/characterxyz/threejs-starter

Custom Characters

To explore the full catalogue of characters and load them using their slug, please visit character.xyz