# Sprites: pictures you can move

[Programming guides](README.md)

A **sprite** is a named picture in your scene, such as your game's hero. Pliro **retains** it: it remembers that named picture so you can show it in a different position without creating another sprite each time.

A **transform** changes how a picture is placed: moving, rotating, or flipping it. **Mirroring** left to right swaps its sides, like a reflection. The **clipping rectangle** is the area allowed to show the picture; parts outside it are hidden. **Stacking order** works like sheets of paper placed on top of each other: later sheets can cover earlier ones. The detailed rules below describe how Pliro handles these changes.

| English call | Canonical ID | Returns |
|---|---|---|
| `showSprite(name, asset, x, y, width, height)` | `sprites.show` | `None` |
| `showSprite(name, asset, x, y, width, height, rotation)` | `sprites.show` | `None` |
| `showSprite(name, asset, x, y, width, height, rotation, flipHorizontal)` | `sprites.show` | `None` |
| `showSprite(name, asset, x, y, width, height, rotation, flipHorizontal, flipVertical)` | `sprites.show` | `None` |
| `hideSprite(name)` | `sprites.hide` | `None` |

`name` and `asset` are non-empty `Text`. Coordinates are finite numbers, and
width and height must be positive. `(x, y)` is the sprite's top-left position.
`rotation` is a finite Number of clockwise degrees around the rectangle's
center, defaulting to 0. `flipHorizontal` and `flipVertical` are Booleans,
defaulting to `false`, applied in local sprite coordinates before rotation.
The requested rectangle remains the layout and clipping rectangle. Optional
values reset to their defaults each time they are omitted. For example:

```text
showSprite("hero", "assets/hero.png", 100, 220, 48, 64, 15, true, false)
```

This turns the sprite 15 degrees clockwise and mirrors it horizontally.
See the [sprite specification](../../../docs/spec/sprites.md).

Showing a new name creates a retained sprite. Showing the same name again
updates its image and rectangle without changing its stacking position. Hiding
removes it. Showing a hidden name again creates it above sprites that remained
visible. Image fitting currently depends on the host: native hosts stretch the
image to the requested width and height, while the [IDE](../concepts/ide.md) preview preserves its
aspect ratio. For portable results, request a rectangle with the same aspect
ratio as the source image.

See [Section 14](../../../pliro-syntax.en.md#14-graphics-media-sprites-and-animation) for scene and
animation behavior.

## Related entries

[Syntax and values](../syntax/README.md) · [Built-ins](../builtins/README.md) · [Programming guides](README.md)