p5.bitboard

p5.bitboard is a small addon for p5.quadrille.js that introduces bitboard-based grid representations. It enables fast and expressive manipulation of binary grids using JavaScript BigInt values.

This library is not standalone — it depends on p5.quadrille.js, which must be included first.

Installation

IIFE (CDN)

<script src="https://cdn.jsdelivr.net/npm/p5@latest/lib/p5.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5.quadrille@latest"></script>
<script src="https://cdn.jsdelivr.net/npm/p5.bitboard@latest"></script>

ES Modules (npm)

npm install p5 p5.quadrille p5.bitboard

Then import and use in your app:

import p5 from 'p5'
import Quadrille from 'p5.quadrille'
import Bitboard from 'p5.bitboard'

Overview

Create a bitboard from a BigInt, a binary string, or just call createBitboard() for an empty 8×8 grid.

const bb = createBitboard(3, 2, 0b111010n)

Like Quadrille, the bitboard stores binary content in a 2D grid, but optimized for bitwise operations.

Core Methods

| Method | Description | | ------------------ | ------------------------------------------ | | fill() | Fills the entire board | | fill(row) | Fills a full row | | fill(row, col) | Fills a single cell | | clear(...) | Same as fill, but clears instead | | toggle(...) | Toggles bits (all, row, or single) | | isFilled(r, c) | Returns true if cell is 1 | | randomize() | Shuffles 1s across random positions | | rand(n) | Fills n random 0s (or clears if n < 0) | | rotate() | Rotates the board 90° clockwise | | reflect() | Flips vertically | | transpose() | Swaps rows and columns | | shift() | Left shift with optional wrapping | | slide(dx,dy) | Slides all bits | | bounds() | Gets bounding box of 1s | | crop(r, c, w, h) | Returns cropped region | | toBinaryString() | Returns binary string | | bitboard | Raw BigInt getter | | order | Number of 1s |

Boolean Algebra

These methods work like Quadrille.algebra:

Bitboard.and(a, b)
Bitboard.or(a, b)
Bitboard.xor(a, b)
Bitboard.not(a)

You can also use them in-place:

bb.and(other)
bb.or(other)
bb.xor(other)
bb.not()

Iteration and Queries

Bitboards support iteration:

for (const { row, col, bit } of bb) {
  doSomething(row, col, bit)
}

You can also use a predicate with visit():

bb.visit(({ row, col, bit }) => {
  if (bit === 1) doSomething(row, col)
})

Or visit all cells:

bb.visit(({ row, col, bit }) => doSomething(row, col, bit))

Example

const bb = createBitboard(3, 1, 0b111n)
bb.fill(0, 1).clear(0, 0)
console.log(bb.toBinaryString()) // "110"

License

GPL-3.0-only — see License