labyrinthos
v1.1.2
Published
A JavaScript library for procedural generation of maps, mazes, and biomes, supporting various algorithms and terrain types.
Downloads
34
Maintainers
Readme
Labyrinthos.js ( ALPHA )
A JavaScript procedural generator for Mazes, Terrains, and Biomes. Designed for game developers and professional hobbyists, Labyrinthos.js offers a very simple-to-use API for crafting complex, customizable landscapes.
Main Features
- Procedural Generation - Create vast, diverse maps and mazes algorithmically
- 2D and 3D Map Generation - Supports both 2D Tile Maps and 3D Voxel Map generation
- Submap Embedding - Seamlessly integrate smaller maps into larger maps
- TileMap Queries - Easily query subsections of a
TileMap
for applying custom transforms - TileSet Support - Flexible
TileSet
mapping for assigning metadata toTileMap
ids - Biomes - Create realastic Biomes with weighted distribution and Perlin Noise
- Parametric L-Systems - Create generational enviroments using L-Systems with parameters
- Realiable Randomness - Leverages Mersenne Twister for advanced predictable randomness
- ASCII Masking - Built-in support for generating custom Roguelike game maps
- Export Functionality - Easily export maps in various formats, including Tiled
.tmj
JSON
Installation
CDN Release 1.1.0 | Files | CDN | Size | |---------------|--------------------------------------------------|-----------| | labyrinthos.js | Link | 160kb | | labyrinthos.min.js| Link | 60kb |
NPM
npm install labyrinthos
Live Demo and Map Explorer
You can explore all Maze and Terrain generators in the browser with our live demo.
If you click "Explore 2D" or "Explore 3D" in the demo, the TileMap will open in an instance of Mantra.js.
LIVE DEMO LINK
https://yantra.gg/labyrinthos
https://github.com/yantra-core/Labyrinthos.js/assets/70011/1f01bcdd-53ca-4d11-9d1c-ed2ed2a65b9a
https://github.com/yantra-core/Labyrinthos.js/assets/70011/c8a5cf73-33d0-41ba-8227-22626265c01e
https://github.com/yantra-core/Labyrinthos.js/assets/70011/74660595-a93b-4e98-b5ce-b5ba63200a14
This demo can export generated maps to Tiled JSON format ( with default bundled TileSet
assets ).
TileMap
Data Formats
Labyrinthos map data is internally represented by arrays of integers.
2D Data
let map = new LABY.TileMap({
width: 3,
height: 3
});
map.fill(2)
The TileMap.data
array will contain an array that looks like this:
[2, 2, 2, 2, 2, 2, 2, 2, 2]
Each integer value in TileMap.data
array corresponds to a Tile.id
.
3D Voxel Data
let map = new LABY.TileMap({
width: 3,
height: 3,
depth: 3
});
map.fill(3);
For 3D Voxel Maps, TileMap.data
is a nested array with first index representing depth
values.
[
[3, 3, 3, 3, 3, 3, 3, 3, 3],
[3, 3, 3, 3, 3, 3, 3, 3, 3],
[3, 3, 3, 3, 3, 3, 3, 3, 3]
]
Usage
Basic
From Yantra CDN Build
<script src="https://yantra.gg/labyrinthos.js"></script>
<script>
document.addEventListener('DOMContentLoaded', (event) => {
let map = new LABY.TileMap({
width: 32,
height: 32
});
map.fill(1); // fill entire map with 1
labyrinthos.mazes.RecursiveBacktrack(map, {});
console.log('RecursiveBacktrack', map);
// output maze with ASCII mask
console.log(map.mask());
});
</script>
Use Submaps
Using labyrinthos npm
package
Each TileMap
has a TileMap.use()
method which can be used to embed maps inside each other. The following example creates (4) quadrants:
import labyrinthos from 'labyrinthos';
// Main map - 8x8 = 64 tiles
const mainMap = new labyrinthos.TileMap({ width: 8, height: 8 });
// Sub maps - 4x4 = 16 tiles each
const subMap1 = new labyrinthos.TileMap({ width: 4, height: 4 });
const subMap2 = new labyrinthos.TileMap({ width: 4, height: 4 });
const subMap3 = new labyrinthos.TileMap({ width: 4, height: 4 });
const subMap4 = new labyrinthos.TileMap({ width: 4, height: 4 });
// Fill each submap with distinct values
subMap1.fill(1);
subMap2.fill(2);
subMap3.fill(3);
subMap4.fill(4);
// Position submaps in each quadrant of the main map
mainMap.use(subMap1, 0, 0); // Top-left quadrant
mainMap.use(subMap2, 4, 0); // Top-right quadrant
mainMap.use(subMap3, 0, 4); // Bottom-left quadrant
mainMap.use(subMap4, 4, 4); // Bottom-right quadrant
console.log('mainMap', mainMap);
console.log(mainMap.mask());
You can find more examples at: ./examples
TileMap
Class
let myMap = new LABY.TileMap({
x: 0,
y: 0,
width: 32,
height: 32
})
This will generate a new TileMap
instance with default data. From here we can run either a Maze
or Terrain
algorithm on the myMap
object like:
LABY.mazes.RecursiveBacktrack(myMap);
// shows myMap data array
console.log(myMap.data);
// renders myMap with default ASCII chart
console.log(myMap.mask());
TileMap.query(query)
Queries subsections of the map and returns a new TileMap
instance.
see: ./examples/tilemap-query.js
;
TileMap.use(tileMap)
Embed Maps / Nest Map / Use submaps. This is useful for creating larger composite maps and re-using maps.
see: ./examples/sub-maps.js
;
TileMap.mask(maskArray)
Apply custom mask to map data and view as ASCII text.
see: ./examples/roguelike-mask.js
TileMap.scaleToTileRange(tileRange)
The terrain generators will return a value from 0-1, this needs to be scaled to match a TileSet
whole integer index value.
For example, calling tileMap.scaleToTileRange(10)
, will scale all the values to a range of 0-9 using whole integers.
TileMap.toTiledJSON()
Exports the TileMap
to the Tiled data format.
Algorithms
Maze Generators
- [✅] - Aldous-Broder Algorithm
- [✅] - Binary Tree Algorithm
- [✅] - Cellular Automata
- [✅] - Eller's Algorithm
- [✅] - Growing Tree Algorithm
- [✅] - Recursive Backtracking
- [✅] - Recursive Division
- [✅] - Spiral Backtracking
- [✅] - Thomas Hunter
- [ ] - Trémaux's Algorithm
- [ ] - Random Walk
- [ ] - Maze Growing Algorithm (Seeded Growth)
- [ ] - Voronoi Diagrams
- [ ] - Randomized Prim's Algorithm
- [ ] - Randomized Kruskal's Algorithm
- [ ] - Wilson's Algorithm
- [ ] - Hunt-and-Kill Algorithm
- [ ] - Sidewinder Algorithm
- [ ] - Fractal Recursive Maze
Terrain Generators
- [✅] - Perlin Noise
- [✅] - Fault Line Algorithm
- [ ] - Diamond-Square Algorithm
- [ ] - Simplex Noise
- [ ] - Voronoi Diagrams
- [ ] - Midpoint Displacement
- [ ] - Cellular Automata (for terrain erosion)
- [ ] - Hybrid Multi-fractal Terrain Generation
- [ ] - Particle Deposition
- [ ] - Value Noise
Shapes
- [✅] - Circle
- [✅] - Square
- [✅] - Triangle
- [ ] - Hexagon
LSystem
- [✅] - Basic
- [✅] - Parameteric Rules using custom
function(context)
- [ ] - Parameteric Rules with Sutra.js
Tests
npm test
Contributing
If you have any issues using Labyrinthos.js or wish to improve the Labyrinthos.js please feel free to Open An Issue or Open A Pull Request.
Labyrinthos.js intends to support a wide variety or generators. Let's do this!
Discord Invite:: https://discord.gg/QgNAZhG9nF
License
Yantra Works 2023 AGPL