Layers

A panel contains one or more layers. Each layer can represent either a static image, a set of images, an animated image table, or a string of text.

Having elements on separate layers allows Panels to simulate depth by scrolling layers at different speeds according to their parallax value. You can also set specific animations and effects for each layer in a panel.

Table of contents

Properties

image

default: nil

The path to an image to display for this layer.

Note: this path should be relative to your comic’s imageFolder setting.

Only specify one of the following per layer: image, images, imageTable, text.
You cannot combine them.

images

default: nil

A list of paths to images to display for this layer.

A layer with multiple images will switch between them as the panel scrolls across the screen. A layer with two images will switch at the halfway point, three images will switch at 1/3 and 2/3, and so on.

Note: these paths should be relative to your comic’s imageFolder setting.

Only specify one of the following per layer: image, images, imageTable, text.
You cannot combine them.

stencil

default: nil

An image to use as the stencil for this layer.

Animations and other layer effects apply to the image layer, but not the stencil. This allows you to have an image layer animate within a mask shape represented by the stencil.

{ image = "s01/shadow.png", stencil = "s01/shadowMask.png",
    animate = { y = -116, x = 100 }
},

In the example above, the ‘shadow’ image animates within the area masked by the ‘shadowMask’ image.

advanceControl

default: nil

FOR MULTI-IMAGE LAYERS ONLY

Specify a button to press to advance through a layer with multiple images. Setting this will override the default behavior of automatically swapping the images as the layer scrolls.

Options:

  • Panels.Input.UP
  • Panels.Input.RIGHT
  • Panels.Input.DOWN
  • Panels.Input.LEFT
  • Panels.Input.A
  • Panels.Input.B

imageTable

default: nil

A path to an animateable image table to display for this layer.

Note: this path should be relative to your comic’s imageFolder setting.

Only specify one of the following per layer: image, images, imageTable, text.
You cannot combine them.

scrollTrigger

default: 0

FOR IMAGETABLE LAYERS ONLY

The scroll point at which an imageTable layer should start to animate.

Scroll values go from 0 (just before the panel enters the screen) to 1 (just after the panel leaves the screen). A scroll trigger of 0.5 will trigger at the halfway point, which for a full-screen panel will be when the panel is fully centered on screen.

trigger

default: nil

FOR IMAGETABLE LAYERS ONLY

Set a button press as the trigger to start an imageTable animation.

If a trigger is set, the imageTable will hold on the first frame until the trigger button is pressed.

delay

default: 200

FOR IMAGETABLE LAYERS ONLY

The amount of time (in milliseconds) each frame of the imageTable is displayed.

reduceFlashingDelay

default: 200

FOR IMAGETABLE LAYERS ONLY

An alternate delay setting to be used when the user has Playdate’s “Reduce Flashing” accessibility setting enabled.

startDelay

default: 0

FOR IMAGETABLE LAYERS ONLY

The amount of time (in milliseconds) to wait before starting an imageTable animation (delay starts when the panel first appears on screen).

loop

default: false

FOR IMAGETABLE LAYERS ONLY

Whether or not to loop the animated imageTable.

text

default: nil

The string to display in a text layer.

Only specify one of the following per layer: image, images, imageTable, text.
You cannot combine them.

background

default: nil

FOR TEXT LAYERS ONLY

Set a solid background color for a text layer. Useful if the text will appear over top of an image or other layer.

Options:

  • Panels.Color.WHITE
  • Panels.Color.BLACK

font

default: playdate.getSystemFont()

FOR TEXT LAYERS ONLY

The path to a font to use for this text layer.

Note that you can also set a default font to use for all text layers in a panel or all panels in a sequence.

fontFamily

default: nil

FOR TEXT LAYERS ONLY

A table of font paths to use for this text layer. Font paths must be keyed to the constant for the appropriate style variant.

Setting a font family allows text layers to use bold and italic formatting with a custom font.

Font variants:

  • Panels.Font.NORMAL
  • Panels.Font.BOLD
  • Panels.Font.ITALIC

Example text layer with font family:

{ text = 'Normal *Bold*, _Italic_', x = 16, y = 180,
    fontFamily = {
        [Panels.Font.NORMAL] = 'fonts/SasserSlab/Sasser-Slab',
        [Panels.Font.BOLD] = 'fonts/SasserSlab/Sasser-Slab-Bold',
        [Panels.Font.ITALIC] = 'fonts/SasserSlab/Sasser-Slab-Italic'
    },
},

Note that you can also set a default font family to use for all text layers in a panel or all panels in a sequence.

color

default: Panels.Color.BLACK

FOR TEXT LAYERS ONLY

Set the color of the text.
Note that text will automatically be drawn in white if the layer has a black background.

Options:

  • Panels.Color.WHITE
  • Panels.Color.BLACK

invertTextColor

default: false

FOR TEXT LAYERS ONLY

Set this to true to draw the text using inverted colors.

Setting the color of a text layer to white will draw the text characters completely in white (kDrawModeFillWhite). For fonts that contain both black and white pixels, you’d most likely rather invert the colors instead of drawing everything in white (kDrawModeInverted).

When this setting is enabled, black pixels in the font will be drawn as white and white pixels will be drawn as black.

rect

default: nil

FOR TEXT LAYERS ONLY

A table to specify the width and height of the rectangle in which to draw multiline text. Text will be positioned using the layer’s normal x and y properties.

lineHeightAdjustment

default: 0

FOR TEXT LAYERS ONLY

Adjust the spacing between lines of text.

alignment

default: playdate.getSystemFont()

FOR TEXT LAYERS ONLY

Set the alignment for multiline text layers.

Options:

  • Panels.TextAlignment.LEFT
  • Panels.TextAlignment.CENTER
  • Panels.TextAlignment.RIGHT

parallax

default: 0

The amount of parallax movement to apply to this layer (between 0 and 1). A layer with a higher value will move more in relation to the frame border. In general, layers closer to the viewer should have a lower parallax value than layers in the distance.

x

default: 0

The horizontal position of the layer (relative to the top left corner of the panel).

You can avoid setting explicit x and y values for each layer in your comic by cutting images with built-in transparency so they are always positioned at (0,0).

y

default: 0

The vertical position of the layer (relative to the top left corner of the panel).

You can avoid setting explicit x and y values for each layer in your comic by cutting images with built-in transparency so they are always positioned at (0,0).

opacity

default: 1

The opacity of the layer.

You can use this to set an initial value to animate from. If your layer will remain at a constant opacity value, then you should consider baking the transparency into the image.

animate

default: nil

A table describing how to animate the layer. Animate layer position or opacity over a set amount of time or based on panel scroll position.

See Layer Animations for more information.

effect

default: nil

A table describing the layer effect. Choose from blink, shake, or text type-on effects.

See Layer Effects for more information.

transitionOffset

default: 0

A layer that lists multiple images will transition between those images as the panel scrolls. This means a layer with two images will swap them when the panel scroll reaches 0.5 (50%).

Setting transitionOffset adjusts the points at which image transitions are triggered. Setting this to -0.1 would cause the above example to swap images at scroll point 0.4 instead of 0.5.

pixelLock

default: 1

Certain dither patterns will appear to flicker as they scroll on the Playdate screen. You can often reduce this flickering effect by scrolling the pattern two pixels at a time.

Setting pixelLock = 2 on a layer with dithering will force it to only render on every other pixel. (A setting of 3 will render the layer on every third pixel and so on.) This may cause some jumpiness in the layer movement, but will significantly reduce flickering.