README.md

use-spritesheet is a set of hooks to use pixel art, spritesheets and Aseprite with react-three-fiber in just a few lines of code.

👁  Live Demo (source in example)

Installation

npm i use-spritesheet

yarn add use-spritesheet

API

usePixelTexture

A small time-saver if you want crisp pixels on a texture, sets the texture filter to nearest-neighbour and (optionally) enables wrapping.

import frogSrc from './resources/frog.png';

const PixelTexture = () => {
  const tex = usePixelTexture(frogSrc);

  return (
    <sprite>
      <spriteMaterial transparent map={tex} />
    </sprite>
  );
};

useSpritesheet

Perfect for when you have a spritesheet and want to slice out a single frame to display statically (such as an icon from a icon set).

import smileySrc from './resources/smiley_idle.png';

const SpritesheetSingleFrame = () => {
  // 1 row
  // 8 columns
  // display frame index 2
  const tex = useSpritesheet(smileySrc, 1, 8, 2);

  return (
    <sprite>
      <spriteMaterial transparent map={tex} />
    </sprite>
  );
};

useSpritesheetAnimation

Play a series of frames that are baked into a single texture, ideal for particle effects.

import impSrc from './resources/impo.png';

const SpritesheetAnimation = ({ paused }: { paused: boolean }) => {
  // 100ms per frame
  // 2 rows
  // 4 columns
  const [tex] = useSpritesheetAnimation(impSrc, 100, 2, 4, paused);

  return (
    <sprite>
      <spriteMaterial transparent map={tex} />
    </sprite>
  );
};

useAsepriteAnimation

Import a texture + json file exported from Aseprite, select which animation to play and control playback speed.

import gremlin from "./resources/bomber.png";
import gremlinJson from "./resources/bomber.json";

export const AsepriteAnimation = ({
  animation = "idle",
  paused,
}: any) => {
  const [texture] = useAseprite(
    gremlin,
    gremlinJson as AsepriteJson,
    animation, // Changing this parameter automatically switches animations
    paused
  );

  return (
    <sprite>
      <spriteMaterial transparent map={texture} />
    </sprite>
  );
};

Running this repo

We make use of yarn workspaces to develop the example alongside the library itself.

Bootstrap

yarn

Running the examples

cd use-spritesheet
yarn build
cd ../example
yarn start