### STARTLOOP/ENDLOOP Example in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/executionorder

Demonstrates the alternative STARTLOOP/ENDLOOP syntax for creating a loop structure in PuzzleScript rules. This is functionally equivalent to a standard rule-group for this specific Sokoban example, iterating rules until no changes occur.

```puzzlescript
STARTLOOP
DOWN [ crate | up player ] -> [ up crate | up player ]
DOWN [ down player | crate ] -> [ down player | down crate ]
RIGHT [ crate | left player ] -> [ left crate | left player ]
RIGHT [ right player | crate ] -> [ right player | right crate ]
ENDLOOP
```

--------------------------------

### Rule Execution on Level Start

Source: https://www.puzzlescript.net/Documentation/prelude

Applies rules once at the beginning of a level before the player sees it. Useful for procedural generation or initial setup.

```puzzlescript
run_rules_on_level_start

```

--------------------------------

### Rule Application Example (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/executionorder

Demonstrates how rules are applied sequentially and how the order matters in PuzzleScript. This example shows a player pushing crates.

```puzzlescript
[ > Crate | Crate ] -> [ > Crate | > Crate ]
[ > Player | Crate ] -> [ > Player | > Crate ]
```

--------------------------------

### Install a Checkpoint in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

Installs a checkpoint at the player's current location. When the player restarts, they will spawn at this checkpoint instead of the level's start. This command is placed after the player's save point.

```puzzlescript
late [ Player SavePoint ] -> CHECKPOINT
```

--------------------------------

### Flick Screen Camera Setup

Source: https://www.puzzlescript.net/Documentation/prelude

Divides the level into a grid and zooms the camera to show only one cell at a time. The camera 'flicks' to new positions as the player moves between grid cells.

```puzzlescript
flickscreen WxH

```

--------------------------------

### Combine Commands in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

Demonstrates combining multiple commands or a command with a regular rule. This example shows playing a sound effect (SFX3) when a checkpoint is triggered, and another example shows a message displayed when two entities collide.

```puzzlescript
late [ Player Shadow ] -> CHECKPOINT SFX3
```

```puzzlescript
[ > Player | Person ] -> [ < Player | Person ] message Woah, buddy, back off!
```

--------------------------------

### Rule Assembly Debug Output Example

Source: https://www.puzzlescript.net/Documentation/prelude

Illustrates the compiled output of a PuzzleScript rule when the 'debug' option is enabled. Shows how rules are broken down into engine-executable instructions.

```text
=========== 
Rule Assembly : (4 rules)
===========
  (83) DOWN [ crate | up player ] -> [ up crate | up player ]
+ (83) DOWN [ down player | crate ] -> [ down player | down crate ]
+ (83) RIGHT [ crate | left player ] -> [ left crate | left player ]
+ (83) RIGHT [ right player | crate ] -> [ right player | right crate ]
===========

```

--------------------------------

### Rule Compilation Example (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/executionorder

Illustrates how a single PuzzleScript rule can be compiled into multiple simpler rules by the interpreter. This shows the internal representation before execution.

```puzzlescript
Rule Assembly : (4 rules)
===========
  (81) DOWN [ crate | up player ] -> [ up crate | up player ]
+ (81) DOWN [ down player | crate ] -> [ down player | down crate ]
+ (81) RIGHT [ crate | left player ] -> [ left crate | left player ]
+ (81) RIGHT [ right player | crate ] -> [ right player | right crate ]
===========
```

--------------------------------

### Standard Rule-Group Equivalent in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/executionorder

Shows the compiled rule-group equivalent for the Sokoban example, illustrating how the STARTLOOP/ENDLOOP construct achieves the same result as a standard rule-group. Each rule is evaluated independently.

```puzzlescript
DOWN [ crate | up player ] -> [ up crate | up player ] 
+ DOWN [ down player | crate ] -> [ down player | down crate ]
+ RIGHT [ crate | left player ] -> [ left crate | left player ] 
+ RIGHT [ right player | crate ] -> [ right player | right crate ]
```

--------------------------------

### PuzzleScript: Crate Interaction with Aliases

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Shows a simple example of modeling two crate types ('OrangeCrate', 'BlueCrate') using an alias 'Crate' in PuzzleScript. This allows for more concise rule definitions when objects share similar behaviors.

