forma

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 43 Open GitHub ↗

A Lua toolkit for computational geometry on a grid

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# forma

[![Build Status](https://github.com/nhartland/forma/actions/workflows/tests.yaml/badge.svg)](https://github.com/nhartland/forma/actions/workflows/tests.yaml)
[![Coverage Status](https://coveralls.io/repos/github/nhartland/forma/badge.svg?branch=master)](https://coveralls.io/github/nhartland/forma?branch=master)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**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, insertion, 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](https://en.wikipedia.org/wiki/Moore_neighborhood), [von
Neumann](https://en.wikipedia.org/wiki/Von_Neumann_neighborhood)).

## Examples

```lua
-- 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:

```Shell
    luarocks install forma
```

## Documentation

Documentation is hosted [here](https://nhartland.github.io/forma/).

To regenerate the documentation locally:

```Shell
    lua docs/extract.lua
    mkdocs build
```

This requires [lua-language-server](https://github.com/LuaLS/lua-language-server),
[dkjson](https://luarocks.org/modules/dhkolf/dkjson), and
[MkDocs Material](https://squidfunk.github.io/mkdocs-material/).

## Testing

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

- [LuaCov](https://keplerproject.github.io/luacov/)
- [luaunit](https://github.com/bluebird75/luaunit)

To run the tests use

luarocks test

forma

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README