README.md

🚨 I don't have time to maintain this package. I am open to PRs. 🚨

rn-sprite-sheet

A sprite sheet animation library for React Native

Install

npm install --save rn-sprite-sheet

Import

import SpriteSheet from 'rn-sprite-sheet';

Usage

1. Create ref for SpriteSheet
2. Set the source using require() for local asset images or using { uri: <image's url>, width: <image's width>, height: <image's height> } for network images
3. Specify the columns and rows (each frame must be the same size)
4. Create animations object (each key is an animation name and their value should be an array of frame indexes)
5. Play an animation by calling the play method on a SpriteSheet reference and pass it a config object with at least a type property

Example

<SpriteSheet
  ref={ref => (this.mummy = ref)}
  source={require('./assets/mummy.png')}
  columns={9}
  rows={6}
  // height={200} // set either, none, but not both
  // width={200}
  // frameHeight={50} // manually set size of your sprite
  // frameWidth={50} // overrides auto calculation of frame size based on height, width, columns, and rows.
  // offsetX={0}
  // offsetY={0}
  imageStyle={{ marginTop: -1 }}
  animations={{
    walk: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17],
    appear: Array.from({ length: 15 }, (v, i) => i + 18),
    die: Array.from({ length: 21 }, (v, i) => i + 33),
  }}
/>;
// ...
play = config => this.mummy.play(config);

Methods

To be called on a SpriteSheet reference

play({
  type, // (required) name of the animation (name is specified as a key in the animation prop)
  fps = 24, // frames per second
  loop = false, // if true, replays animation after it finishes
  resetAfterFinish = false, // if true, the animation will reset back to the first frame when finished; else will remain on the last frame when finished
  onFinish = () => {} // called when the animation finishes; will not work when loop === true
})

stop(callback) // stop at current frame

reset(callback) // stop and go to first frame

Props

static propTypes = {
  source: sourcePropType.isRequired // source must be required
  columns: PropTypes.number.isRequired,
  rows: PropTypes.number.isRequired,
  animations: PropTypes.object.isRequired, // see example
  viewStyle: stylePropType, // styles for the sprite sheet container
  imageStyle: stylePropType, // styles for the sprite sheet
  height: PropTypes.number, // set either height, width, or none,
  width: PropTypes.number, // but not both height and width
  onLoad: PropTypes.func,
  frameWidth: PropTypes.func, // overrides sprite size calculation based on height,width,rows,columns props
  frameHeight: PropTypes.func, // both frameWidth and frameHeight must be set or neither
  offsetX: PropTypes.func, // used with frameWidth/frameHeight to adjust offset of first frame
  offsetY: PropTypes.func
};

static defaultPropTypes = {
  columns: 1,
  rows: 1,
  animations: {}
};

Sprite sheet image specifications

When generating a sprite sheet image to use with rn-sprite-sheet, ensure that the frames are all of the same dimensions, and that the overall image size is exactly the height of all rows and the width of all columns. Depending on the tool you use to generate your sprite sheet image, you may need to crop the source image.