```puzzlescript
Edit======
LEGEND
======

Crate = OrangeCrate or BlueCrate

======
RULES 
====== 

[ > Player | Crate ] -> [ > Player | > Crate ] 
[ > Crate | Crate ] -> [ > Crate | > Crate ]
```

--------------------------------

### PuzzleScript Level Definition Example

Source: https://www.puzzlescript.net/Documentation/levels

Defines the layout of a game level in PuzzleScript, including the grid, object placements, and optional messages. Levels are separated by blank lines. This format does not support branching.

```puzzlescript
=======
LEVELS
=======

#########
#.......#
#.*.*.O.#
#..*..O.#
#.P.*.*.#
#.......#
#########

MESSAGE Woah, that was tough, eh?!

#########
#.....@.#
#.P.*.O.#
#.......#
#########

#########
#.....@.#
#.P.*.O.#     
#.......#
#########

MESSAGE Thank you for playing the game.
```

--------------------------------

### Identify Real-time vs. Player Input Ticks in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/realtime

Provides example patterns to distinguish between game ticks that occur in real-time and those triggered by player input. This helps in creating distinct game logic for each type of tick.

```puzzlescript
(only triggers on real-time ticks)
[ stationary Player ] [ a ] -> [ Player ] [ b ]
```

```puzzlescript
(only triggers in response to player input)
[ moving Player ] [ c ] -> [ moving Player ] [ d ]
```

--------------------------------

### Kitty and Fruit Interaction Rule in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules101

This example shows a Kitty sprite interacting with Fruit. The first rule makes the Kitty move to the Fruit's position, and the second rule prevents the Kitty from moving on its own after the interaction.

```puzzlescript
Edit[ > Kitty | ... | Fruit ] -> [ | ... | Kitty ]
[ > Kitty ] -> [ Kitty ]
```

--------------------------------

### Rule: Multiple Ellipses in Pattern

Source: https://www.puzzlescript.net/Documentation/rules

This example demonstrates the use of two ellipses within a single rule pattern. It's important to use multiple ellipses cautiously as it can impact performance.

```puzzlescript
(92) [ > Player | ... | Crate | ... | Crate ] -> [ > Player | ... | > Crate | ... | Crate ]
```

--------------------------------

### Eyeball Following Player Rule in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules101

An example of an 'Editlate' rule where an Eyeball sprite moves towards the Player. The '...' wildcard allows for any tiles between the Eyeball and the Player, making the rule flexible.

```puzzlescript
Edit[ Eyeball | ... | Player ] -> [ > Eyeball | ... | Player ]
```

--------------------------------

### Project Metadata and Editor Settings

Source: https://www.puzzlescript.net/Documentation/prelude

Sets the game's title, author, and homepage. Configures editor behavior like key repeat interval and enables/disables specific player actions or game mechanics.

```puzzlescript
title 2D Whale World
author increpare
homepage www.increpare.com

require_player_movement
key_repeat_interval 0.12

```

--------------------------------

### Background and Text Color Settings

Source: https://www.puzzlescript.net/Documentation/prelude

Defines the background and text colors for title/message screens and the website. Accepts color names or hex codes.

```puzzlescript
background_color blue

```

--------------------------------

### PuzzleScript: Loop Equivalent to Rule Grouping

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Shows how a 'STARTLOOP'/'ENDLOOP' block containing individual rules is functionally equivalent to grouping those rules with the '+' operator in PuzzleScript, when not dealing with 'rigid' rules.

```puzzlescript
Edit[ > Player | Crate ] -> [ > Player | > Crate ] 

[ > OrangeCrate | OrangeCrate ] -> [ > OrangeCrate | > OrangeCrate ]
+ [ > OrangeCrate | BlueCrate ] -> [ > OrangeCrate | > BlueCrate ]
+ [ > BlueCrate | OrangeCrate ] -> [ > BlueCrate | > OrangeCrate ]
+ [ > BlueCrate | BlueCrate ] -> [ > BlueCrate | > BlueCrate ]
```

--------------------------------

### Action Key Repeat Behavior

Source: https://www.puzzlescript.net/Documentation/prelude

