This package provides a React implementation of a low-level 2D tilemap board optimized for high-performance rendering in web browsers.
It pretends to be the graphic engine of games or applications where you need to paint a grid map with sprites, operate with a camera and position elements on it.
- Written entirely in typescript.
- Designed for React developers.
- Minimal dependencies.
- Designed to have animations and motions.
npm i react-super-tilemap
// OR
yarn add react-super-tilemap
Mainly you will need to define the set of sprites that the map will render. These sprites can be oriented to different purposes and have configurations so you can adapt them according to your needs.
Each sprite will need a unique key, it is important that they are not repeated to avoid overlapping.
import { SpriteDefinition } from 'react-super-tilemap'
// Tip: any string you could pass to an <image src={...} /> is a valid imageSrc
const grass = '{ path to your sprite image }'
const sprites: SpriteDefinition[] = [
{
key: 'grass',
imageSrc: [grass],
},
...
]When you need a sprite to have an animation, you have the possibility to declare an array of imageSrc and the animationDelay field where you can adjust the transition time between images in milliseconds.
It is important that each of the images have the same size, otherwise the tilemap will throw an exception on the initial load of the sprite definition.
const sprites: SpriteDefinition[] = [
...
{
key: 'ocean',
imageSrc: [ocean_1, ocean_2, ocean_3, ocean_4],
animationDelay: 400
}
]You can declare oversized sprites with the property size when you have sprites that stick out of the tile grid.
const sprites: SpriteDefinition[] = [
...
{
key: 'building',
imagesSrc: [building_1, building_2],
animationDelay: 800,
size: {
width: 1,
height: 2,
},
},
]You can declare offseted sprites with the property offset when you have sprites that you want to fix the anchor point.
const sprites: SpriteDefinition[] = [
...
{
key: 'selector',
imagesSrc: [selector2, selector1],
animationDelay: 800,
size: {
width: 2,
height: 2,
},
offset: {
col: -0.5,
row: 0.5,
},
},
]This is the main component to start painting in your React application 2D tilemaps.
import { Tilemap, SpriteDefinition } from 'react-super-tilemap'
const sprites: SpriteDefinition[] = [...]
const scheme: string[][][] = [
[
['ocean'],
['ocean'],
],
[
['grass'],
['grass'],
]
]
const YourComponent = () => (
<Tilemap
tilmapScheme={scheme}
spriteDefinition={sprites}
>
...
</Tilemap>
)This component is used to manually control the camera position and zoom of the tilemap.
import { Tilemap, ManualCamera } from 'react-super-tilemap'
const position = {
col: 0,
row: 0,
}
const zoom = 0;
const YourComponent = () => {
return (
<Tilemap
tilmapScheme={scheme}
spriteDefinition={sprites}
>
<ManualCamera
position={position}
zoom={zoom}
/>
</Tilemap>
)
}Use this component to operate with a third person camera in the tilemap.
Here you can forget about control the camera position and zoom because this component will do it for you enabling drag and zoom controls by default.
It is important that multiple cameras are not added between the Tilemap children.
import { Tilemap, ThirdPersonCamera } from 'react-super-tilemap'
const YourComponent = () => {
return (
<Tilemap
tilmapScheme={scheme}
spriteDefinition={sprites}
>
<ThirdPersonCamera />
</Tilemap>
)
}Third person camera allows you to apply motion effects to the position and zoom. To do this you just have to create a child component and use the useThirdPersonCameraContext hook.
import { Tilemap, ThirdPersonCamera, useThirdPersonCameraContext } from 'react-super-tilemap'
const CameraControls = () => {
const {
addZoomMotion,
} = useThirdPersonCameraContext();
const resetZoom = () => addZoomMotion(motionSettings, 0);
return (
<button onClick={resetZoom}>Reset zoom</buttton>
);
}
const YourComponent = () => {
return (
<Tilemap
tilmapScheme={scheme}
spriteDefinition={sprites}
>
<ThirdPersonCamera>
<CameraControls />
</ThirdPersonCamera>
</Tilemap>
)
}To include dynamic elements to the scene you can add child components to Tilemap such as the following that are provided:
Similar as ManualCamera, you can use add a ManualElment as a child of a Tilemap. Using this component you have full control of the position of the element on the map.
const YourComponent = () => {
return (
<Tilemap
tilmapScheme={scheme}
spriteDefinition={sprites}
>
<ThirdPersonCamera />
<ManualElement
elementKey="element1"
spriteKey="armyIdle"
layer={1}
tilePosition={{
x: 0,
y: 0,
}}
/>
</Tilemap>
)
}With this component you can have relative control over the position keeping you out of everything related to element motions. Just sends props with the position where the element is and, in case of possible changes, these will be done with the given motion configuration.
const YourComponent = () => {
return (
<Tilemap
tilmapScheme={scheme}
spriteDefinition={sprites}
>
<ThirdPersonCamera />
<MotionableElement
tilePosition={{
x: elementCol,
y: elementRow,
}}
spriteKey={elementSprite}
layer={1}
elementKey='element1'
motionSettings={{
speed: motionSpeed,
easing: 'linear',
}}
>
{/* Children JSX */}
<label> Element 1 </label>
</MotionableElement>
</Tilemap>
)
}