Quadrille API

Welcome to the Quadrille API, a versatile tool designed for creating and managing layers of data cells for various applications, particularly board games. The comprehensive Quadrille API allows you to represent and manipulate these layers dynamically, enabling intricate designs and logic. Below is an interactive snippet that demonstrates the Quadrille API in action.

Features of Quadrille

1. Data Storage
   Quadrille cells can store any valid JavaScript value, with empty cells represented as null. If a cell is filled with an undefined value, it is automatically converted to null and treated as empty. The library enforces a key invariant: quadrilles are always square, matrix-like objects where each row has the same number of columns, and empty cells are consistently filled with null values.

2. Rendering
   By default, the library renders cells filled with colors, numbers, strings, images & videos, p5.Graphics, or even (drawing) functions. These default rendering behaviors can be overridden to suit specific requirements.

3. Multi-Layer Capability
   Multiple quadrilles can be superimposed to form layers, with each layer representing distinct elements or states. Quadrilles are layered back-to-front based on their drawing order. This feature is particularly useful in games where players or objects need separation.

4. Quadrille Aggregation
   Quadrilles support aggregation during creation, filling, or through static boolean operators, a powerful feature dubbed Quadrille Algebra. For instance, the Quadrille.or operator is used to combine multiple layers into the aggregate shown above, effectively merging data from different quadrilles.

In the snippet above, you’ll see how layers of quadrilles manage different types of data, such as colors, strings, images, videos, and custom graphical elements. Aggregation further enhances this flexibility, allowing you to seamlessly merge and interact with combined data dynamically. The setup enables toggling visibility, aggregating layers, and validating game states interactively.

Example: Tic Tac Toe

The Quadrille API can be highlighted by implementing Tic Tac Toe in two distinct ways: using multiple layers or a single aggregate layer.

1. Using Multiple Layers

In this approach, you’ll store each player’s moves in separate quadrilles (player1 and player2). This separation simplifies processing each player’s moves but may require additional synchronization logic to handle interactivity across layers.

Define Winning Patterns

Winning patterns—rows, columns, and diagonals—are shared between players and manually defined using base quadrilles:

User Interaction

Players interact by clicking on cells to make their moves. The process involves:

• Checking that the clicked cell is within bounds, determined by the Quadrille’s mouseRow and mouseCol properties.
• Ensuring the selected cell is empty in both the current and the opponent’s quadrille, using the isEmpty(row, col) method.
• Updating the current player’s turn using the player1 and player2 order property.

Once validated, the move is filled into the current player’s quadrille, and a winner check is performed.

Check for Winner

After each move, the current player’s quadrille is checked against the predefined winning patterns using search(pattern, false). This method ensures that the cells occupied by the player match a winning configuration, with disregard of the actual values. If a match is found, the player is declared the winner.

2. Using an Aggregate Layer

This approach uses a single shared game quadrille to track the entire game state. Player 1’s moves are represented by 'X', and Player 2’s by 'O'. While this approach simplifies interaction logic you’ll still need to define separate winning patterns for each player.

Define Winning Patterns

Separate arrays of quadrilles are used to store each player’s winning patterns—rows, columns, and diagonals. Player 1 ('X') and Player 2 ('O') will each have their own unique set of patterns.

User Interaction

Players interact by clicking on cells to make their moves. The process involves:

• Verifying that the clicked cell is within bounds using the game mouseRow and mouseCol properties.
• Checking that the selected cell is unoccupied using the game isEmpty(row, col) method.
• Updating the cell with the symbol corresponding to the current player, determined by the game order property.

If the cell is valid, the move is filled into the shared game quadrille, and the check for a winner follows.

Check for Winner

Winning patterns for the current player are checked against the shared game state using search(pattern, true). Strict matching ensures that the cells occupied match a winning configuration, along with their values. If a match is found in either player’s array of patterns, the respective player is declared the winner.

How to Read This API

The Quadrille API is designed with a “learn by example” strategy to help you quickly understand and apply its features. Each API entry includes practical examples that demonstrate how the commands work, making it easier to integrate them into your projects.

Tips for Learning the API

1. Comprehensive Reading
   The API is complete, covering all essential commands and methods, so it’s a good idea to read through the entire documentation before diving into specific tasks. This approach is akin to reading an entire exam before answering questions—it gives you a clear overview of the tools at your disposal. Maximizing API usage is especially important in object-oriented programming, as it streamlines development and is less error-prone. Start with the createQuadrille and drawQuadrille functions, as they are present in nearly all applications of the library.

2. Start with Tic Tac Toe
   To get hands-on experience, begin by implementing the Tic Tac Toe game following your favorite strategy or explore both approaches: using multiple layers or a single aggregate layer. This exercise will help you familiarize yourself with the API core concepts and capabilities.

By combining these strategies, you’ll build a strong understanding of the Quadrille API and how to use it effectively in your projects.

Hacking

Hack a p5.quadrille.js intro sketch in the p5.js Web Editor and start coding right away.