Controls whether the action key can be repeatedly triggered by holding it down. 'norepeat_action' ensures it only responds to individual presses.

```puzzlescript
norepeat_action

```

--------------------------------

### Color Palette Configuration

Source: https://www.puzzlescript.net/Documentation/prelude

Specifies the color palette to be used in the game. Supports predefined palettes by name or numerical index.

```puzzlescript
color_palette mastersystem

```

--------------------------------

### PuzzleScript: Using STARTLOOP and ENDLOOP for Repetitive Rules

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Introduces the 'STARTLOOP' and 'ENDLOOP' keywords in PuzzleScript. These are used to group and repeat a set of rules, which is particularly useful for handling interactions between multiple instances of the same object types without excessive repetition.

```puzzlescript
Edit[ > Player | Crate ] -> [ > Player | > Crate ] 

startLoop

[ > OrangeCrate | OrangeCrate ] -> [ > OrangeCrate | > OrangeCrate ]
[ > OrangeCrate | BlueCrate ] -> [ > OrangeCrate | > BlueCrate ]
[ > BlueCrate | OrangeCrate ] -> [ > BlueCrate | > OrangeCrate ]
[ > BlueCrate | BlueCrate ] -> [ > BlueCrate | > BlueCrate ]

endLoop
```

--------------------------------

### Real-time Game Engine Interval

Source: https://www.puzzlescript.net/Documentation/prelude

Sets the interval for real-time game engine ticks. Allows for games that progress independently of player input.

```puzzlescript
realtime_interval

```

--------------------------------

### PuzzleScript Gravity Implementation with Direction Restriction

Source: https://www.puzzlescript.net/Documentation/directions

Shows how to implement gravity in PuzzleScript by restricting a rule to the DOWN direction. It illustrates a more verbose method and a simpler, equivalent alternative.

```PuzzleScript
DOWN [ stationary Object ] -> [ > Object ]
```

```PuzzleScript
DOWN [ stationary Object ] -> [ DOWN Object ]
```

```PuzzleScript
[ stationary Object ] -> [ DOWN Object ]
```

--------------------------------

### PuzzleScript: Rigid Rules with Multiple Block Types

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Illustrates how to manage interactions between different types of blocks using rigid rules. It shows that any rule causing motion to a 'BigBlock' must be marked as 'rigid' to ensure consistent behavior.

```puzzlescript
Edit[ > Player | LittleBlock ] -> [ > Player | > LittleBlock ]
[ > LittleBlock | LittleBlock ] -> [ > LittleBlock | > LittleBlock ]

rigid [ > LittleBlock | BigBlock ] -> [ > LittleBlock | > BigBlock ]
+ rigid [ > Player | BigBlock ] -> [ > Player | > BigBlock ] 
+ rigid [ moving BigBlock | BigBlock ] -> [ moving BigBlock | moving BigBlock ]
+ [ > BigBlock | LittleBlock ] -> [ > BigBlock | > LittleBlock ]
```

--------------------------------

### PuzzleScript: Basic Rigid Rule Application

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Demonstrates the basic application of the 'rigid' keyword in PuzzleScript to ensure that a rule only applies if all specified conditions are met. This prevents partial rule application in complex scenarios.

```puzzlescript
Editrigid [ > Player | BigBlock ] -> [ > Player | > BigBlock ] 
+ rigid [ Moving BigBlock | BigBlock ] -> [ Moving BigBlock | Moving BigBlock ]
```

--------------------------------

### Basic Rule: Player Pushing Crate

Source: https://www.puzzlescript.net/Documentation/rules

This rule demonstrates the fundamental pattern matching and replacement in PuzzleScript. It looks for a player moving towards a crate and updates the crate's state to reflect the movement.

```puzzlescript
[ > Player | Crate ] -> [ > Player | > Crate ]
```

--------------------------------

### Rule Grouping with '+' (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/executionorder

Shows how to group multiple PuzzleScript rules into a single 'rule group' using the '+' symbol. This allows for more complex conditional logic and simultaneous rule application within a group.

```puzzlescript
[ > Player | Crate ] -> [ > Player | > Crate ]
+ [ < Player | Crate ] -> [ < Player | < Crate ]
```

--------------------------------

