BlaiseLabs/procedural-almanac

Procedural drawing and motion techniques, each with its sources and short tests

Summary

procedural-almanac is a JavaScript library of 162 procedural-generation techniques for drawing, motion, world building, pathfinding, particles, and other graphics tasks. Each catalog entry provides a plain-English explanation, references or original-design notes, and corresponding checks; the repository currently documents 267 checks across the library.

What it is useful for

The library is aimed at creative coders, generative artists, 2D game developers, and engineers building worlds as data. It can replace repeated implementation of techniques such as seeded randomness, value and fractal noise, terrain and rivers, A* pathfinding, color manipulation, pixel rasterization, creature gaits, inverse-kinematic limbs, weather, and particle movement.

A concrete example in the README generates a deterministic deer using genomeFrom, gaitTiming, footStep, strideRate, and twoBoneLimb. The same seed produces the same deer, while the functions calculate its stride, foot movement, knee, and foot position. Another example constructs a terraced island with water, rivers, forests, villages, roads, a day-night cycle, and a storm entirely from code, without sprites or image assets.

The catalog also serves as a learning reference. Established techniques cite papers, books, standards, published code, or introductory material, while original techniques explain their purpose, inspiration, dependencies, and implementation.

It is explicitly not a game engine, physics library, or 3D renderer, and it does not provide or control the render loop. Developers call its functions directly and decide how to integrate them.

How engineers can use it

Install it directly from GitHub:

npm install github:BlaiseLabs/procedural-almanac

The library uses plain ES modules, has no runtime dependencies or build step, and supports modern browsers and Node.js 18 or later. Start with CATALOG.md to find a technique by name, read its references and checks, then import the corresponding function. For example:

import {
  SeededRandom,
  genomeFrom,
  gaitTiming,
  footStep,
  strideRate,
  twoBoneLimb
} from 'procedural-almanac';

Run npm test to execute the checks and catalog consistency rules; npm run docs regenerates the catalog and gallery. Canvas-based drawing, parts, and display modules require a canvas implementation in Node, configured with setCanvasMaker; the README demonstrates this with @napi-rs/canvas.

For the complete island example, follow the README’s browser import-map setup, or serve it locally:

python3 -m http.server 8000

Then open http://localhost:8000/examples/island/. The Node example can be run with node examples/island/island.mjs; producing its GIF and MP4 additionally requires ffmpeg.