A lib of helper functions to animate sprites with R3Fiber.
A lib of helper functions to animate sprites with R3Fiber.
R3Fiber is necessary on your project to use the functionality of this library.
yarn add sprite-three-animation
useRef()
If the sprite is bigger than
32px
pass an option object with the tileSize as a number or an array of numbers for width and height (for example. 64 or [32, 64])
More complex animations are also supported:
{
port?: { x?: number; y?: number;};
move?: { x?: number; y?: number;};
tileid?: number;
duration: number;
}[]
call the animation function inside of useFrame
from R3Fiber passing the delta to the animation
enjoy!
import { createAnimation } from 'sprite-three-animation';
import { useFrame, useLoader } from '@react-three/fiber';
import { useRef } from 'react';
function Box(props) {
// Load the spriteSheet texture
const texture = useLoader(THREE.TextureLoader, '/skullMonkey.png');
// Get the ref of the Sprite
const sprite = useRef();
// Create your animation passing the array of frames
const animation = createAnimation(sprite, [10, 12, 13, 14, 15, 16, 17], {
tileSize: 64,
});
useFrame((clock, delta) => {
/*
You can pass a boolean as second argument to control the activation of the animation. see type options for more info.
for example:
const control: boolean = isUpKeyPressed()
animation(delta, control)
*/
animation(delta); // Call the animation function inside of useFrame from R3Fiber
});
return (
<sprite {...props} ref={sprite}>
<spriteMaterial attach="material" map={texture} />
</sprite>
);
}
tileSize?: number | [number number]
Size in pixels of a tile in the Sprite Sheet
Tile size in pixels [<size for x>,<size for y>]
, single number is shorthand for square tiles.
If undefined defaults to tileSize: "32"
frameDuration?: number
Number in milliseconds for the duration of each sprite in the animation
💥 Use this option only with number[]
animations
If undefined defaults to frameDuration: "100"
constantMove?: { x?: number; y?: number;}
Sprite position update on every frame, accept negative numbers too.
If undefined defaults to { x: 0, y: 0 }
type?: 'single onPress' | 'single' | 'loop'
Type of animation:
loop
: the animation will loop infinite time. If control is passed to false the animation will stop.
single
: the animation do a single loop and stop (currently only working with complex animations)
single onPress
: the animation do a single loop but only while the control argument to the animation function call in useFrame
is passed as true. (currently only working with complex animations)
The animation will stop after a single loop and only being restarted until the control is set to false and true again.
if undefined defaults to type: "loop"
quickStart?: boolean
💥 Not compatible with number[]
animations, if this feature is needed use a complex animation array.
Set the animation to call the first animation step immediately instead of wait the first time duration, if true
the first step duration will be ignored. *
if undefined defaults to quickStart: "false"
type GameAnimationStep = {
port?: {
x?: number;
y?: number;
};
move?: {
x?: number;
y?: number;
};
tileid?: number;
duration: number;
};
type GameSpriteAnimation = GameAnimationStep[];
type AnimationOptions<T extends number[] | GameSpriteAnimation> = {
/** Tile size in pixels `[<size for x>,<size for y>]`, single number is shorthand for square tiles.
*
* if undefined defaults to `tileSize: "32"`
*/
tileSize?: number | [number, number];
/** if undefined defaults to `frameDuration: "100"`
*
* 💥 Use this option only with `number[]` animations
*/
frameDuration?: T extends number[] ? number : never;
/** Sprite position update on every frame, accept negative numbers too.
*
* if undefined defaults to `{ x: 0, y: 0 }`
*/
constantMove?: {
x?: number;
y?: number;
};
/** Type of animation modifying how the function interacts with control,
*
* if undefined defaults to `type: "loop"`
*
* 💥 Not compatible with `number[]` animations,
* for "single" and "single onPress" use a complex animation array.
*/
type?: 'single onPress' | 'single' | 'loop';
/** Set the animation to call the first animation step immediately instead of wait the first time duration, if `true` the first step duration will be ignored.
*
* if undefined defaults to `quickStart: "false"`
*
* 💥 Not compatible with `number[]` animations, if this feature is needed use a complex animation array.
*/
quickStart?: T extends GameSpriteAnimation ? boolean : never;
};
NOTE: I understand this DOCS are incomplete, they are a work in progress. Thanks for understand.