### PuzzleScript: Crate Interaction Without Aliases

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Demonstrates defining interactions for individual crate types ('OrangeCrate', 'BlueCrate') when aliases are not used or allowed. This leads to more verbose rule sets.

```puzzlescript
Edit[ > Player | Crate ] -> [ > Player | > Crate ] 

[ > OrangeCrate | OrangeCrate ] -> [ > OrangeCrate | > OrangeCrate ]
[ > OrangeCrate | BlueCrate ] -> [ > OrangeCrate | > BlueCrate ]
[ > BlueCrate | OrangeCrate ] -> [ > BlueCrate | > OrangeCrate ]
[ > BlueCrate | BlueCrate ] -> [ > BlueCrate | > BlueCrate ]
```

--------------------------------

### Debug Mode for Rule Compilation

Source: https://www.puzzlescript.net/Documentation/prelude

Enables debug output, showing the compiled instructions for rules. Useful for understanding how PuzzleScript interprets and transforms game rules.

```puzzlescript
debug

```

--------------------------------

### PuzzleScript Win Condition Formats

Source: https://www.puzzlescript.net/Documentation/winconditions

Demonstrates the syntax for various built-in win conditions in PuzzleScript. These conditions specify how a player wins the game, such as clearing all items or achieving a specific state.

```puzzlescript
No Fruit

All Target On Crate

Some Love

Some Gold on Chest

No Gold on Chest
```

--------------------------------

### PuzzleScript Perpendicular Movement Simplification

Source: https://www.puzzlescript.net/Documentation/directions

Shows how to simplify two separate rules for vertical and horizontal player movement into a single rule using the 'Perpendicular' keyword.

```PuzzleScript
[ ^ Player | Crate ] -> [ ^ Player | ^ Crate ]
[ v Player | Crate ] -> [ v Player | v Crate ]
```

```PuzzleScript
[ Perpendicular Player | Crate ] -> [ Perpendicular Player | Perpendicular Crate ]
```

--------------------------------

### Sumo Wrestler Imitation Rule in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules101

Demonstrates how to define rules that span multiple rows or columns. This rule makes a Sumo sprite imitate the Player's movement, regardless of their relative positions.

```puzzlescript
Edit[ > Player ] [ Sumo ] -> [ > Player ] [ > Sumo ]
```

--------------------------------

### Implement Action Button Input in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/actionbutton

This snippet demonstrates how to define the action button's behavior in PuzzleScript. It shows how an action input on the player can trigger a change, such as interacting with a 'Sheep' object. The action is treated as a directional input that doesn't affect movement but can be detected.

```puzzlescript
Edit[ Action Player | Sheep ] -> [  Action  Player | > Sheep  ]
[ > Sheep |  Sheep ] -> [ blood | > Sheep ]
```

--------------------------------

### PuzzleScript Sound Event Declarations

Source: https://www.puzzlescript.net/Documentation/sounds

This section demonstrates how to associate in-game actions with specific sound effects using numeric identifiers. These identifiers are generated from sound buttons within the PuzzleScript editor.

```puzzlescript
Player Move Up 142315
Player Move Down 142313
Player Move Right 142311
Crate Move 412312
Player CantMove Up 41234
Crate CantMove 41234
Crate Create 41234123
CloseMessage 1241234
Sfx0 213424
Sfx3 213424
```

--------------------------------

### Define Simple Object with Name and Color (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/objects

Defines a basic in-game object using only its name and a color. This is the simplest way to declare an object in PuzzleScript.

```puzzlescript
Player
Blue
```

--------------------------------

### Initial Extended Rigid Body Concept

Source: https://www.puzzlescript.net/Documentation/rigidbodies

This snippet illustrates the basic concept of an extended rigid body, where a player can push a larger object. It highlights the initial visual representation and the underlying rule structure.

```puzzlescript
Edit[ > Player | BigBlock ] -> [ > Player | > BigBlock ] 
[ Moving BigBlock | BigBlock ] -> [ Moving BigBlock | Moving BigBlock ]
```

--------------------------------

### Define Object with Name, Color, and Sprite (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/objects

Defines an in-game object with a name, color, and a custom 5x5 pixel sprite. The sprite uses numbers to index colors and dots for transparency.

```puzzlescript
Player 
PINK YELLOW BLACK    
.222.
.000.
22122
.222.
.2.2.
```

