p5.bitboard/README.md

A bitboard-based addon for p5.quadrille.js to teach and render grid-based logic in p5.js.

[![npm version](https://img.shields.io/npm/v/p5.bitboard.svg)](https://www.npmjs.com/package/p5.bitboard)

# p5.bitboard

`p5.bitboard` is a small addon for [p5.quadrille.js](https://github.com/objetos/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)

```html
<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)

```bash
npm install p5 p5.quadrille p5.bitboard
```

Then import and use in your app:

```js
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.

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

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

You can also use them in-place:

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

### Iteration and Queries

Bitboards support iteration:

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

You can also use a predicate with `visit()`:

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

Or visit all cells:

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

## Example

```js
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](./license.txt)