{"id":28749655,"url":"https://github.com/psigen/aframe-tilemap","last_synced_at":"2025-06-16T20:44:05.220Z","repository":{"id":57174295,"uuid":"114478798","full_name":"psigen/aframe-tilemap","owner":"psigen","description":"A-Frame components for static tilemaps.","archived":false,"fork":false,"pushed_at":"2018-04-12T03:51:17.000Z","size":912,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-04T07:31:23.384Z","etag":null,"topics":["aframe","aframe-component","instanced-tilemaps","tilemap"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/psigen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-16T17:36:45.000Z","updated_at":"2020-12-28T22:11:57.000Z","dependencies_parsed_at":"2022-08-29T00:10:39.134Z","dependency_job_id":null,"html_url":"https://github.com/psigen/aframe-tilemap","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/psigen/aframe-tilemap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psigen%2Faframe-tilemap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psigen%2Faframe-tilemap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psigen%2Faframe-tilemap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psigen%2Faframe-tilemap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/psigen","download_url":"https://codeload.github.com/psigen/aframe-tilemap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psigen%2Faframe-tilemap/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260236324,"owners_count":22979397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aframe","aframe-component","instanced-tilemaps","tilemap"],"created_at":"2025-06-16T20:44:04.219Z","updated_at":"2025-06-16T20:44:05.206Z","avatar_url":"https://github.com/psigen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aframe-tilemap\n\nA set of [A-Frame](https://aframe.io/) components that render a static tilemap\nfrom a specially coded image source and a set of reference entities. It\nincludes three components with different underlying implementations: [`tilemap-cloned`](#cloned-tilemaps-tilemap-cloned), [`tilemap-merged`](#merged-tilemaps-tilemap-merged), and [`tilemap-instanced`](#instanced-tilemaps-tilemap-instanced).\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"examples/assets/screenshot.png\" alt=\"screenshot\"\u003e\u003c/p\u003e\n\n## Usage\n\n```html\n\u003ca-scene\u003e\n  \u003ca-assets\u003e\n    \u003ca-asset-item id=\"milkTruck\" src=\"assets/CesiumMilkTruck.glb\"\u003e\u003c/a-asset-item\u003e\n    \u003cimg id=\"tilemap-image\" src=\"maps/tilemap-128px.png\"\u003e\n  \u003c/a-assets\u003e\n  \u003ca-entity tilemap-instanced=\"src: #tilemap-image\" position=\"0 0 -20\"\u003e\n    \u003ca-entity tile=\"id: 1\" geometry=\"primitive: box\" visible=\"false\" scale=\"1 1 3\"\u003e\u003c/a-entity\u003e\n    \u003ca-entity tile=\"id: 2; readyEvent: model-loaded\" gltf-model=\"#milkTruck\" visible=\"false\" scale=\"0.5 0.5 0.5\"\u003e\u003c/a-entity\u003e\n    \u003ca-entity tile=\"id: 3\" geometry=\"primitive: sphere\" visible=\"false\"\u003e\u003c/a-entity\u003e\n  \u003c/a-entity\u003e\n  \u003ca-sky color=\"#333\"\u003e\u003c/a-sky\u003e\n\u003c/a-scene\u003e\n```\n\n## API\n\nTilemaps are specified using a combination of `tilemap-*` and `tile` components.\nAn entity with the `tilemap-*` component represents the tilemap itself, and\nshould be transformed and attached to the desired part of the scene graph.\n\nEntities that are direct children of the `tilemap-*` can include the `tile`\ncomponent to indicate that they represent one of the tile IDs that can be\nspecified in the tilemap. Their transformation relative to the origin of the\ntilemap is replicated in each of their instances.\n\nUsually, these tile entities should also have the component `visible=\"false\"`.\n\n### Tilemap Properties\n\n| Property   | Type      | Description                                                                                                                                                                                                 | Default Value   |\n| ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |\n| src        | `asset`   | An image asset from which to derive the tile values                                                                                                                                                         |                 |\n| tileWidth  | `number`  | Width of each tile in scene units                                                                                                                                                                           | 1               |\n| tileHeight | `number`  | Height of each tile in scene units                                                                                                                                                                          | 1               |\n| 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}` |\n| debug      | `boolean` | Enables additional debug printing to console                                                                                                                                                                | `false`         |\n\n### Tilemap Events\n\n| Property     | Description                                                                                    |\n| ------------ | ---------------------------------------------------------------------------------------------- |\n| model-loaded | Tilemap completed loading.\u003cbr\u003e_This emulates the behavior of other model loaders in A-Frame._ |\n\n### Tile Properties\n\n| Property   | Type     | Description                                                                                                                                                                                                                 |\n| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| id         | `int`    | The ID value in the tilemap that this entity represents                                                                                                                                                                     |\n| 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).\u003cbr\u003e_For most A-Frame loaders, listen for the event `model-loaded`._ |\n\n## Tilemap Image Format\n\n| Example: Square 128px Randomized-ID Tilemap |\n| -------------------------------------------------------------------------------------------------------- |\n| ![tilemap](examples/maps/tilemap-128px.png)                                                              |\n| IDs: *random, 0 to 3* | \n| Rotation: *0 to 360 deg from left to right* |\n\nThe image tilemap that determines where each tile is rendered contains only\ntwo components: `ID` and `Rotation`. Images are expected to contain one byte\nper channel of either RGB or RGBA information.\n\n| Channel       | Size     | Description                                    |\n| ------------- | -------- | ---------------------------------------------- |\n| **R** (Red)   | `1 byte` | HIGH byte of the tile ID                       |\n| **G** (Green) | `1 byte` | LOW byte of the tile ID                        |\n| **B** (Blue)  | `1 byte` | Normalized rotation (`0 = 0°`, `255 = 358.5°`) |\n| **A** (Alpha) | `1 byte` | _Unused_                                       |\n\nThe equations for determining the tile offets from the pixel value of the image are:\n```\nTILE_ID    = 256 * pixel.R + pixel.G\nTILE_THETA = PI / 128.0 * pixel.B\n```\n\nEach pixel of the image represents one tile, with each column spaced at\n`tileWidth` intervals and each row spaced at `tileHeight` intervals.\n\n## Implementations\n\n### Cloned Tilemaps: [`tilemap-cloned`](src/tilemap-cloned.js)\n\nIn the cloned tilemap, each tile location in the map is rendered by cloning the\n`THREE.Object3D` represented in the reference tile with the matching ID.\n\nThis approach exactly reuses the `THREE.Geometry` and `THREE.Material`\nassociated with the reference tile, so it will not interfere with shaders or\nother complex models. However, it is the least performant, as each tile is\nhandled as a completely different node in the scene graph.\n\n### Merged Tilemaps: [`tilemap-merged`](src/tilemap-merged.js)\n\nIn the merged tilemap, each reference tile is decomposed into a list of\nreference meshes. The geometry of each of these meshes is then duplicated at\neach matching tile location, creating a single merged mesh that contains\ngeometry for all instances of the reference tile.\n\nThis method is much more performant than cloning, because each reference tile\nmesh simply pushes one large geometry buffer to the GPU. However, it is very\nmemory intensive, because it must maintain the full geometric representation\nof every tile location in memory.\n\n### Instanced Tilemaps: [`tilemap-instanced`](src/tilemap-instanced.js)\n\nIn the instanced tilemap, each reference tile is pushed to the GPU, where a\nvertex shader is applied to each child mesh that instead renders it at each\ntile location.\n\nThis is the most performant of the three methods, as it only pushes each\nreference tile to the GPU once, and it also only needs a small amount of memory\nto maintain a buffer of tile locations to which each tile will be rendered.\n\nOne downside of this approach is that it requires the direct insertion of a\nvertex shader into the material that is used to render the object. This limits\nthe material options for these objects. The implementation tries to replicate\nthe functionality of standard `THREE` source materials as best it can, but some\neffects will not work properly, and all vertex shader effects are removed.\n\nAnother downside is that the rendered instances are not available outside\nthe GPU for other applications, such as raycasts or other physical checks.\nFor applications that require those, cloned or merged tilemaps may be a\nbetter choice.\n\n## License\n\nThis library is free software and is distributed under an MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsigen%2Faframe-tilemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpsigen%2Faframe-tilemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsigen%2Faframe-tilemap/lists"}