Repository navigation
Background
The Playfield tab (called Background in earlier versions) holds background graphics — playfields your game displays with the "Playfield set to" block.
Click the + button in the bottom-right corner to add a new background graphic. A new project starts with one background: a border of lit pixels along all four edges, across every row.
- See the Graphic Editor Toolbar page for a description of graphic editing tool functionality.
XY toggle (Shift+') — shows/hides X,Y coordinate labels on the grid overlay. Only available while the pixel grid itself is on.
- Quick color palette — only shown when per-row playfield colors are enabled (see below); pick a color here to paint with it directly in a background's row-color strip. The palette is saved with the project and comes back when you open it (a new project starts with an empty one).
- Background name — shown in the "Background" dropdown wherever you select it in your blocks.
- ID (the badge in the card's top-left) — a permanent number, separate from the name or list position.
- The pixel grid itself — 32 pixels wide, and as many rows tall as the playfield's current resolution: 12 rows by default (11 are visible at once; the 12th is the hidden row that scrolls into view with the playfield scroll blocks), or the Options tab's Superchip RAM "pfres" setting if that's enabled. Backgrounds saved with 11 rows get the extra blank row when opened here.
- pfres (DPC+ kernel only, in the same row as the background name) — how many rows this background has on screen, 1 to 192. Left empty it uses the project's pfres from the Options tab. Every background can have a different row count: the playfield scroll, box, collision and sprite blocks all follow the background currently showing, and the card's aspect ratio follows its row count.
Click the chevron in the top-left corner to collapse a background card. Drag the strip at the top of a card to reorder backgrounds in the list. After a reorder the backgrounds are renumbered 1, 2, 3... by their new position, and everything that referred to one by its ID is updated to the new ID: Playfield select blocks, the Playfield value block, a plain number plugged straight into Playfield set to, and Data table cells set to the Background format. A background number held in a variable or worked out by a calculation can't be followed, so check blocks that use one.
Copy this background's image / Paste copied image onto this background — copies (or pastes) the pixel data and, if per-row colors are on, the row colors too.
Copy this background's row colors only / Paste copied row colors only — (only shown with per-row playfield colors enabled) copies just the color strip, leaving the pixel image alone.
Delete this background (or select it and press Delete) — asks for confirmation, then removes it. Only shown when there's more than one background in the project.
The Play button on a background card (left of the delete button) previews just that background in the emulator, without building or changing your ROM. The background's name is shown on the first line of the Text Minikernel.
If the Options tab's "per-row playfield colors" (pfcolors) setting is enabled, each background gets its color strip alongside the pixel grid, one color per row. Use the quick color palette above the list to pick a color, then click a row's swatch to apply it, or click-and-drag across rows to paint several at once. The Eraser tool sets a row's color back to white. Turning this option off doesn't delete any colors already picked, they're kept in case pfcolors is turned back on later. Clear resets both the pixels and the row colors back to their defaults.
A background that no block ever switches to is left out of the ROM, so unused ones cost nothing. The first background always stays, because the game starts on it. Every background stays when one is picked from a variable or another calculated value, since any of them could be chosen. A Playfield block inside a disabled event or block doesn't count as a use.
On the Actions tab, the Background category has blocks for:
- Playfield / Playfield set to [name] — read or select which background is currently shown, picked from a dropdown of names.
- Playfield set [Background/Playfield] color to [color] / Get [Background/Playfield] color — set or read the background or playfield color directly.
- Fade [Background/Playfield] color to [color] over [n] frames — starts fading that color toward the given target, same hue, brightness automatically climbing or dropping from wherever it currently is. Only needs to be triggered once - the fade keeps running by itself every frame afterward, even from inside an "if" block that only briefly becomes true, until it reaches the target and stops.
- Fade playfield rows from [color] up/down to playfield colors over [n] frames — starts every playfield row at the brightness of the chosen color (pick it with the color picker block) and fades each one up or down to its row color from the editor, in four steps over roughly this many frames. Needs per-row playfield colors turned on (Options tab). Only needs to be triggered once; switching backgrounds cancels it.
- When [Background/Playfield] color has finished fading — runs the connected blocks once, the moment a matching fade reaches its target color.
- Is [Background/Playfield] color fade active? — true from the moment a matching fade triggers until it reaches its target, false otherwise.
- Playfield get pixel at X [x] and Y [y] — reads a single playfield pixel (usable in an "if" statement).
- Playfield area from X [x1] Y [y1] to X [x2] Y [y2] is clear — true when every playfield pixel in the rectangle between the two corners is off, for example to see whether all the bricks in a block have been cleared. X is the column (0-31) and Y the row, the same numbers as Playfield get pixel. The corners can be given in either order, and any part of the rectangle outside the playfield is ignored. It reads the pixels one by one (and stops at the first lit one), so a big area takes a while: use it now and then, such as when a brick is cleared, not on every frame. It uses one variable and can't be used inside a custom function.
- Playfield [Set/Clear/Flip] pixel at X [x] and Y [y] — changes a single playfield pixel.
- Playfield [Set/Clear/Flip] [Horizontally/Vertically] [n] pixels at X [x] and Y [y] — draws a horizontal or vertical line of pixels.
- Playfield [Set/Clear/Flip] line from X [x1] Y [y1] to X [x2] Y [y2] — draws a straight line of any angle between two playfield points, unlike the Horizontally/Vertically line block above, which only draws straight up/down or left/right.
- Convert playfield [X/Y] [n] to [single-wide sprite/double/quad-wide sprite] / Convert [single-wide sprite/double/quad-wide sprite] [X/Y] [n] to playfield — converts between a playfield pixel column (0-31) or row and the matching Player/Missile/Ball X or Y coordinate, and back.
- Find playfield pixel [sprite] collided with, moving in direction [n] / Playfield collision column / Playfield collision row — finds the exact playfield pixel a Player, Missile or Ball just collided with, so you can read or change it (for example clear it to break a wall). See the Actions page for how the direction value works.
- Playfield clear all pixels — turns off every playfield pixel at once.
- Playfield rainbow colors, offset [n] / Stop playfield rainbow colors — gives every playfield row a different, shimmering color (read from raw ROM bytes), and puts the rows back to the row colors of the loaded background. Needs Playfield row colors turned on in Options. See the Actions page for the details.
- Playfield height (rows) — reads the playfield's current vertical resolution (11 by default, or the Superchip pfres setting).
-
Playfield scroll [direction] with two checkboxes, stop at top/bottom edge and scroll playfield colors — scrolls the whole playfield left, right, up, down, or up/down by 2 pixels at once. Down moves the background down and Up moves it up, whatever the background's height.
- Scroll playfield colors (off by default, needs per-row playfield colors turned on in the Options tab) moves each row's color along with its pixels for the up/down directions. Without it the colors stay where they are on the screen and the pixels slide past them. Tick it on every scroll block of the project that should move the colors. It works with Superchip RAM on or off, in bankswitched ROMs, and for backgrounds of any height. It uses two variables, plus 256 bytes of ROM in the kernel's bank for every 16 rows of a background (at least one page per background), and the Fade playfield rows block doesn't combine with it.
- A background can be taller than the screen (use the toolbar's Set height, up to 64 rows). Scrolling up/down then moves through its full height, loading each new row in as it appears. With Stop at edge checked it stops cleanly on the first/last row (Down stops at the top, Up at the bottom); without it, it wraps around so the first row follows the last.
- A project only pays for position tracking when it needs it (a Stop-at-edge scroll block, the scroll position getter, or a sprite following the scroll); a project with a tall background always does.
- Playfield scroll colors [direction] with stop at top/bottom edge — scrolls only the row colors and leaves the playfield pixels alone, so it works without scrolling the playfield. Needs per-row playfield colors turned on in the Options tab. The standard kernel moves the colors a whole playfield row per block; DPC+ moves them by scanline.
- Playfield offset [alternate rows left and right / all left / all right / all up / all down] [whole playfield] — moves the pixels of the playfield by one pixel in the chosen direction each time it runs, wrapping round, so the holes in a wall drift along (the shield in Yars' Revenge). A pixel that leaves the end of a row carries on at the start of the next row, and one that leaves the last row comes back on the first; all up and all down wrap the top and the bottom. Alternate rows left and right moves one row left, the next right and so on, so the pixels run along the rows like a belt. Untick whole playfield to move just an area: from X [0/8/16/24] Y [row] to X [7/15/23/31] Y [row] (the edges are whole bytes of the playfield, so the width is a multiple of eight pixels, and the rows are counted from 0 like Playfield get pixel). Run it every few frames for a slower drift. Only pixels move; per-row colors stay where they are. It needs no variables and works with the standard kernel (with or without Superchip RAM) and DPC+.
- Set playfield scroll to row [n] — starts (or jumps) the scroll at row n of a background taller than the screen: 0 is the top (the default), so with a 64-row background and an 11-row screen, 32 shows rows 32 to 42. A row past the last scrollable one is clamped to it. It works whether it comes before or after a "Set background" block in the same event, and it does nothing for a background that isn't taller than the screen. Sprites that follow the scroll aren't moved.
- When playfield scroll reaches the [Top/Bottom] — runs the blocks inside once each time Up/Down scrolling moves the view onto the top or bottom row. Jumping there with "Set background scroll to row", or switching backgrounds, doesn't count.
- Draw screen — batari Basic's "drawscreen" - renders the current frame. Every project needs one of these in its main loop.
See the Actions tab's Playfield category for every Playfield block: selecting/setting the current background, reading/setting/fading the background or playfield color, reading/changing individual pixels or drawing lines, converting between playfield and sprite coordinates, clearing the playfield, scrolling, reading the playfield's row count, and Draw screen.