--------------------------------

### Define Multiple Player Types for Input

Source: https://www.puzzlescript.net/Documentation/input

This snippet shows how to define multiple entity types that can receive player input. By using the 'or' operator in the legend, you can group different entities under a single player definition, ensuring they all respond to the same inputs.

```puzzlescript
Player = Player1 or Player2 or Player3
```

--------------------------------

### PuzzleScript: Complex Rigid Bodies with Loops

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Demonstrates a complex PuzzleScript scenario involving multiple rigid bodies ('RedCrate', 'GreenCrate', 'BlueCrate') and small blocks. It utilizes 'STARTLOOP' and 'ENDLOOP' to manage the rigid rules effectively, preventing unintended cancellations of game logic.

```puzzlescript
Editstartloop

[ > Player | Smallcrate ] -> [ > Player | > SmallCrate ]

[ > Player | RedCrate ] -> [ > Player | > RedCrate ] 
+ rigid [ moving RedCrate | RedCrate ] -> [ moving RedCrate | moving RedCrate ]
+ [ > Crate | RedCrate ] -> [ > Crate | > RedCrate ] 

[ > Player | GreenCrate ] -> [ > Player | > GreenCrate ] 
+ rigid [ moving GreenCrate | GreenCrate ] -> [ moving GreenCrate | moving GreenCrate ]
+ [ > Crate | GreenCrate ] -> [ > Crate | > GreenCrate ] 

[ > Player | BlueCrate ] -> [ > Player | > BlueCrate ] 
+ rigid [ moving BlueCrate | BlueCrate ] -> [ moving BlueCrate | moving BlueCrate ]
+ [ > Crate | BlueCrate ] -> [ > Crate | > BlueCrate ] 

```

--------------------------------

### One Player, One Extended Body Rule

Source: https://www.puzzlescript.net/Documentation/rigidbodies

Demonstrates the simplest case of extended rigid bodies: a single player pushing a single type of 'Crate'. If the crate cannot be pushed, the entire action is cancelled, ensuring a clean state.

```puzzlescript
Edit[ > Player | Crate ] -> [ > Player | > Crate ]
[ > Crate ] [ stationary Crate ] -> [ > Crate ] [ > Crate ]
[ > Crate | Wall ] -> cancel
```

--------------------------------

### Propagate Movements in Extended Bodies (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/rigidbodies

This snippet demonstrates how to propagate movements within and between extended bodies in PuzzleScript. It uses directional metadata (CRATE_U, CRATE_D, CRATE_L, CRATE_R) on a single CRATE object type to manage movement rules. It also shows how to move connections along with crates and cancel turns if a crate cannot move.

```puzzlescript
Edit(Propagate movements within and between extended bodies)
[ > Pusher | Pushable ] -> [ > Pusher | > Pushable ]
+ up [ moving Crate Crate_U | Crate ] -> [ moving Crate Crate_U | moving Crate ]
+ down [ moving Crate Crate_D | Crate ] -> [ moving Crate Crate_D | moving Crate ]
+ left [ moving Crate Crate_L | Crate ] -> [ moving Crate Crate_L | moving Crate ]
+ right [ moving Crate Crate_R | Crate ] -> [ moving Crate Crate_R | moving Crate ]

(Move connections along with the crates themselves)
[ moving Crate stationary Crate_connection ] -> [ moving Crate moving Crate_connection ]

(If any crate can't move, cancel the turn. This works because there's only one player.)
[ > Crate | wall ] -> cancel  
```

--------------------------------

### Trigger Sound Effects with 'sfx' in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

Commands 'sfx0' through 'sfx10' are used to trigger associated sound effects. These sounds are defined in the 'sounds' section and can be invoked within rules by mentioning their corresponding 'sfx' command.

```puzzlescript
sfx3
```

--------------------------------

### List of PuzzleScript Sound Events

Source: https://www.puzzlescript.net/Documentation/sounds

A comprehensive list of all possible sound events that can be triggered within a PuzzleScript game. Each event is associated with a numeric identifier and a description of when it is played.

