Skip to main content

Stencils

Stencils let you limit where graphics are drawn on the screen to specific shapes or areas. This can be used to create all kinds of effects:

  • Stylized borders: give the minimap a fancy shape by giving its camera a stencil.
  • Fog of war: In a real-time strategy game, limit a player's vision to what they can see by using stencils around their units.
  • Scene transitions: Animate a spinning and zooming star-shaped stencil to create a scene transition.
  • Search and reveal: Create a spotlight effect by using a circular stencil that follows the mouse pointer.

Defining stencils​

When a camera is rendered, only the pixels that fall within the stencilled areas are drawn. You can define a stencil using one of the following functions:

Multiple stencils​

All stencils for a camera are combined to form a single stencil mask. This allows you to do things like implement fog-of-war in a real-time strategy game. Each unit emits the stencil shape around itself, and the combined stencil mask shows the areas visible to at least one unit.

Cameras and stencils​

Each camera has its own set of stencils. This is useful because your minimap camera might have a circular stencil to give it a shape, while your main game camera might have no stencil at all. Or as you transition from one scene to another, the old scene's stencil may be shrinking while the new scene's stencil is growing.

Enabling/disabling per-camera​

By default, a camera will render all pixels, but as soon as a stencil is defined, rendering will be limited to the stencilled areas for that camera. As most games do not use stencils, this default behavior makes it easy to get started without any stencils, and then for stencils to automatically take effect as soon as you add them.

This can cause surprising behavior in certain situations when you frequently transition between having stencils and not having stencils. For example, if you are implementing fog of war in a real-time strategy game, and suddenly as soon as there are no units (and therefore no stencils), the entire map becomes visible again. To solve this, you can force-enable stencils all the time by passing stencil=true to your Camera function.

You can also disable stencils for a particular camera by passing stencil=false to the Camera function. This will force the camera to always render all pixels and ignore any stencils defined for that camera. This could be used to temporarily disable fog of war when the player gains a satellite view power-up, for example.

Images and stencils​

When using an image as a stencil, only the transparency/opacity of the image matters:

  • Opaque or semi-transparent pixels mark where to draw.
  • Transparent pixels mark where not to draw.

Stencil positions​

Like other sprites, stencils can use special position values such as Position:AtPointer. This can be used to create effects such as a circular spotlight that follows the mouse pointer:

PolygonStencil(body=Position:AtPointer, shape=Circle(radius=20))

See Position for a complete list of special position symbols.