node package manager
Love JavaScript? Your insights can make it even better. Take the 2017 JavaScript Ecosystem Survey »



A set of A-Frame components that render a static tilemap from a specially coded image source and a set of reference entities. It includes three components with different underlying implementations: tilemap-cloned, tilemap-merged, and tilemap-instanced.



    <a-asset-item id="milkTruck" src="assets/CesiumMilkTruck.glb"></a-asset-item>
    <img id="tilemap-image" src="maps/tilemap-128px.png">
  <a-entity tilemap-instanced="src: #tilemap-image" position="0 0 -20">
    <a-entity tile="id: 1" geometry="primitive: box" visible="false" scale="1 1 3"></a-entity>
    <a-entity tile="id: 2; readyEvent: model-loaded" gltf-model="#milkTruck" visible="false" scale="0.5 0.5 0.5"></a-entity>
    <a-entity tile="id: 3" geometry="primitive: sphere" visible="false"></a-entity>
  <a-sky color="#333"></a-sky>


Tilemaps are specified using a combination of tilemap-* and tile components. An entity with the tilemap-* component represents the tilemap itself, and should be transformed and attached to the desired part of the scene graph.

Entities that are direct children of the tilemap-* can include the tile component to indicate that they represent one of the tile IDs that can be specified in the tilemap. Their transformation relative to the origin of the tilemap is replicated in each of their instances.

Usually, these tile entities should also have the component visible="false".

Tilemap Properties

Property Type Description Default Value
src asset An image asset from which to derive the tile values
tileWidth number Width of each tile in scene units 1
tileHeight number Height of each tile in scene units 1
origin vec2 Origin of the tilemap in normalized image coordinates. A value of (0,0) will render a tilemap whose entity center is the top-left corner, while a value of (1,1) will center the entity at the bottom right {x:0.5,y:0.5}
debug boolean Enables additional debug printing to console false

Tilemap Events

Property Description
model-loaded Tilemap completed loading.
This emulates the behavior of other model loaders in A-Frame.

Tile Properties

Property Type Description
id int The ID value in the tilemap that this entity represents
readyEvent string If specified, the tilemap will wait for this entity to emit this event before loading. This is needed for tiles that load assets (e.g. GLTF models).
For most A-Frame loaders, listen for the event model-loaded.

Tilemap Image Format

Example: Square 128px Randomized-ID Tilemap
IDs: random, 0 to 3
Rotation: 0 to 360 deg from left to right

The image tilemap that determines where each tile is rendered contains only two components: ID and Rotation. Images are expected to contain one byte per channel of either RGB or RGBA information.

Channel Size Description
R (Red) 1 byte HIGH byte of the tile ID
G (Green) 1 byte LOW byte of the tile ID
B (Blue) 1 byte Normalized rotation (0 = 0°, 255 = 358.5°)
A (Alpha) 1 byte Unused

The equations for determining the tile offets from the pixel value of the image are:

TILE_ID    = 256 * pixel.R + pixel.G
TILE_THETA = PI / 128.0 * pixel.B

Each pixel of the image represents one tile, with each column spaced at tileWidth intervals and each row spaced at tileHeight intervals.


Cloned Tilemaps: tilemap-cloned

In the cloned tilemap, each tile location in the map is rendered by cloning the THREE.Object3D represented in the reference tile with the matching ID.

This approach exactly reuses the THREE.Geometry and THREE.Material associated with the reference tile, so it will not interfere with shaders or other complex models. However, it is the least performant, as each tile is handled as a completely different node in the scene graph.

Merged Tilemaps: tilemap-merged

In the merged tilemap, each reference tile is decomposed into a list of reference meshes. The geometry of each of these meshes is then duplicated at each matching tile location, creating a single merged mesh that contains geometry for all instances of the reference tile.

This method is much more performant than cloning, because each reference tile mesh simply pushes one large geometry buffer to the GPU. However, it is very memory intensive, because it must maintain the full geometric representation of every tile location in memory.

Instanced Tilemaps: tilemap-instanced

In the instanced tilemap, each reference tile is pushed to the GPU, where a vertex shader is applied to each child mesh that instead renders it at each tile location.

This is the most performant of the three methods, as it only pushes each reference tile to the GPU once, and it also only needs a small amount of memory to maintain a buffer of tile locations to which each tile will be rendered.

One downside of this approach is that it requires the direct insertion of a vertex shader into the material that is used to render the object. This limits the material options for these objects. The implementation tries to replicate the functionality of standard THREE source materials as best it can, but some effects will not work properly, and all vertex shader effects are removed.

Another downside is that the rendered instances are not available outside the GPU for other applications, such as raycasts or other physical checks. For applications that require those, cloned or merged tilemaps may be a better choice.


This library is free software and is distributed under an MIT License.