```puzzlescript
Cancel 123413
Crate Action 123414
Crate Create 123414
EndGame 123413
EndLevel 123413
Player CantMove 4123412
Player CantMove Down Left 4123412
CloseMessage 123434
Crate Destroy 123414
Player Move 4123412
Player Move Down Left 4123412
Player Move Horizontal 4123412
Restart 123413
SFX0 123434
ShowMessage 123434
StartGame 123413
Startlevel 123413
TitleScreen 123414
Undo 123413
```

--------------------------------

### Basic Movement Rule in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules101

This rule defines the core mechanic for pushing a crate in Sokoban. It checks for a player attempting to move into a crate and replaces the player and crate with the player moving into the crate's position.

```puzzlescript
Edit[ > Player | Crate ] -> [ > Player | > Crate ]
```

--------------------------------

### PuzzleScript Relative Direction Compilation

Source: https://www.puzzlescript.net/Documentation/directions

Demonstrates how relative directions in PuzzleScript patterns are compiled into absolute directions for each rotation (UP, DOWN, LEFT, RIGHT). This is fundamental for understanding how movement is interpreted.

```PuzzleScript
[ > Player | Crate ] -> [ > Player | > Crate ]
```

```PuzzleScript
UP [ UP player | crate ] -> [ UP player | UP crate ] 
DOWN [ DOWN player | crate ] -> [ DOWN player | DOWN crate ] 
LEFT [ LEFT player | crate ] -> [ LEFT player | LEFT crate ] 
RIGHT [ RIGHT player | crate ] -> [ RIGHT player | RIGHT crate ]
```

--------------------------------

### Rule: Matching Any Player Movement

Source: https://www.puzzlescript.net/Documentation/rules

This rule uses the 'MOVING' keyword to match any movement of the player, regardless of direction. It also ensures the crate moves in the same direction.

```puzzlescript
[ MOVING Player | STATIONARY Crate ] -> [ MOVING Player | MOVING Crate ]
```

--------------------------------

### Trigger Repeated Turns with 'again' in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

Uses the 'again' command to trigger another turn after a small pause, without player input. This is useful for non-interactive animations. The 'again_interval' prelude switch controls the time between these automatic turns. It only triggers if changes occur.

```puzzlescript
Editrandom [ no Sheep ] -> [ Sheep ] again
```

--------------------------------

### Disabling Specific Game Keys

Source: https://www.puzzlescript.net/Documentation/prelude

Disables the action key (X), undo key (Z), or restart key (R). Use with caution as it can impact player experience.

```puzzlescript
noaction
noundo
norestart

```

--------------------------------

### Random Rule Application in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/randomness

Applies a rule from a group of rules at random. This is useful for introducing unpredictable events or behaviors in the game. The system considers all possible applications of rules within the group and selects one randomly.

```puzzlescript
random [ Wall ] -> [ ]
```

--------------------------------

### Define Object with Hex Color Codes (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/objects

Defines an in-game object using its name, hex color codes for its appearance, and a custom 5x5 sprite. This allows for precise color selection.

```puzzlescript
Player 
#FF5555 #FFFFFF #000000    
.222.
.000.
22122
.222.
.2.2.
```

--------------------------------

### One Player, Multiple Extended Bodies Rules

Source: https://www.puzzlescript.net/Documentation/rigidbodies

This shows how to handle multiple extended bodies ('Box' types) with a single player. It uses a loop to propagate movements and extend interactions between different box types, with a cancellation rule if any box cannot move.

```puzzlescript
Edit[ > Player | Box ] -> [ > Player | > Box ]

startloop

(Propagate movements through crates of different types.)
[ moving Box1 | Box1 ] -> [ moving Box1 | moving Box1 ]
[ moving Box2 | Box2 ] -> [ moving Box2 | moving Box2 ]
[ moving Box3 | Box3 ] -> [ moving Box3 | moving Box3 ]
[ moving Box4 | Box4 ] -> [ moving Box4 | moving Box4 ]

(Extend the movements between crates of different types.)
[ > Box | Box ] -> [ > Box | > Box ]

endloop

(Just cancel the whole turn if something can't move.)
[ > Box | Wall ] -> cancel
```

--------------------------------

### Random Robot Movement in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/randomness

Enables a robot to move in a random direction each turn. However, the documentation strongly advises caution, as unpredictable movement can often lead to unfun gameplay and make puzzles difficult to understand. Deterministic movement is generally recommended.

