p5.quadrille.js

Welcome to the p5.quadrille.js source code repository. This open-source p5.js addon library offers a simple yet powerful API for grid-based creative coding, game design, and visual computing. Most methods are demonstrated with interactive sketches for hands-on exploration.

Paintings sorted according to their luma using quadrille sort

• Usage
  • CDN
  • npm (ESM)
• Algorithms & Performance
• Adoption
• Releases
• System Requirements
• Contribute
  • Support
  • Open TODOs
• Further Reading

Usage

Using p5.quadrille.js can be as minimal or as interactive as you need:

• 2 steps — storage only: declare and create the quadrille.
• 3 steps — add rendering: use drawQuadrille() in draw().
• 4 steps — add interactivity: call a mutator method (e.g. fill(), clear(), replace()) inside an event like keyPressed() or mousePressed().

The library works in two setups:

• CDN: Use the IIFE (Immediately Invoked Function Expression) format with <script> tags directly in the browser, along with p5.js.
• npm: Use the ES module version in modern projects with Vite or another bundler.

CDN

Include both libraries using <script> tags, which run in both global and instance mode.

<!-- index.html -->
<!-- Load p5.js first (required by p5.quadrille.js, latest version) -->
<script src="https://cdn.jsdelivr.net/npm/p5/lib/p5.min.js"></script>
<!-- Load p5.quadrille.js (latest stable version) -->
<script src="https://cdn.jsdelivr.net/npm/p5.quadrille/dist/p5.quadrille.min.js"></script>
<script>
  let q // Step 1: Declare

  function setup() {
    createCanvas(600, 400)
    q = createQuadrille(6, 4, 10, '🐲') // Step 2: Create
  }

  function draw() {
    background(0)
    drawQuadrille(q) // Step 3: Render
  }

  function mousePressed() {
    q.randomize() // Step 4: Interact
  }
</script>

You can run the example, which uses global mode, by opening the index.html file in a browser, or by using VSCodium (recommended) or Visual Studio Code with the Live Server extension.

npm (ESM)

Install both p5 and p5.quadrille as dependencies:

npm i p5 p5.quadrille

Then import them in your project's entry file (e.g., main.js) using a modern bundler like Vite, which runs in instance mode only:

// main.js
import p5 from 'p5'
import Quadrille from 'p5.quadrille'

const sketch = p => {
  let q // Step 1: Declare

  p.setup = () => {
    p.createCanvas(600, 400)
    q = p.createQuadrille(6, 4, 10, '🐲') // Step 2: Create
  }

  p.draw = () => {
    p.background(0)
    p.drawQuadrille(q) // Step 3: Render
  }

  p.mousePressed = () => {
    q.randomize() // Step 4: Interact
  }
}

new p5(sketch)

This approach gives you full modularity and clean instance isolation using modern JavaScript tooling.

Algorithms & Performance

Let n be the total number of cells in the quadrille.

• Grid Operations: O(n) — Covers transformations and cell iteration performed with for...of loops.

• Image Filtering: O(n × k²) — Where k is the kernel width/height (assumed square).
• Pattern Search & Merging: O(n × m) — Where m is the number of cells in the pattern or quadrille being searched/merged.
• Drawing: O(n) — Efficient rendering using the p5.js canvas.

Observations:

• Optimized for grid-based games and interactive applications, including WebGL-heavy scenarios. Supports rendering JavaScript functions via p5.Framebuffer for advanced effects.
• Produces deterministic results—identical inputs always yield the same outputs.
• Maintains a clear distinction between mutable and immutable methods, promoting API integrity and predictable behavior.

Adoption

• Tested in real-world scenarios:
  – Object-Oriented Programming courses at UNAL.
  – National and international game jams with the UNGames group.
• Fosters creativity and problem-solving in both classroom and jam settings.
• Publicly showcased at objetos.github.io/docs/showcase, featuring student projects, games, and demos.

Releases

• Latest (v3.3.5):
  These links always point to the latest stable version on npm.

  • p5.quadrille.js (unminified)
  • p5.quadrille.min.js (minified)
  • npm package

• Current tagged version (v3.3.5):
  Use these if you want to lock to a specific version.

  • [email protected] (unminified)
  • [email protected] (minified)
  • npm package (v3.3.5)

• Legacy (v2.x):
  GitHub CDN links compatible with p5 v1.

  • p5.quadrille.js (GitHub CDN)
  • All GitHub releases

System Requirements

• Hardware: Any modern device—PC, phone, or tablet—with a browser supporting ES6 (Firefox 54+, Chrome 51+, Safari 10+, Edge 15+, Opera 38+).
• Software: Like any p5.js sketch—just include p5.js and p5.quadrille.js via local file or CDN.

Observation: The library leverages p5.js for rendering and modern browser APIs for performance. WebGL enhances 3D/GPU examples but is optional.

Contribute

Your contributions are welcome!

Support

Use the bug report or feature request templates to report issues or suggest new features.

Open TODOs

Fork the repo and submit a pull request to help with any of the following (GitHub Guide):

1. Implement isPolyomino()
2. Add perlin() and simplex() noise-based utilities
3. Extend sort() to support 'webgl' mode — requires Framebuffer support for sample() (currently limited to the P2D renderer)
4. Add WEBGL support for screenRow() and screenCol() — may depend on features from p5.treegl

Further Reading

• 
  Always use the latest version of p5.quadrille.js from npm. Supports modern p5.js v2 and includes ESM and IIFE builds.
  Install with npm i p5.quadrille.
• 
  The creative coding library powering this project. From newcomers to advanced users—explore the reference, examples, tutorials, and libraries.
• 
  Browse the full API reference, including all methods, usage patterns, and detailed explanations—each with interactive examples. Start with createQuadrille() and drawQuadrille(), then explore shape manipulation, color handling, I/O, WebGL rendering, and more.
• 
  An evolving educational resource covering:
  – Object-Oriented and Functional Programming essentials
  – Game design principles
  – Tutorials & step-by-step guides
  – Real-world projects by students and jam participants
  – Advanced demos by the author
• 
  Published in SoftwareX. Goes beyond technical documentation—explains the motivation, research hypothesis, design rationale, and internal architecture of p5.quadrille.js.
• 
  Official GitHub repository.
  – Fork the repo and contribute via pull requests (GitHub Guide)
  – Use the bug report or feature request templates for support
• 
  Experimental features, new ideas, and early previews shaping future versions of the library.