react-canvas-map

This module provides a basic 2d grid-based map interface that works with react-canvas (https://github.com/Bucky24/react-canvas)

Installation

With NPM

npm install --save @bucky24/react-canvas-map

With Yarn

yarn add @bucky24/react-canvas-map

Dependencies

This module depends on @bucky24/react-canvas as a peer dependency, with a min version of 3.1.4

Usage

Map

The Map component is the main component that sets up and draws the map.

Children

The Map component expects a series of Layers as its children. Layers are drawn in order.

Parameters

| Param | Description | Required | | -- | -- | -- | | x | X coord where the map starts on the canvas | Yes | | y | Y coord where the map starts on the canvas | Yes | | width | Width in pixels of the map | Yes | | height | Height in pixels of the map | Yes | | cellSize | Size in pixels of each map cell (can be modified internally based on zoom level). Defaults to 25 | No | | xOff | Initial map horizontal offset | No | | yOff | Initial map vertical offset | No | | moveType | One of the MoveType entries. Determines how the map can be panned. Defaults to MOUSE | No | | mapBackground | MapBackground object, describes background for the map | No | | offMapBackground | MapBackground object, describes background for area that is not take up by the map | No | | onMove | Function, fires when mouse moves over a map cell. First param is cell x, second is cell y. | No | | onClick | Function, fires when move is clicked over a map cell. onClick(cellX, cellY, button, rawX, rawY) (button is a ButtonType from @bucky24/react-canvas). | No | | zoom | Number that indicates the zoom level of the map. Used as initial value if zoomType is not NONE. 100 is default zoom (100% zoom) | No | | zoomType | One of the ZoomType entries. Determines how the map is zoomed. Defaults to MOUSE | No | | minCellX | The cell x at which the map will start drawing cells. Defaults 0 | No | | minCellY | The cell y at which the map will start drawing cells. Defaults 0 | No | | maxCellX | The cell x at which the map will stop drawing cells (inclusive). Defaults 20 | No | | maxCellY | The cell y at which the map will stop drawing cells (inclusive). Defaults 20 | No | | hideGrid | Boolean, if true, the grid lines for cells are not drawn | No | | type | MapType. Indicates type of map, defaults to MapType.STANDARD | No | | centerX | X coord of cell to center the map on. Ignored unless moveType is NONE | No | | centerY | Y coord of cell to center the map on. Ignored unless moveType is NONE | No |

Layer

The Layer component define a layer to be drawn to the map. Layers are drawn in order. It does not take any props, and expects zero or more Layer specific components (detailed below). This component must be placed as a child of a Map.

LayerImage

This component details an image that should be drawn on a given layer. It must be a child of a Layer.

Parameters

| Param | Description | Required | | -- | -- | -- | | src | Either a URL or base64 encoded string with image data | Yes | | width | How many cells the image takes up horizontally (can be fractional) | Yes | | height | How many cells the image takes up vertically (can be fractional) | Yes | | x | The x position of the cell to draw the image at | Yes | | y | The y position of the cell to draw the image at | Yes | | xOff | Setting this will shift the image horizontally from the cell x. Can be fractional. | No | | yOff | Setting this will shift the image vertically from the cell y. Can be fractional. | No | | rot | Indicates how much the image should be rotated, if at all | No | | hAlign | The horizontal alignment of the image. One of HAlign. Defaults HAlign.LEFT | No | | vAlign | The vertical alignment of the image. One of VAlign. Defaults VAlign.TOP | No |

LayerText

This component details text that should be drawn on a given layer. It must be a child of a Layer.

Parameters

| Param | Description | Required | | -- | -- | -- | | text | The text to draw | Yes | | x | The x position of the cell to draw the text at | Yes | | y | The y position of the cell to draw the text at | Yes | | vAlign | The vertical alignment of the text. One of "top", "center", "bottom" | No | | hAlign | The horizontal alignment of the text. One of "left", "center", "right" | No | | font | The font of the text to draw | Yes

LayerRaw

This compoment has been replaced by Cell

LayerPassthrough

This component can be useful if you want the efficiency of building the layer maually but still want to use the Layer component. Note that LayerPassthrough does not technically need to be the only child in the Layer, but, due to the way it is implemented, it must be the first (and any LayerRaw that comes after will overwrite its raw portion of the layer).

Parameters

| Param | Description | Required | | -- | -- | -- | | layer | Instance of MapLayer | Yes |

Manually Building Layers

Manually building layers can be done by setting the layers property on the Map component. This may be slightly more efficient, but is less React-like.

MapLayer

The MapLayer object defines a layer of various objects that need to be drawn. MapLayers are drawn in order, so the first layer is drawn first, and the last layer is drawn last. You can use this to ensure that you get a proper z-depth for your map. MapLayers have the following keys:

| Param | Description | Required | | -- | -- | -- | | images | List of Image objects | No | | text | List of Text objects | No | | raw | Raw object | no |

Note that this means a single layer can have multiple images, multiple text strings, or both.

Image

The Image object defines an image as well as information on how to draw or position the image.

| Param | Description | Required | | -- | -- | -- | | src | Either a URL or base64 encoded string with image data | Yes | | cellWidth | How many cells the image takes up horizontally (can be fractional) | Yes | | cellHeight | How many cells the image takes up vertically (can be fractional) | Yes | | cellX | The x position of the cell to draw the image at | Yes | | cellY | The y position of the cell to draw the image at | Yes | | xOff | Setting this will shift the image horizontally from the cell x. Can be fractional. | No | | yOff | Setting this will shift the image vertically from the cell y. Can be fractional. | No | | rot | Indicates how much the image should be rotated, if at all | No | | hAlign | The horizontal alignment of the image. One of HAlign. Defaults HAlign.LEFT | No | | vAlign | The vertical alignment of the image. One of VAlign. Defaults VAlign.TOP | No |

Text

The Text object defines a string of text as well as information on how to draw the text.

| Param | Description | Required | | -- | -- | -- | | text | The text to draw | Yes | | cellX | The x position of the cell to draw the text at | Yes | | cellY | The y position of the cell to draw the text at | Yes | | vAlign | The vertical alignment of the text. One of "top", "center", "bottom" | No | | hAlign | The horizontal alignment of the text. One of "left", "center", "right" | No | | font | The font of the text to draw | Yes

Raw

The Raw object determines how to draw a layer that is custom, allowing more complex things than just images and text to be drawn.

| Param | Description | Required | | -- | -- | -- | | cells | List of CellItem objects | Yes | | drawFunc | A callback function that will be called once per cell given in the cells list. This function will be given a DrawFuncParams object as a parameter. This function should return either a single React element, or an array of React elements. Note that these elements must be something that can be handled by the Clip element from @bucky24/react-canvas |

Cell

A component that describes an item on the map

| Param | Description | Required | | -- | -- | -- | | cellX | The x coord on the map of the item | Yes | | cellY | The y coord on the map of the item | Yes | | cellWidth | The width, in cells, of the item | Yes | | cellHeight | The height, in cells, of the item | Yes | | cb | Callback function that is called with a CellDims | Yes |

CellDims

| Key | Description | | -- | -- | | x | Starting X of cell | | y | Starting Y of cell | | width | Width of cell | | height | Height of cell | | x2 | x + width | | y2 | y + width |

DrawFuncParams

An object that is passed into the drawFunc for raw drawing on layers. Note that any coords or widths here are already adjusted for map offset, map x/y, and zoom.

| Param | Description | | -- | -- | | x | The x coord on the canvas where this item begins | | y | The y coord on the canvas where this item begins | | width | The width, in pixels, of the item | | height | The height, in pixels, of the item | | id | The id of the item. Whatever was givenin the CellItem is passed through here. |

MapBackground

The MapBackground object defines a background.

| Param | Description | Required | | -- | -- | -- | | color | A hex color code to fill a solid color background | No | | image | An image url or base 64 string to fill an image background | No |

Note that either color or image is expected to be set.

MoveType

MoveType is also exported from the module. It is an enum with the following types:

| Type | Description | | -- | -- | | MOUSE | Use the mouse for panning the map | | KEYBOARD_ARROW | Use arrow keys for panning the map | | NONE | No map panning will be done by the component |

ZoomType

ZoomType is also exported from the module. It is an enum with the following types:

| Type | Description | | -- | -- | | MOUSE | Use the mouse wheel for zooming the map | | FIXED | The zoom parameter will be respected but the map cannot be dynamically zoomed by the user | | NONE | No zoom will be done by the component, and zoom of the map will be set to 100% |

HAlign

HAlign type is exported from the module. It is an enum with the following types:

| Type | Description | | -- | -- | | LEFT | Align the item left | | CENTER | Center the item horizontally | | RIGHT | Align the item right |

VAlign

VAlign type is exported from the module. It is an enum with the following types:

| Type | Description | | -- | -- | | TOP | Align the item top | | CENTER | Center the item vertically | | BOTTOM | Align the item bottom |

MapType

MapType is expected from the module. It is an enum with the following types:

Note there may be some issues with the isometric grid, especially around displaying text.

| Type | Description | | -- | -- | | STANDARD | A normal square grid | | ISOMETRIC | An isometric grid |