PuzzleScript: A DSL for Puzzle Game Design

• PuzzleScript is a domain-specific language for creating turn-based, grid-based puzzles with clearly defined syntax and semantics.
• Its design supports formal rule synthesis and automated playtesting through algebraic, SAT, and constraint programming methods.
• Automated pipelines and GPU-accelerated simulation underscore its impact on AI benchmarking, game design, and computational creativity research.

PuzzleScript is an expressive, domain-specific language and web-based engine for specifying and playing turn-based, grid-based puzzle games. It has become a locus of research in automated game synthesis, benchmarking of reasoning systems, and combinatorial game design, owing to its accessible yet highly constrained scripting language and its broad community adoption for both professional and amateur game creation.

1. Syntax and Semantics of the PuzzleScript Language

PuzzleScript uses a concise and highly structured DSL tailored for describing 2D gridworld puzzles. A complete PuzzleScript game is specified using dedicated sections:

• Object Definitions: Enumerates atomic game entities (Player, Crate, Wall, etc.).
• Legend: Aliases and semantic groupings of objects.
• Rules: The core logic, specified as rewrite rules (e.g., [ > Player | Crate ] -> [ > Player | > Crate ] describes pushing a crate forward).
• Win Conditions: Logical statements that determine game completion.
• Levels: ASCII-art layouts mapping symbols to objects.

The semantics of rules are those of pattern-directed rewrites over game states: at each turn, rules are evaluated sequentially and repeatedly applied until the state stabilizes. Force propagation (e.g., movement or pushing) is encoded by directional objects or meta-objects, and multiple rules can interact via grouped application.

PuzzleScript’s design intentionally constrains expressivity—certain classes of games (e.g., those requiring memory or complex temporal dynamics) are not directly expressible. However, this same rigidity is leveraged for precise automated analysis and reproducible gameplay (Earle et al., 6 Jun 2025, Earle et al., 22 Aug 2025).

2. Rule Formalization and Mathematical Definition

Recent formal results extend the PuzzleScript paradigm with mathematical frameworks for rule systematization. One approach, rooted in the systematization of pencil-style puzzles (Slitherlink, Sudoku), defines boards via coordinate-annotated grid points (p(i, j)), cells (c(i', j')), and edge sequences. Binary relations (H, V, D, M) encode adjacency and coincidence.

A key composition operator, combine(R, E), iteratively builds structures (closed loops, rooms) mapped by positional relationship sets $R$ over sequences $E$. This allows algebraic manipulation of puzzle rules as graph-theoretic constructs.

Domains $S$ for each structure are specified, with constraints formulated as logical predicates (e.g., for Slitherlink: $\forall p, \text{cross}(p) = 2$). This formalization enables translation of object-based rules from PuzzleScript into abstract algebraic and logical forms, supporting automated rule generation and validation (Maeda et al., 18 Dec 2024). Approximately one-fourth of Nikoli-style puzzles have been successfully encoded using this framework.

3. Reachability and Planning Encodings

PuzzleScript’s mechanics are substantially driven by questions of agent reachability and object manipulation. Grid-based reachability is encoded using several principal methods (Bofill et al., 2023):

• DAG Encoding: Vertices are assigned ordering variables; reachability is represented by propagation rules and constraints preventing cycles, using $O(NM)$ clauses and $O(N^2)$ Boolean variables.
• Path Encoding: Boolean variables designate inclusion in a source-target path, with degree constraints to enforce acyclicity. This method is compact ($O(N)$ size).
• Spanning Tree Encoding: The novel approach builds a tree rooted at the source, using variables for reachability and tree edges, with constraints ensuring mutual exclusion, acyclicity, and correct spanning of the connected component.

These encodings enable both SAT (Boolean satisfiability) and CP (constraint programming) approaches to model agent/object movement and solve for optimal action sequences, often ignoring trivial agent walking to focus on meaningful object actions.

4. Automated Game Design and Validation Workflows

The process of game creation, analysis, and validation in the PuzzleScript ecosystem is increasingly automated. Notably:

