PuzzleScript

  1. Documentation
  2. Bird's-eye View
  3. CollisionLayers

Bird's-eye view of a PuzzleScript file

A puzzlescript file is divided into 8 sections:

CollisionLayers

Purpose and syntax

Objects can be placed on different layers: 

Background
Target
Player, Wall, Crate

The main purpose of layers is in resolving movements: two objects on the same layer cannot coexist in a single cell. The order of layers also determines in what order things are drawn: from the lowest layer (the first defined) to the highest (last defined) one.

The Background layer

The Background layer is a special layer. Every game must have one. Every tile must have a background tile. However, by defining 

Background = Background1 or Background2

in the legend, you can have several tile types on the background layer. Every tile must have a background tile. If you don't specify one explicitly for a tile, it is inferred based on what background tiles are on the level it's in.

Layer groups

As objects can overflow from the cells that contain them, it is often necessary to control the order in which objects are rendered to avoid one object to overdraw another object in a nearby cell. This is achieved by separating the collision layers into layer groups. (This feature only affects rendering, not collision detection.)

Objects in (the visible part of) the level are rendered in the order defined by these rules:

  1. All objects in the layers of a layer group are rendered before (and thus, under) the objects in the layers of higher groups.
  2. Inside a layer group, all the objects in a cell are rendered before the objects in the next cell. Cell order can be redefined (see below) but defaults to the writing direction used in English: rightward to the end of the line, then downward to the next line.
  3. Inside a cell and layer group, the objects are rendered layer by layer, from the lowest layer of the group to the highest one.

You use a -- line to separate layer groups. so, for instance, if you want to make a pseudo-3D effect with background tiles filling their cells, characters and walls that overflow their cells upward, and shadows under the characters and walls that overflow upward and leftward, you could have a collision layer definition like this: 

Background
Shadows
--
Character, Wall

That way, you make sure that a shadow will not overdraw a character or wall in the cell above or left of the thing that casts the shadow.

Rendering directions

The default cell ordering is not always what you want, so you can redefine it for each layer group. To do so, you add two characters after the separation line. These characters can be ^ (upward), v (downward), > (rightward), or < (leftward). The direction defined by the first character is used first, and when a (horizontal or vertical) line along that direction is filled, the direction defined by the second character is used for a new line, parallel to the former. Hence, the default group separator -- is actually equivalent to -->v.

Tip: if you want to make a group separator look nicer, you can add -- at the end, like that for instance: --^>--.

The characters | (default vertical direction) and - (default horizontal direction) can also be used. They are currently equivalent to v and > respectively, but future Pattern:Script versions might provide a preamble option to define the default directions. A typical use of these characters is to switch for a vertical-first rendering with a group separator like --|-.