```puzzlescript
Edit[ Stationary Robot ] -> [ randomDir Robot ]
```

--------------------------------

### PuzzleScript Object Definition with 'and'

Source: https://www.puzzlescript.net/Documentation/levels

Specifies that multiple objects can occupy the same tile in PuzzleScript. This is achieved by using the 'and' keyword in the legend section when defining an object.

```puzzlescript
@ = Crate and Target
```

--------------------------------

### Display Message with 'Message' in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

The 'Message' command displays a text message to the player. It reads all text to its right, so it must be the rightmost argument in a rule.

```puzzlescript
Message Hello World
```

--------------------------------

### Rule: Disconnected Pattern Matching

Source: https://www.puzzlescript.net/Documentation/rules

This rule shows how to match multiple disconnected patterns within a single rule. It describes a scenario where a bird vanishes when a cat attempts to jump up.

```puzzlescript
[ UP Cat ]  [ Bird ] -> [ UP Cat ] [ ]
```

--------------------------------

### Set Real-time Interval in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/realtime

Configures the game to run in real-time by setting the interval between ticks. A value of 0.5 means the game engine will tick twice per second without player input. Player input is processed separately.

```puzzlescript
realtime_interval 0.5
```

--------------------------------

### CollisionLayers Definition in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/collisionlayers

Demonstrates how objects are assigned to different layers within a PuzzleScript file. Layers are crucial for resolving movement conflicts and determining drawing order. The 'Background' layer is mandatory and requires a background tile for every object.

```puzzlescript
Background
Target
Player, Wall, Crate
```

```puzzlescript
Background = Background1 or Background2
```

--------------------------------

### Player Movement Requirement

Source: https://www.puzzlescript.net/Documentation/prelude

Ensures that a move is canceled if the player does not move. This is a common requirement for many game mechanics.

```puzzlescript
require_player_movement

```

--------------------------------

### Define Object with Shorthand Character (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/objects

Defines an in-game object by specifying its name, a shorthand character for level editing, and its visual representation (color and sprite).

```puzzlescript
Player P
PINK WHITE BLACK    
.222.
.000.
22122
.222.
.2.2.
```

--------------------------------

### Teleport Sprite Rule and Fix in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules101

Illustrates a rule where a Sprite swaps places with the Player. The initial version causes an infinite loop, which is fixed by introducing a temporary 'Temp' tile to break the cycle.

```puzzlescript
late [ Sprite | ... | Player ] -> [ Player | ... | Sprite ]
Editlate [ Sprite | ... | Player ] -> [ Temp | ... | Sprite ]
late [ Temp ] -> [ Player ]
```

--------------------------------

### Two Player Movement Interaction (PuzzleScript)

Source: https://www.puzzlescript.net/Documentation/rigidbodies

This snippet illustrates a scenario with two players, a regular player and a shadow player moving in the opposite direction. It highlights the potential conflict when an extended body is pushed from two directions simultaneously.

```puzzlescript
Edit[ > player ] [ stationary shadow ] -> [ > player ] [ < shadow ]
```

--------------------------------

### PuzzleScript Horizontal Movement Rule

Source: https://www.puzzlescript.net/Documentation/directions

Demonstrates a PuzzleScript rule for objects that move horizontally in sync with player horizontal movement but ignore vertical player movement.

```PuzzleScript
[ Horizontal Player ] [ Crate ] -> [ Horizontal Player ] [ Horizontal Crate ]
```

--------------------------------

### Random Robot Spawnpoint in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/randomness

Defines a robot spawnpoint that can generate robots of different colors randomly. This is achieved by defining a 'Robot' type as a collection of possible robot types and then using this type in the spawn rule. Multiple random statements in the same cell are combined.

```puzzlescript
Robot = RedRobot or GreenRobot or BlueRobot

Edit[ RobotSpawn no robot ] -> [ RobotSpawn random Robot ]
```

```puzzlescript
Edit[ RobotSpawn no robot ] -> [ RobotSpawn random RedRobot random GreenRobot random BlueRobot ]
```

--------------------------------

### Cancel Player Movement in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

Simulates the 'require_player_movement' prelude setting. If the player cannot move, other game elements also stop their actions for the turn. This is achieved by using a player shadow that is cancelled if the player cannot move.