• LLM-Driven Game Generation: ScriptDoctor (Earle et al., 6 Jun 2025) uses LLMs prompted with human-authored examples to synthesize PuzzleScript code. Compiler errors from the engine are looped back as repair cues, and synthesized games are tested via breadth-first search (BFS) playtesting. The iterative process $C_{i+1} \gets F(C_i, E_i, P_i)$ formalizes the refinement loop, where levels must meet playability thresholds (e.g., solution length > 10 moves).
• Automated Playtesting Agents: BFS solvers play through generated levels to validate solvability and assess complexity, returning metrics such as node count and solution length. Search-based evaluation is computationally bounded (e.g., 1 million node expansions).

This has established automated pipelines whereby PuzzleScript games are generated, compiled, and rigorously playtested without direct human intervention, framing AGD (Automatic Game Design) as an open-ended, LLM-driven optimization loop.

5. Hardware-Accelerated Simulation and Benchmarking

PuzzleJAX (Earle et al., 22 Aug 2025) translates PuzzleScript’s DSL into a GPU-accelerated simulation platform using JAX. Rewrite rules are compiled into convolutional kernels applied to multihot binary encodings of states, with kernel matching and projection performed via nested while loops. This enables rapid, high-throughput simulation suitable for benchmarking both tree search and learning agents.

PuzzleJAX maintains full interoperability with the original PuzzleScript language, parsing existing games via context-free grammars and supporting advanced scripting features. Convolutional execution yields fast per-step runtime, offsetting longer compile times incurred by rule expansion and loop nesting.

Empirical performance analysis shows:

• Tree Search: BFS solves most simple PuzzleScript games within hundreds to thousands of iterations (e.g., Sokoban Basic solved at 900 iterations), but more complex levels exceed feasible brute-force bounds.
• Reinforcement Learning: PPO agents trained on PuzzleJAX representations improve heuristic rewards quickly, but often converge to deadlocks or suboptimal local minima due to sparse rewards and intricate puzzle dependencies.
• LLMs: Most tested LLM agents demonstrate near-zero win rates except for the simplest puzzles, highlighting a discrepancy between brute-force search success and LLM reasoning.

This demonstrates that, despite the accessible formalism, PuzzleScript-derived games manifest significant planning and reasoning challenges for current agent architectures.

6. Complexity, Difficulty, and Planning Metrics

Work on planning encodings reveals that perceived puzzle difficulty in the PuzzleScript domain is primarily a function of “object actions”—pushes, rolls, stacks—rather than agent traversal. SAT-based formulations efficiently solve for optimal object action sequences by sidelining trivial walk actions.

Empirical results show that:

• Time-to-solution drops substantially when excluding agent walking from plan enumeration.
• The spanning tree encoding outperforms DAG and path encodings in parallel settings, yielding lower PAR-2 scores and fewer timeouts on hundreds of Sokoban and Snowman instances.
• Difficulty metrics derived from required object actions serve both as solver guides and as quantitative feedback for level designers or automated puzzle generators (Bofill et al., 2023).

This focus on object manipulation informs both solver/practitioner strategy and evaluation of game design within PuzzleScript.

7. Broader Implications and Systematization

PuzzleScript, as illuminated by recent formal and algorithmic advances, is a platform at the intersection of combinatorial game design, automated reasoning, and computational creativity. Mathematical frameworks for rule synthesis (Maeda et al., 18 Dec 2024) offer a pathway for systematic, AI-assisted generation of new puzzle genres. Automated pipelines leveraging LLMs and search agents (Earle et al., 6 Jun 2025) redefine game design as an iterative, data-driven process.

PuzzleJAX’s hardware-enabled simulation underscores a research trajectory toward benchmarking AI agents on human-relevant but challenging puzzles. Observable performance gaps between search, learning, and LLM agents motivate ongoing methodological development.

A plausible implication is that further integration of algebraic rule systematization with scalable simulation and LLM-driven synthesis will continue to expand not only the taxonomic diversity of PuzzleScript puzzles but also the capacities of reasoning agents—offering both challenge and opportunity to fields spanning AI, computational creativity, and educational technology.