README

Iceoh

A tiny, 0 dependency JS library for isometric and 2d tilemaps

Features

Small, flexible, and fast
Modern and fully typed
Supports stacking tiles at different sizes and depths
Unopinionated. Built with pixi.js in mind, should will work anywhere.
Good enough

Installation

yarn add iceoh

Quick Start

For more complete examples that use pixi.js, see the examples' source

The following example is a naive vanilla example with canvas, to illustrate core concepts.

import { Tilemap, IsoTilemap, TOP_LEFT, MIDDLE, CLASSIC, getDirection, DIRECTION, getDistance } from 'iceoh'

// This can be anything, PIXI.Sprite, Phaser.Sprite, whatever your tile object is.
class Sprite {
  width: number
  height: number
  image: CanvasImageSource
}

const canvas = document.getElementById('canvas')
const ctx = canvas.getContext('2d')

// 2d Tilemap
const map = new Tilemap<Sprite>({
  getGlobalDimensions: () => canvas.getBoundingClientRect(),
  getWorldPosition: () => ({ x: 0, y: 0 }),
  getWorldScale: () => ({ x: 1, y: 1 }),
  worldOrigin: TOP_LEFT,
  baseOrigin: MIDDLE,
  baseTileDimensions: {
    width: 64,
    height: 64
  }
})

const map = new IsoTilemap<Sprite>({
  getGlobalDimensions: () => canvas.getBoundingClientRect(),
  getWorldPosition: () => ({ x: 0, y: 0 }),
  getWorldScale: () => ({ x: 1, y: 1 }),
  worldOrigin: MIDDLE,
  baseOrigin: MIDDLE,
  projectionAngle: CLASSIC,
  baseTileDimensions: {
    width: 64,
    height: 64,
    depth: 32 // how many pixels tall is the front edge of the tile
  }
})

let sprite = new Sprite()

// takes grid coordinates and returns screen space coordinates to draw your sprite at
// the returned z coordinate is helpful if you're using a library with depth sorting
let { x, y, z } = map.add(sprite, { x: 0, y: 0, z: 0 })
ctx.drawImage(sprite.image, x, y, sprite.width, sprite.height)

// Move existing sprite to a new spot in the map, then draw the sprite in the new location
ctx.clearRect(x, y, sprite.width, sprite.height)
{ x, y, z } = map.move({ x: 0, y: 0, z: 0 }, { x: 1, y: 1, z: 0 })
ctx.drawImage(sprite.image, x, y, sprite.width, sprite.height)

// Get a sprite at map coordinates
map.get({ x: 1, y: 1, z: 0 }) === sprite // true

// Remove the tile at map coordinates and return it
map.remove({ x: 1, y: 1, z: 0 }) === sprite // true

// Get an array of all tiles at a given x,y
map.add(z0Sprite, { x: 2, y: 2, z: 0 })
map.add(z1Sprite, { x: 2, y: 2, z: 1 })
map.add(z2Sprite, { x: 2, y: 2, z: 2 })
const [z0Sprite, z1Sprite, z2Sprite] = map.getColumn<Sprite>({ x: 2, y: 2 })

// You can also get a column of tile depths if using IsoTilemap
const [z0Depth, z1Depth, z2Depth] = map.getColumn<number>({ x: 2, y: 2 }, map.depthMap)

// Get map coordinate from a screen point
{ x, y } = map.toTile({ x: mouse.x, y: mouse.y })
// and get world coordinates for an arbitrary map position
{ x: worldX, y: worldX } = map.toPoint({ x, y })

// Get a world position with a given map position at its center
{ x: worldX, y: worldX } = map.centerToTile({ x, y })

// Get the map dimensions, x/y being center tile coordinates
// width being max X, and height being max Y tile values
const { x, y, width, height, depth } = map.getBounds()

// Center viewport to center of map
{ x: worldX, y: worldX } = map.center()
// is the same as
{ x: worldX, y: worldX } = map.centerToTile(map.getBounds())

// Get the facing direction between two points
getDirection({ x: 1, y: 1 }, {x: 1, y: 0 }) === DIRECTION.N
getDirection({ x: 1, y: 1 }, {x: 2, y: 0 }) === DIRECTION.NE
getDirection({ x: 1, y: 1 }, {x: 2, y: 1 }) === DIRECTION.E
getDirection({ x: 1, y: 1 }, {x: 2, y: 2 }) === DIRECTION.SE
getDirection({ x: 1, y: 1 }, {x: 1, y: 2 }) === DIRECTION.S
getDirection({ x: 1, y: 1 }, {x: 0, y: 2 }) === DIRECTION.SW
getDirection({ x: 1, y: 1 }, {x: 0, y: 1 }) === DIRECTION.W
getDirection({ x: 1, y: 1 }, {x: 0, y: 0 }) === DIRECTION.NW

// get the distance between two points
const num = getDistance({ x: 1, y: 1 }, { x: 5, y: 5}) // num = ~5

Prior Art

This library could not exist without the following libraries, which were not quite in the Goldilocks zone of what I wanted. If Iceoh sucks, try one of these!

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

Contributions are welcome.

Developing

git clone https://github.com/sammccord/iceoh.git
cd iceoh

# deps
yarn

# build
yarn build

# develop
yarn dev

# To develop via examples
cd example && yarn dev
open http://localhost:1234

Usage no npm install needed!