The renderer-agnostic engine: camera, coordinate math, gestures, layers, and the draw API. Every other package builds on core.
Classes
CanvasTileEngine
class
The core engine. Wires the camera, config, renderer, events, and draw helpers together. Generic over the mount target and image type so the same class powers DOM, React Native, and server renderers.
rendererIRenderer<TMount, TImage>Renderer implementation, e.g. new RendererCanvas().
center?CoordsInitial center in world space. Default { x: 0, y: 0 }.
Example
import { CanvasTileEngine } from "@canvas-tile-engine/core";
import { RendererCanvas } from "@canvas-tile-engine/renderer-canvas";
const engine = new CanvasTileEngine(
document.getElementById("map-wrapper"),
{ scale: 50, size: { width: 800, height: 600 } },
new RendererCanvas(),
{ x: 0, y: 0 }
);
engine.drawGridLines(1);
engine.render();
SpriteSheet
class
Grid-based spritesheet frame calculator. Maps (col, row) or linear frame indices to pixel source rectangles inside a sheet image. Pure calculation — holds no image reference, so it works with every renderer.
Plays a SpriteAnimation by invoking a callback whenever the current frame changes. The internal rAF loop only fires when the frame index advances, so renders happen at the animation's fps, not at 60fps.
Spatial indexing wrapper using an R-Tree for fast viewport queries. Used internally for viewport culling of large item sets (500+); exposed for advanced custom querying.
Normalizes and stores engine configuration with safe defaults. get() returns a deeply frozen snapshot — do not mutate it. Mostly used internally; renderers receive it via RendererDependencies.
Holds the mutable viewport size for runtime changes (resize, layout) and tracks device pixel ratio for HiDPI/Retina rendering.
class ViewportState {
constructor(width: number, height: number)
getSize(): { width: number; height: number }
setSize(width: number, height: number): void
get dpr(): number
updateDpr(): void
}
GestureProcessor
class
Handles gesture logic (click, hover, drag, zoom, pinch) independent of DOM/platform. Renderers feed it normalized pointer input; it performs the camera math and fires the engine callbacks.
Manages smooth animations for camera movements and canvas resizing, including animation frame scheduling and cleanup. Backs engine.goCoords and engine.resize.
Draw rectangles with a pre-rendering cache: items render once to an offscreen canvas, then the visible portion is blitted each frame. Ideal for large static datasets like minimaps.
Register a custom draw function for complete rendering control. The context type depends on the renderer (CanvasRenderingContext2D on the web, SkCanvas on Skia).
Clear all draw callbacks from all layers for a complete scene reset.
clearAll(): void
Event Callbacks
onClick
event
Fired when a tile is clicked (mouse or touch tap). coords is in world space, mouse is canvas-relative, client is viewport-relative; raw is exact, snapped is floored to the tile.
The engine configuration. scale is pixels per world unit; gridAligned snaps center coordinates to cell centers for pixel-perfect alignment; responsive controls how the canvas reacts to container resizes; debug enables an FPS/coords HUD.
Anchor point for wheel/pinch zoom: "pointer" zooms toward the cursor or pinch midpoint, "center" toward the canvas center.
type ZoomMode = "pointer" | "center"
Coords
type
A point in world or screen space.
type Coords = { x: number; y: number }
DrawObject
type
Base shape for drawable items. Position and size are in world units; origin controls the anchor point within the cell or the item itself.
type DrawObject = {
x: number
y: number
size?: number
origin?: { mode?: "cell" | "self"; x?: number; y?: number }
style?: { fillStyle?: string; strokeStyle?: string; lineWidth?: number }
rotate?: number // degrees, positive = clockwise
radius?: number | number[] // px; single or [tl, tr, br, bl]
}
Rect / Circle
type
Rect is a full DrawObject; Circle drops rotation and radius (circles need neither).
type Rect = DrawObject
type Circle = Omit<DrawObject, "rotate" | "radius">
Text
type
A text item drawn at a world position with zoom-scaled font size.
type Text = Omit<DrawObject, "radius" | "size"> & {
text: string
size?: number // font size in world units (scales with zoom), default 1
style?: {
fillStyle?: string
fontFamily?: string
textAlign?: TextAlign
textBaseline?: TextBaseline
}
}
Line / Path
type
A single segment between two world points, and a polyline through many.
type Line = { from: Coords; to: Coords }
type Path = Coords[]
interface LineStyle { strokeStyle?: string; lineWidth?: number }
ImageItem
type
An image to draw. TImage is the platform-specific image handle — HTMLImageElement on the web, SkImage on React Native, Image on the server.
type ImageItem<TImage = HTMLImageElement> = Omit<DrawObject, "style"> & {
img: TImage
sprite?: SpriteRect // draw only this sub-region (spritesheet frame)
}
SpriteRect
type
A source rectangle inside a spritesheet image, in sheet pixels. Produced by SpriteSheet, consumed by ImageItem.sprite.
type SpriteRect = { x: number; y: number; w: number; h: number }
SpriteSheetOptions
type
Construction options for SpriteSheet.
interface SpriteSheetOptions {
frameWidth: number
frameHeight: number
columns?: number // required for index-based lookups
margin?: number // outer offset from sheet edges (default 0)
spacing?: number // gap between adjacent frames (default 0)
}
SpriteAnimation
type
A frame-based sprite animation definition, played by SpriteAnimator.