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:
Tilemaps are specified using a combination of
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
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
||An image asset from which to derive the tile values|
||Width of each tile in scene units||1|
||Height of each tile in scene units||1|
||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||
||Enables additional debug printing to console||
|model-loaded||Tilemap completed loading.
This emulates the behavior of other model loaders in A-Frame.
||The ID value in the tilemap that this entity represents|
||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
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
Rotation. Images are expected to contain one byte
per channel of either RGB or RGBA information.
||HIGH byte of the tile ID|
||LOW byte of the tile ID|
||Normalized rotation (
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
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
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.
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.
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.