{"id":18146497,"url":"https://github.com/riokoe/three-sprites","last_synced_at":"2025-04-23T16:42:07.872Z","repository":{"id":257823816,"uuid":"871690347","full_name":"riokoe/three-sprites","owner":"riokoe","description":"A library for THREE.JS to render and animate spritesheet-based tilemaps and sprites.","archived":false,"fork":false,"pushed_at":"2024-10-16T17:15:29.000Z","size":945,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-16T07:16:04.571Z","etag":null,"topics":["2d","3d","animate","shader","sprites","spritesheet","three","threejs","tile","tilemap","tileset","tiling","webgl"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/riokoe.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-12T17:04:41.000Z","updated_at":"2025-03-06T16:00:59.000Z","dependencies_parsed_at":"2024-10-18T09:02:59.828Z","dependency_job_id":null,"html_url":"https://github.com/riokoe/three-sprites","commit_stats":null,"previous_names":["riokoe/three-sprites"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riokoe%2Fthree-sprites","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riokoe%2Fthree-sprites/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riokoe%2Fthree-sprites/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riokoe%2Fthree-sprites/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riokoe","download_url":"https://codeload.github.com/riokoe/three-sprites/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250472043,"owners_count":21436071,"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":["2d","3d","animate","shader","sprites","spritesheet","three","threejs","tile","tilemap","tileset","tiling","webgl"],"created_at":"2024-11-01T21:07:57.227Z","updated_at":"2025-04-23T16:42:07.850Z","avatar_url":"https://github.com/riokoe.png","language":"TypeScript","funding_links":["https://ko-fi.com/V7V514H3K9"],"categories":[],"sub_categories":[],"readme":"# three-sprites\n\nA library for [THREE.js](https://github.com/mrdoob/three.js) to render, animate and layer spritesheet/tileset-based tilemaps and sprites. The project provides tiling-based versions of most [THREE.js materials](https://threejs.org/docs/?q=material#api/en/materials/Material) but also allows you to extend custom materials.\n\n - Load spritesheets/tilesets\n - Render, animate and tile sprites\n - Render and layer tilemaps\n - No texture cloning\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/V7V514H3K9)\n\n# Demos\n\n[![Demo](https://github.com/riokoe/three-sprites/raw/main/demos/shared/demo.gif)](https://riokoe.github.io/three-sprites/demos/tilemap/index.html)\n\n - [Tilemap demo](https://riokoe.github.io/three-sprites/demos/tilemap/index.html) ([source code](https://github.com/riokoe/three-sprites/tree/main/demos/tilemap/tilemap.js))\n - [Usage demo](https://riokoe.github.io/three-sprites/demos/general/index.html) ([source code](https://github.com/riokoe/three-sprites/tree/main/demos/general/general.js))\n\n# Installation\n\n## Dependencies\n\nHas a peer dependency to [THREE.js](https://threejs.org/docs/#manual/en/introduction/Installation).\n\n## NPM\n\nInstall via:\n\n```bash\nnpm install three three-sprites\n```\n\nImport in ESM projects:\n\n```js\nimport * as THREE from \"three\";\nimport { SpriteMeshBasicMaterial, TilemapMeshBasicMaterial } from \"three-sprites\";\n```\n\nImport in CJS projects:\n\n```js\nconst THREE = require(\"three\");\nconst { SpriteMeshBasicMaterial, TilemapMeshBasicMaterial } = require(\"three-sprites\");\n```\n\n## Browser / CDN\n\nConfigure import map:\n\n```xml\n\u003cscript type=\"importmap\"\u003e\n  {\n    \"imports\": {\n      \"three\": \"https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js\",\n      \"three-sprites\": \"https://cdn.jsdelivr.net/npm/three-sprites@latest/dist/browser/three-sprites.min.js\",\n    }\n  }\n\u003c/script\u003e\n```\n\nImport in your project:\n\n\n```js\nimport * as THREE from \"three\";\nimport { SpriteMeshBasicMaterial, TilemapMeshBasicMaterial } from \"three-sprites\";\n```\n\n# Usage\n\nFor details see the [documentation](https://github.com/riokoe/three-sprites/tree/main/docs/index.md) and the [demo source code](https://github.com/riokoe/three-sprites/tree/main/demos/).\n\n## Materials\n\nThe library provides exports for almost all THREE.js materials.\n\nFor sprites:\n\n```js\nimport {\n  SpriteMeshBasicMaterial,\n  SpriteMeshLambertMaterial,\n  SpriteMeshStandardMaterial,\n  SpriteMeshPhysicalMaterial,\n  SpriteMeshPhongMaterial,\n  SpriteMeshToonMaterial\n} from \"three-sprites\"\n```\n\nFor tilemaps:\n\n```js\nimport {\n  TilemapMeshBasicMaterial,\n  TilemapMeshLambertMaterial,\n  TilemapMeshStandardMaterial,\n  TilemapMeshPhysicalMaterial,\n  TilemapMeshPhongMaterial,\n  TilemapMeshToonMaterial\n} from \"three-sprites\"\n```\n\nChose the ones which fit your needs. They all provide the same interface around sprites/tilemaps but also come with the corresponding material's set of features.\n\n## Sprites\n\n### Render a sprite based on a tileset index\n\nWorking with a tileset (all tiles have the same size), you can use tile indices to render and animate sprites. The following example loads a tileset and renders one tile as a sprite.\n\n```js\n// Import THREE.js and a material from thee-sprites\nimport * as THREE from \"three\";\nimport { SpriteMeshBasicMaterial } from \"three-sprites\";\n\n// Load spritesheet or tileset\nconst texture = new THREE.TextureLoader().load(\"spritesheet.png\");\n\n// Turn off mipmapping to minimize seams on mag/min filters\ntexture.magFilter = THREE.LinearFilter;\ntexture.minFilter = THREE.LinearFilter;\ntexture.wrapS = THREE.RepeatWrapping;\ntexture.wrapT = THREE.RepeatWrapping;\n\n// Create a mesh with the new material\nconst sprite = new THREE.Mesh(\n  new THREE.PlaneGeometry(1, 1),\n  new SpriteMeshBasicMaterial({\n    side: THREE.FrontSide,\n    precision: \"highp\",\n    map: texture,\n  }),\n);\n\n// Configure the tiling\nsprite.material.tile({\n  // Define the size of the tileset in px\n  tileSize: { x: 128, y: 128 },\n  // Define the size of the tiles in the tileset in px\n  tilesetSize: { x: 16, y: 16 },\n  // Set the index of the tile in the tileset to render\n  // In this case, we display the fourth tile in the tileset\n  // On a tileset of w/h 128/128 with tiles of 16/16, that's the tile at x/y 48/0\n  tile: 3,\n});\n\n// Position the mesh and add it to your scene...\nmyScene.add(sprite)\n```\n\nWith the sprite in your scene, animate through tile 3-6 based on tile indices:\n\n```js\nlet tileIndex = 3;\nlet lastts = 0;\nconst tick = ts =\u003e {\n  if (tileIndex \u003e 6)\n    tileIndex = 3;\n  // Set the corresponding tile\n  sprite.tile({ tile: tileIndex++ });\n  requestAnimationFrame(tick);\n};\ntick();\n```\n\n### Render a sprite based on spritesheet coordinates\n\nWorking with a spritesheet instead of a tileset, you can use coordinates to render the sprite:\n\n```js\n// Imports and mesh setup identical to the previous full example...\n\n// Display a 16x32 sprite from a spritesheet\nsprite.material.tile({\n  // Define the size of the spritesheet in px\n  tileSize: { x: 128, y: 128 },\n  // Define the (top/left corner) coordinates of the tile in the spritesheet\n  tile: { x: 32 , y: 16}\n  // Define the size of tile\n  tilesetSize: { x: 16, y: 32 },\n});\n```\n\nAnimate via coordinates:\n\n```js\nconst tick = ts =\u003e {\n  // ...\n  sprite.tile({ tile: { x: 32 + n, 16 + m } });\n  // ...\n};\n```\n\n### Repeat a sprite on the mesh\n\nInstead of fitting one tile on a mesh, you can repeat the same tile horizontally/vertically:\n\n```js\n// Imports and mesh setup identical to the previous full example...\n\n// Create a 10x2 mesh\nconst sprite = new THREE.Mesh(\n  new THREE.PlaneGeometry(10, 2),\n  new SpriteMeshBasicMaterial({\n    side: THREE.FrontSide,\n    precision: \"highp\",\n    map: texture,\n  }),\n);\n\n// Display a 16x16 sprite and repeat it 9 times horizontally\n// and 1 time vertically\nsprite.material.tile({\n  // Define the size of the spritesheet in px\n  tileSize: { x: 128, y: 128 },\n  // Define the (top/left corner) coordinates of the tile in the spritesheet\n  tile: { x: 32 , y: 16}\n  // Define the size of tile in the spritesheet\n  tilesetSize: { x: 16, y: 16 },\n  // Repeat the tile vertically/horizontally:\n  repeat: { x: 10, y: 2 }\n});\n```\n\n### Use a tileset with spacing\n\nWhen working with a tileset with spacing between tiles, you can crop them:\n\n```js\n// Imports and mesh setup identical to the previous full example...\n\nsprite.material.tile({\n  tileSize: { x: 128, y: 128 },\n  tilesetSize: { x: 16, y: 16 },\n  tile: 4,\n  repeat: { x: 10, y: 2 },\n  // Define the space between tiles in px\n  spacing: 2\n});\n```\n\n## Tilemaps\n\n### Render a tilemap from a tileset\n\nInstead of rendering individual sprites, you can render multiple different tiles on one mesh.\n\n```js\n// Import THREE.js and a material from thee-sprites\n// Note that Tilemaps use a different base material as they run on\n// different shaders compared to sprites\nimport * as THREE from \"three\";\nimport { TilemapMeshBasicMaterial } from \"three-sprites\";\n\n// Load tileset\nconst texture = new THREE.TextureLoader().load(\"tileset.png\");\n\n// Turn off mipmapping to minimize seams on mag/min filters\ntexture.magFilter = THREE.LinearFilter;\ntexture.minFilter = THREE.LinearFilter;\ntexture.wrapS = THREE.RepeatWrapping;\ntexture.wrapT = THREE.RepeatWrapping;\n\n// Create a mesh with the new material\nconst sprite = new THREE.Mesh(\n  new THREE.PlaneGeometry(20, 10),\n  new TilemapMeshBasicMaterial({\n    side: THREE.FrontSide,\n    precision: \"highp\",\n    map: texture,\n  }),\n);\n\n// Configure the tiling\nsprite.material.tile({\n  // Define the size of the tileset in px\n  tileSize: { x: 128, y: 128 },\n  // Define the size of tiles in the tileset\n  tilesetSize: { x: 16, y: 16 },\n  // Define the space between tiles in the tileset\n  spacing: 0,\n  // Define how many tiles to display in each direction\n  repeat: { x: 10, y: 5 }\n  // Define which tiles to render\n  tiles: [\n    0, 0, 1, 5, 3, 9, 2, 5, 0, 0,\n    0, 4, 4, 2, 2, 2, 1, 9, 0, 0,\n    0, 1, 1, 5, 0, 9, 4, 3, 4, 0,\n    0, 1, 0, 5, 3, 9, 2, 5, 0, 3,\n    0, 7, 8, 4, 3, 2, 1, 9, 8, 7,\n  ],\n});\n\n// Position the mesh and add it to your scene...\nmyScene.add(sprite)\n```\n\n### Layer tilemaps\n\nBlend multiple tilemap layers on one mesh. Supports transparency.\n\n```js\n// Imports and mesh setup identical to the previous full example...\n\n// Configure the tiling\nsprite.material.tile({\n  // Define the size of the tileset in px\n  tileSize: { x: 128, y: 128 },\n  // Define the size of tiles in the tileset\n  tilesetSize: { x: 16, y: 16 },\n  // Define the space between tiles in the tileset\n  spacing: 0,\n  // Define how many tiles to display in each direction\n  repeat: { x: 10, y: 5 }\n  // Define which tiles to render\n  tiles: [\n    // Layer one\n    0, 0, 1, 5, 3, 9, 2, 5, 0, 0,\n    0, 4, 4, 2, 2, 2, 1, 9, 0, 0,\n    0, 1, 1, 5, 0, 9, 4, 3, 4, 0,\n    0, 1, 0, 5, 3, 9, 2, 5, 0, 3,\n    0, 7, 8, 4, 3, 2, 1, 9, 8, 7,\n    // Layer two, will wrap around and start at the first tile again\n    3, 7, 3, 0, 4, 7, 2, 7, 4, 6,\n    3, 2, 3, 0, 1, 2, 2, 9, 6, 1,\n    3, 7, 3, 2, 1, 7, 7, 1, 4, 6,\n    2, 1, 2, 0, 4, 7, 2, 7, 2, 7,\n    3, 7, 1, 3, 4, 7, 6, 6, 4, 9,\n    // More layers\n    // ...\n  ],\n});\n```\n\n## General\n\n### Re-using textures\n\nInstead of defining texture wrapping per texture, this library allows you to re-use textures across sprites and tilemaps.\n\n```js\nconst texture = new THREE.TextureLoader().load(\"tileset.png\");\nconst geo = new THREE.PlaneGeometry(1, 1);\nconst materialOptions = {\n    side: THREE.FrontSide,\n    precision: \"highp\",\n    map: texture\n};\nconst tilingOptions = {\n  tileSize: { x: 16, y: 16 },\n  tilesetSize: { x: 128, y: 128 }\n}\n\n// Sprite 1\nconst sprite1 = new THREE.Mesh(geo, new SpriteMeshBasicMaterial(materialOptions));\nsprite1.tile({ ...tilingOptions, tile: 1 });\nmyScene.add(sprite1);\n\n// Sprite 2\nconst sprite2 = new THREE.Mesh(geo, new SpriteMeshBasicMaterial(materialOptions));\nsprite2.tile({ ...tilingOptions, tile: 5 });\nmyScene.add(sprite2);\n\n// Sprite 3\nconst sprite3 = new THREE.Mesh(geo, new SpriteMeshBasicMaterial(materialOptions));\nsprite3.tile({ ...tilingOptions, tile: 12 });\nmyScene.add(sprite3);\n\n// Tlemap\nconst tilemap = new THREE.Mesh(geo, new TilemapMeshBasicMaterial(materialOptions));\ntilemap.material.tile({\n  ...tileOptions,\n  repeat: { x: 10, y: 5 },\n  tiles: [\n    0, 0, 1, 5, 3, 9, 2, 5, 0, 0,\n    0, 4, 4, 2, 2, 2, 1, 9, 0, 0,\n    0, 1, 1, 5, 0, 9, 4, 3, 4, 0,\n    0, 1, 0, 5, 3, 9, 2, 5, 0, 3,\n    0, 7, 8, 4, 3, 2, 1, 9, 8, 7,\n  ],\n});\nmyScene.add(tilemap);\n```\n\n# Documentation\n\n## Classes\n\n| Class | Description |\n| ------ | ------ |\n| [SpriteMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/SpriteMaterial.md) | Base material to render sprites: |\n| [SpriteMeshBasicMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/SpriteMeshBasicMaterial.md) | THREE.MeshBasicMaterial extending SpriteMaterial. |\n| [SpriteMeshLambertMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/SpriteMeshLambertMaterial.md) | THREE.MeshLambertMaterial extending SpriteMaterial. |\n| [SpriteMeshPhongMaterial](classes/SpriteMeshPhongMaterial.md) | THREE.MeshPhongMaterial extending SpriteMaterial. |\n| [SpriteMeshPhysicalMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/SpriteMeshPhysicalMaterial.md) | THREE.MeshPhysicalMaterial extending SpriteMaterial. |\n| [SpriteMeshStandardMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/SpriteMeshStandardMaterial.md) | THREE.MeshStandardMaterial extending SpriteMaterial. |\n| [SpriteMeshToonMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/SpriteMeshToonMaterial.md) | THREE.MeshToonMaterial extending SpriteMaterial. |\n| [TilemapMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMaterial.md) | Base material to render sprites: |\n| [TilemapMeshBasicMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMeshBasicMaterial.md) | THREE.MeshBasicMaterial extending TilemapMaterial. |\n| [TilemapMeshLambertMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMeshLambertMaterial.md) | THREE.MeshLambertMaterial extending TilemapMaterial. |\n| [TilemapMeshPhongMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMeshPhongMaterial.md) | THREE.MeshPhongMaterial extending TilemapMaterial. |\n| [TilemapMeshPhysicalMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMeshPhysicalMaterial.md) | THREE.MeshPhysicalMaterial extending TilemapMaterial. |\n| [TilemapMeshStandardMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMeshStandardMaterial.md) | THREE.MeshStandardMaterial extending TilemapMaterial. |\n| [TilemapMeshToonMaterial](https://github.com/riokoe/three-sprites/tree/main/docs/classes/TilemapMeshToonMaterial.md) | THREE.MeshToonMaterial extending TilemapMaterial. |\n\n## Interfaces\n\n| Interface | Description |\n| ------ | ------ |\n| [ISpriteTilingOptions](https://github.com/riokoe/three-sprites/tree/main/docs/interfaces/ISpriteTilingOptions.md) | Options for `SpriteMaterial.tile()` |\n| [ISpriteUniforms](https://github.com/riokoe/three-sprites/tree/main/docs/interfaces/ISpriteUniforms.md) | Uniforms for `SpriteMaterial` |\n| [ITilemapTilingOptions](https://github.com/riokoe/three-sprites/tree/main/docs/interfaces/ITilemapTilingOptions.md) | Options for `TilemapMaterial.tile()` |\n| [ITilemapUniforms](https://github.com/riokoe/three-sprites/tree/main/docs/interfaces/ITilemapUniforms.md) | Uniforms for `TilemapMaterial` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friokoe%2Fthree-sprites","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friokoe%2Fthree-sprites","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friokoe%2Fthree-sprites/lists"}