rot.js Roguelike Toolkit

You can include rot.js in your project using several methods:

• npm: Install via the rot-js package.
• Direct Download: Download the prebuilt dist/rot.js or the minified dist/rot.min.js files.
• Source: Clone the repository for full source code access.

npm install rot-js

Rot.js is written in TypeScript and is available in multiple formats for browser environments:

1. ES2015 Modules: Use the code in the lib/ directory for modern browsers. These can be used directly without transpilation or can be bundled using tools like Rollup or Babel (recommended for production).
2. Pre-built Bundle: Include dist/rot.js (or the minified dist/rot.min.js) via a traditional <script> tag. This version uses ES5 and places the library into a global ROT namespace.

Most parts of rot.js are compatible with Node.js. When using the Display class in a server-side environment, you must specify the "term" layout backend to output to the terminal.

The pre-bundled package can be loaded as a CommonJS module.

let display = new ROT.Display({width:40, height:9, layout:"term"});
display.draw(5,  4, "@");
display.draw(15, 4, "%", "#0f0");          // foreground color
display.draw(25, 4, "#", "#f00", "#009");  // and background color

When instantiating the Rogue class, you can provide a partial Options object to customize the layout:

• cellWidth (number): The number of cells to create horizontally.
• cellHeight (number): The number of cells to create vertically.
• roomWidth ([number, number]): An array containing the [min, max] width for rooms. If not provided, it is calculated automatically based on cellWidth.
• roomHeight ([number, number]): An array containing the [min, max] height for rooms. If not provided, it is calculated automatically based on cellHeight.

Convert a Color array [r, g, b] to a standard web string format. Both methods automatically clamp values between 0 and 255.

• toRGB(color): Returns an rgb(r,g,b) string.
• toHex(color): Returns a #rrggbb hex string.

The Corridor class defines a path between two points.

Manual Construction

Use new Corridor(startX, startY, endX, endY) to define a corridor between two specific coordinates.

Randomized Generation

• Corridor.createRandomAt(x, y, dx, dy, options): Creates a corridor of random length starting at (x, y) and extending in direction (dx, dy).

Options

When using randomized methods, provide a CorridorOptions object:

• corridorLength: [min, max] number range.

Digging

Use create(digCallback) to apply the corridor to your map. The digCallback receives (x, y, value) where value is 0 (empty space).

To ensure the corridor doesn't leave awkward gaps at its end, you can use createPriorityWalls(priorityWallCallback) to place walls at the terminal points of the corridor.

Both Room and Corridor provide an isValid method to check if a feature can be placed without violating map constraints.

isValid(isWallCallback, canBeDugCallback) requires two callbacks:

• isWallCallback(x, y): Returns true if the position is a wall.
• canBeDugCallback(x, y): Returns true if the position can be dug (e.g., is currently empty or a specific type of terrain).

The RNG class provides various methods for generating different types of random values, including uniform distributions, normal distributions, and weighted selections. It uses the Alea algorithm for high-quality pseudorandom numbers.

Key methods include:

• getUniform(): Returns a value in the range [0, 1).
• getUniformInt(lowerBound, upperBound): Returns an integer between lowerBound and upperBound (inclusive).
• getNormal(mean, stddev): Returns a normally distributed value.
• getPercentage(): Returns an integer between 1 and 100 (inclusive).
• getItem(array): Returns a random item from an array, or null if the array is empty.
• shuffle(array): Returns a new array containing the same items in a randomized order.
• getWeightedValue(data): Returns a key from an object where values represent relative weights/probabilities.