```puzzlescript
[ Player ] -> [ Player Shadow ]
late [ Player Shadow ] -> CANCEL
late [ Shadow ] -> [ ]
```

--------------------------------

### Multiple Players, Multiple Extended Bodies (Multi-Stage)

Source: https://www.puzzlescript.net/Documentation/rigidbodies

This complex rule set handles multiple players pushing multiple extended bodies simultaneously. It uses a four-stage process: propagating forward movements, propagating obstructions backward, flagging potential movers, and finally re-propagating movements only for flagged objects.

```puzzlescript
Edit( 1. Propagate movements forward )
[ > Mover | Movable ] -> [ > Mover | > Movable ]
+ [ > Box ] [ Box ] -> [ > Box ] [ > Box ]
+ [ > Crate ] [ Crate ] -> [ > Crate ] [ > Crate ]
+ [ > Chest ] [ Chest ] -> [ > Chest ] [ > Chest ]
+ [ moving Glue | Glue ] -> [ moving Glue | moving Glue ]

( 2. Propagate obstructions backwards )
[ > Mover | stationary Obstacle ] -> [ stationary Mover | Obstacle ]
+ [ > Crate ] [ stationary Crate ] -> [ stationary Crate ] [ Crate ]
+ [ > Box ] [ stationary Box ] -> [ stationary Box ] [ Box ]
+ [ > Chest ] [ stationary Chest ] -> [ stationary Chest ] [ Chest ]
+ [ moving Glue | stationary Glue ] -> [ stationary Glue | Glue ]

( 3. remove all movement, keep a flag )
[ > Movable ] -> [ Movable wanna_move ]

( 4. propagate movement only on wanna_move things )
( ie redo step 1 but with WANNA_MOVE added to the first line below )
[ > Mover | Movable WANNA_MOVE ] -> [ > Mover | > Movable ]
+ [ > Box ] [ Box ] -> [ > Box ] [ > Box ]
+ [ > Crate ] [ Crate ] -> [ > Crate ] [ > Crate ]
+ [ > Chest ] [ Chest ] -> [ > Chest ] [ > Chest ]
+ [ moving Glue | Glue ] -> [ moving Glue | moving Glue ]

( 5. cleanup, remove flag )
[ wanna_move ] -> [ ]
```

--------------------------------

### Define Object Properties in PuzzleScript Legend

Source: https://www.puzzlescript.net/Documentation/legend

This code snippet illustrates how to define custom properties for game objects in the 'Legend' section of a PuzzleScript file. These properties can then be referenced in other sections like 'Rules' for complex game logic.

```puzzlescript
Flying = Bat or Bird
Obstacle = Wall or Lava or Water
```

--------------------------------

### Rule: Ellipsis for Variable Length (Lava Gun)

Source: https://www.puzzlescript.net/Documentation/rules

This rule uses an ellipsis (...) to match a variable number of cells between two objects. It simulates a lava gun that turns any 'Mortal' in its line of sight into a 'Corpse'.

```puzzlescript
late [ LavaGun | ... | Mortal ] -> [ LavaGun | ... | Corpse ]
```

--------------------------------

### Rule: Removing Objects with NO Keyword

Source: https://www.puzzlescript.net/Documentation/rules

This rule shows how to specify the removal of an object type on the right-hand side without explicitly referencing it on the left. It adds a 'Wall' where there was previously an empty space.

```puzzlescript
[ > Player |  ] -> [ > Player | NO Wall ]
```

--------------------------------

### Cancel Turn with 'cancel' in PuzzleScript

Source: https://www.puzzlescript.net/Documentation/rules

The 'cancel' command reverts the game state to how it was at the beginning of the current turn, effectively undoing all changes made during that turn.

```puzzlescript
cancel
```

--------------------------------

### Define Single-Character Object Names in PuzzleScript Legend

Source: https://www.puzzlescript.net/Documentation/legend

This code snippet demonstrates how to assign single-character identifiers to game objects within the 'Legend' section of a PuzzleScript file. This allows for concise representation of objects in level designs.

```puzzlescript
P = Player
. = Background
# = Wall
* = Crate
O = Target
@ = Crate and Target
```