forma

2D grid shape generation in Lua

forma is a utility library for the procedural generation and manipulation of shapes on a two dimensional grid or lattice. It came about as part of experiments in making roguelike games. forma is therefore particularly suited (but not limited) to the generation of roguelike environments.

Features

A spatial-hashing pattern class with sparse set storage for fast lookup and removal of active cells.
Pattern manipulators such as union, subtraction, intersection, XOR, rotation, reflection, dilation, erosion, opening, closing and morphological gradient.
Rasterisation algorithms for 2D primitives, e.g lines, circles, squares and Bezier curves.
A multipattern class for handling collections of patterns with batch operations.
A raycasting tool for computing visible areas from a source cell.
A very flexible cellular automata implementation with
Synchronous and asynchronous updates
Combination of multiple rule sets
Pattern sampling algorithms including
Random (white noise) sampling
Perlin noise sampling
Poisson-disc sampling
Mitchell's best-candidate sampling
Algorithms for subpattern finding including
Flood-fill contiguous segment finding
Convex hull finding
Pattern exterior/interior hull finding
Pattern thinning/skeletonisation
Binary space partitioning
Voronoi tessellation / Lloyd's algorithm

Results can be nested to produce complex patterns, and all of these methods are able to use custom distance measures and definitions of the cellular neighbourhood (e.g Moore, von Neumann).

Examples

Example Gallery

-- Generate a square box to run the CA inside
local domain = primitives.square(80,20)

-- CA initial condition: 800-point random sample of the domain
local ca = domain:sample(800)

-- Moore (8-cell) neighbourhood 4-5 rule
local moore = automata.rule(neighbourhood.moore(), "B5678/S45678")

-- Run the CA until converged or 1000 iterations
local ite, converged = 0, false
while converged == false and ite < 1000 do
    ca, converged = automata.iterate(ca, domain, {moore})
    ite = ite+1
end

-- Access cell coordinates for external use
for icell in ca:cells() do
    -- local foo = bar(icell)
    -- or
    -- local foo = bar(icell.x, icell.y)
end

-- Find all 4-contiguous connected components of the CA pattern
-- Uses the von Neumann neighbourhood to determine 'connectedness'
-- but any custom neighbourhood can be used.
local connected_components = ca:connected_components(neighbourhood.von_neumann())

-- Print a representation to io.output
connected_components:print(nil, domain)

Installation

forma is compatible with Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT 2.0, 2.1. The library is written in pure Lua, no compilation is required. Including the project is as simple as including the forma directory in your project or Lua path.

The easiest way to do this is via LuaRocks. To install the latest stable version use:

    luarocks install forma

Documentation

Documentation is hosted here.

Generating the documentation requires

LDoc

Simply running

ldoc --style=./ --output contents --dir docs .

in the root directory should generate all the required pages.

Testing

Unit tests and coverage reports are provided. The test suite requires

To run the tests use

luarocks test

forma

Contents

Readme

Modules

Examples

forma

Features

Examples

Installation

Documentation

Testing