Configuration

The CanvasTileEngineConfig object controls the initial state and behavior of the engine.

Core Settings

These are the fundamental settings required to initialize the engine.

Property	Type	Default	Description
scale	number	Required	The initial zoom level (pixels per grid unit).
size	object	Required	The dimensions of the canvas. See Size Options.
responsive	"preserve-scale" | "preserve-viewport" | false	false	Enable responsive mode. See Responsive Mode.
backgroundColor	string	"#ffffff"	The background color of the canvas.
minScale	number	scale * 0.5	Minimum allowed zoom level.
maxScale	number	scale * 2	Maximum allowed zoom level.
gridAligned	boolean	false	Snap initial center to cell centers (x.5, y.5) for pixel-perfect grid alignment.

Size Options

Define the canvas dimensions and constraints.

Property	Type	Default	Description
width	number	Required	Initial width in pixels.
height	number	Required	Initial height in pixels.
minWidth	number	100	Minimum width allowed during resize.
minHeight	number	100	Minimum height allowed during resize.
maxWidth	number	Infinity	Maximum width allowed during resize.
maxHeight	number	Infinity	Maximum height allowed during resize.

Responsive Mode

Enable responsive mode to automatically resize the canvas when its container changes size. Two modes are available:

Mode	Description
"preserve-scale"	Scale stays constant, visible tile count changes as container resizes.
"preserve-viewport"	Visible tile count stays constant, scale adjusts based on width.

preserve-scale

The scale remains fixed while the visible tile count changes based on the container size. The wrapper size is fully controlled by your CSS.

const config = {
    size: { width: 800, height: 600 },
    scale: 50,
    responsive: "preserve-scale",
};

preserve-viewport

The visible tile count remains fixed while the scale adjusts based on container width. The engine automatically:

• Sets wrapper width: 100%
• Calculates height based on the tile ratio from size.width / size.height
• Derives minWidth / maxWidth from minScale / maxScale:
  • minWidth = minScale × (size.width / scale)
  • maxWidth = maxScale × (size.width / scale)
• Derives minHeight / maxHeight similarly based on the tile ratio

This ensures the scale always stays within minScale and maxScale bounds.

const config = {
    size: { width: 800, height: 600 }, // 16×12 tiles at scale 50
    scale: 50,
    minScale: 25, // → minWidth: 400px, minHeight: 300px
    maxScale: 100, // → maxWidth: 1600px, maxHeight: 1200px
    responsive: "preserve-viewport",
};

Automatic Size Limits

In preserve-viewport mode, size.minWidth, size.maxWidth, size.minHeight, and size.maxHeight are ignored. The size limits are automatically calculated from minScale and maxScale to maintain the configured tile count.

Limitations

When responsive mode is enabled:

• resize() method is disabled (canvas size is controlled by the wrapper element)
• eventHandlers.resize is ignored (resizing is handled automatically)

Interactions

Control how the user interacts with the map via eventHandlers.

Handler	Default	Description
click	false	Enable click events on grid cells.
rightClick	false	Enable right click events on grid cells.
hover	false	Enable hover events and tracking.
drag	false	Enable panning by dragging the map.
zoom	false	Enable zooming with the mouse wheel.
resize	false	Automatically resize canvas when container changes.

// Example usage
eventHandlers: {
  drag: true,
  zoom: true,
  click: true
}

Map Boundaries

Restrict camera movement to a specific area of the world. This is useful for preventing users from scrolling beyond your map limits.

Property	Type	Default	Description
minX	number	-Infinity	Minimum X coordinate the camera can reach.
maxX	number	Infinity	Maximum X coordinate the camera can reach.
minY	number	-Infinity	Minimum Y coordinate the camera can reach.
maxY	number	Infinity	Maximum Y coordinate the camera can reach.

// Example: Restrict map to a 200x200 grid centered at origin
bounds: {
  minX: -100,
  maxX: 100,
  minY: -100,
  maxY: 100
}

// Example: Only restrict horizontal movement
bounds: {
  minX: 0,
  maxX: 500,
  minY: -Infinity,
  maxY: Infinity
}

Runtime Updates

You can change boundaries at runtime using engine.setBounds(). See Camera Controls for details.

Visual Customization

Coordinate Overlay

Display X/Y axes numbers on the edges of the screen.

Property	Type	Default	Description
enabled	boolean	false	Show the coordinate numbers.
shownScaleRange	{ min, max }	All	Only show coordinates when zoom is within this range.

Cursors

Customize the mouse cursor for different states.

State	Default	Description
default	"default"	The standard cursor.
move	"move"	The cursor shown while dragging the map.

Debugging

Built-in tools to help you develop. Enable via the debug object.

Feature	Default	Description
enabled	false	Master switch for all debug features.
hud.enabled	false	Show HUD panel.
hud.topLeftCoordinates	false	Display top-left world coords.
hud.coordinates	false	Display center coords.
hud.scale	false	Display current scale.
hud.tilesInView	false	Display visible tile counts.
hud.fps	false	Display current FPS (continuously updated).
eventHandlers.*	true	Debug-time overrides for click/hover/drag/zoom/resize.

Full TypeScript Type

For reference, here is the complete type definition:

export type CanvasTileEngineConfig = {
    scale: number;
    maxScale?: number;
    minScale?: number;
    backgroundColor?: string;
    gridAligned?: boolean;
    size: {
        width: number;
        height: number;
        minWidth?: number;
        minHeight?: number;
        maxWidth?: number;
        maxHeight?: number;
    };
    responsive?: "preserve-scale" | "preserve-viewport" | false;
    eventHandlers?: {
        click?: boolean;
        rightClick?: boolean;
        hover?: boolean;
        drag?: boolean;
        zoom?: boolean;
        resize?: boolean;
    };
    coordinates?: {
        enabled?: boolean;
        shownScaleRange?: { min: number; max: number };
    };
    cursor?: {
        default?: string;
        move?: string;
    };
    debug?: {
        enabled?: boolean;
        grid?: {
            enabled?: boolean;
            color?: string;
            lineWidth?: number;
        };
        hud?: {
            enabled?: boolean;
            topLeftCoordinates?: boolean;
            coordinates?: boolean;
            scale?: boolean;
            tilesInView?: boolean;
        };
        eventHandlers?: {
            click?: boolean;
            hover?: boolean;
            drag?: boolean;
            zoom?: boolean;
            resize?: boolean;
        };
    };
};