Author the stage a turn-based pet battle is drawn on — background, platforms, tint, music and pet placement — and where it is picked automatically.

Battle Scenes

A battle scene is the stage a turn-based pet battle is drawn on: the background art, an optional midground layer, the platforms each side's pets stand on, a colour tint, the battle music, and where the pets stand. A trainer's battle team can pin one scene, or leave it on Auto and let the game pick the best scene for the map or biome the battle starts on. Pet duels between two players use the same automatic pick.

Where to author it

What	Where
The scene — art, tint, music, placement, auto-pick rules	Database → Pets & Mounts → Pets → Battle Scenes
Pinning a scene on a trainer	Database → Pets & Mounts → Pets → Battle Teams → a team → Team → Battle scene
The art and music themselves	The Media Library (upload images and audio there first)

Set up a scene#

Upload the art to the Media Library: a background (a wide image — it is stretched
to fill the battle screen), and optionally a midground layer and two platform images. Upload the battle music as an audio file.
Open Database → Pets & Mounts → Pets → Battle Scenes and press + New Battle Scene.
On Scene, give it an ID (e.g. forest_clearing) and a Name.
On Art & Music, press Pick… next to Background and choose your image. Add
the midground, platforms and Battle music the same way. The preview on the Scene and Pet Placement tabs updates as you go.
Optional: set a Tint colour and Tint strength — a dark blue at 30–40% makes a
night version of a day scene without new art.
Optional: on Pet Placement, tick Custom pet placement and move the pets to sit
on your platforms. Watch the preview.
Decide how the scene is used:
- Pinned — open a battle team and choose this scene under Battle scene; or
- Auto-pick — on the Auto-pick tab, add the Maps and/or Biomes it
  belongs to and give it a Priority.
Press Create Scene. Start a battle on one of those maps (or against the trainer
that pins it) to see it.

Scene fields#

Field	What it does
ID	Permanent identifier (lower-case letters, numbers, - and _). Fixed once created.
Name	What you call the scene in the editor and in the team's Battle scene dropdown.
Description	An editor-only note.

Art & music fields#

Field	What it does
Background	Full-screen art drawn behind everything, stretched to the battle screen. Empty = the built-in stage.
Midground	An optional second layer drawn over the background (trees, fog, a crowd). Use a transparent PNG.
Player platform	The disc or ground patch the player's pets stand on (the near side).
Opponent platform	The disc the opponent's pets stand on (the far side).
Battle music	Loops for the whole battle. Must be an audio asset. Empty = the default battle music.
Tint colour	A colour washed over the stage. Clear removes it.
Tint strength (%)	0 = no tint, 100 = solid colour. The tint needs both a colour and a strength above 0.

Pet placement fields#

Positions are fractions of the battle screen, so a scene looks the same at every window size. With Custom pet placement off, the scene uses the built-in placement, which is tuned to sit between the battle HUD panels.

Field	What it does
Player X / Y	Where the player's lead pet stands. X: 0 = left edge, 1 = right edge. Y: 0 = top, 1 = bottom. Default 0.26 / 0.63.
Player size	Size multiplier for the player's pets (0.25–4). Near pets read larger — default 1.35.
Opponent X / Y	Where the opponent's lead pet stands. Default 0.74 / 0.34.
Opponent size	Size multiplier for the opponent's pets (0.25–4). Default 1.

In 2v2 and 3v3 fights the other field pets line up beside the lead on the same side.

Auto-pick fields#

Field	What it does
Maps	The scene is used for battles that start on any of these maps.
Biomes	The scene is used for battles on a map whose main (default) biome is one of these.
Priority	When several scenes match, the highest priority wins (−1000 to 1000).

A battle team with a pinned scene always uses it. A team on Auto, and every player-vs-player pet duel, uses the highest-priority scene whose maps or biomes match — and the built-in stage when none match.

Gotchas#

A scene with no maps or biomes is only used when a team pins it. The editor warns
you on the sidebar.
Stage art must be images and the music must be audio. Picking the wrong kind is
refused with the field highlighted. Only Media Library assets work — pasted URLs are refused.
A tint needs both parts. A colour at 0% strength, or a strength with no colour,
draws nothing (the sidebar warns you).
Biomes match the map's main biome only — painted biome patches inside a map do not
change which scene is picked.
Deleting a scene never breaks a battle: teams that pinned it go back to Auto. The
delete prompt lists them.
History: open a scene and use the History tab to see every earlier version and
restore one. A deleted scene can be brought back from Recently deleted for 30 days.
Hosted games: saves reach a running server within a few seconds; a managed server
with its own database gets scenes on your next Publish.
Needs the Pet Battles feature flag (and Pets) switched on in **World Config →
Features**.
AI / automation: the Copilot can create and edit scenes with the
pet-battle-scene-create / pet-battle-scene-update tools, and scripts can use /api/ai/pet-battle-scenes (list / create) and /api/ai/pet-battle-scenes/<id> (read / update / delete). Every write accepts dryRun: true, runs the same checks, and is recorded in the audit log.