Repository navigation
Actions
The Actions tab is where you build your game's logic with Blockly blocks, organized into categories down the left side (the "toolbox").
- Search (the first category in the toolbox) — a search field for the block library. Type part of a block's name and the matching blocks appear in the flyout, ready to drag onto the workspace. Ctrl+B jumps straight to it.
- Search the workspace — Ctrl+F (Cmd+F on Mac) opens a search box that finds and highlights blocks already placed on your workspace. Escape or the close button closes it.
if / if-else — standard conditional branching.
[compare] — compares two numbers (=, ≠, <, ≤, >, ≥).
and / or — combines two true/false values.
not — inverts a true/false value.
true / false — literal boolean values.
repeat [n] times — runs the connected blocks a fixed number of times.
repeat while / repeat until — runs the connected blocks while (or until) a condition holds.
wait [n] frames — pauses for the given number of video frames (about 60 per second) before continuing.
[number] — a literal number. Accepts decimal, hex ($1F or 0x1F), or binary (%1010 or 0b1010).
[a] [+ − × ÷ ^ & | ⊕ %] [b] — arithmetic and bitwise operators: add, subtract, multiply, divide, power, AND, OR, XOR, modulo. Both slots start as number fields set to 0.
Set [variable] to Absolute value of [n] — sets a variable to the always-positive value of a number.
Standard Blockly variable blocks (get/set/change) for your named variables, created via the "Create variable" button in this category. Variable count is limited by available RAM - see the Options tab.
With the DPC+ kernel, the Math category also has Push [variable], Pull [variable] and Stack position [n] blocks for its 256-byte variable stack.
Player 0/1, Missile 0/1, and the Ball each get a getter, setter, and "change by" block for their properties. Player 0/1 and Missile 0/1 are single combined block types with a dropdown to pick which one, recoloring to match (red for 0, blue for 1). The Ball keeps its own block type.
Player 0/1 [X / Y / Color / Animation / Horizontal flip] / ...set to [n] / ...change by [n] — reads, sets, or changes that property. The getter block also reads Visibility (true while the player is shown), which you can compare with false in a logic block.
Player 0/1 Height — current frame's pixel height. Read-only.
Player 0/1 set Visibility to [n] — shows or hides the player. Write-only.
Player 0/1 Frame — current animation frame. Read-only.
Player 0/1 Width/quantity — the width/quantity code the Player set width/quantity block last set, as a number from 0 to 7: 0 one copy, 1 two close copies, 2 two medium copies, 3 three close copies, 4 two wide copies, 5 double-size, 6 three medium copies, 7 quad-size. Read-only (a choice of the Player getter block, along with X, Y, Height, Color, Animation, Horizontal flip and Frame).
Players 2 to 9 (DPC+ only) — with the DPC+ kernel the Player dropdown also lists Players 2 to 9, which have X, Y, Height, Width/quantity, Horizontal flip, Frame, Animation, Visibility and Color, play animations, and can be used in Fire, Seek, Inertia, Bounce, Collided and Undo last move. A Player 2 to 9 starts on screen at a spot spread across the screen and has a fixed starting color; its color can only be set to a fixed color. Collision with Players 2 to 9 compares bounding boxes after the hardware says a virtual sprite was touched, so it is approximate; against the playfield it reports whether any of the virtual sprites touched it.
Missile 0/1 / Ball [X / Y / Height] / ...set to [n] / ...change by [n] — reads, sets, or changes that property. With the DPC+ kernel the Missile 0/1 blocks also have a Color option (read and set), because each missile has a separate color register there; on the standard kernel a missile is always drawn in its player's color. A Height of 0 hides a DPC+ missile, and a Height of 1 draws it on every other line.
Missile 0/1 set Width to [n] — sets width (1/2/4/8 px) from a plugged-in value.
Ball set Width to [n] — sets the ball's width.
Player 0/1-only blocks:
Animation [name] — looks up an animation by name for "...Animation set to." It takes the color of the player block it is plugged into.
Player 0/1 animation [Play/Pause] — pauses or resumes animation playback.
Player 0/1 set width/quantity to [option] — sets NUSIZ: 1/2/3 copies, double, or quad size.
Player 0/1 display ROM noise, offset [n] height [n] rows — shows raw ROM bytes as the graphic (Yars' Revenge "neutral zone" effect).
Player 0/1 stop ROM noise — undoes ROM noise.
Player 0/1 rainbow colors, offset [n] — gives the player a different color per row.
Player 0/1 stop rainbow colors — stops rainbow colors.
Fade Player 0/1 color to [color] over [n] frames — fades the player's live color to a target. With the DPC+ kernel the player's missile fades along with it.
When Player 0/1 color has finished fading — runs once when a fade completes.
Is Player 0/1 color fade active? — true while a fade is in progress.
Missile-only:
Missile 0/1 set width to [1/2/4/8] pixels — sets width from a fixed dropdown.
Missile 0/1 and Ball:
Fire [Missile 0 / Missile 1 / Ball] from X [x] Y [y] at angle [angle] default [dir] speed [n] — launches the object and moves it automatically until off-screen. One block covers all three objects through its dropdown (the block turns orange for the Ball).
Speed is a number input, in pixels per frame from 0 to 7: plug in a number block, a variable or any expression. 0 stands still, and anything above 7 is held at 7. A new block comes with a 1 already plugged in. Throttle movement (with "every X frames") paces the movement to that rate.
The angle runs clockwise from Up. Plug in a number, a variable, or a "Joystick direction" block; a value outside the valid range (such as 255 from a centered joystick) uses the default direction instead. Ticking 16 directions doubles the angle resolution (it also affects Accelerate's direction in the same way). Angles you already picked are converted when you tick or untick it.
8 directions (the default):
| Angle | Direction |
|---|---|
| 0 | Up |
| 1 | Up-Right |
| 2 | Right |
| 3 | Down-Right |
| 4 | Down |
| 5 | Down-Left |
| 6 | Left |
| 7 | Up-Left |
16 directions: the even angles are the eight directions above (doubled), and each odd angle sits halfway between its neighbors, moving at the block's speed along its main direction and at half that speed along the other (at speed 1 that is one pixel every other frame):
| Angle | Direction |
|---|---|
| 0 | Up |
| 1 | Up (leaning right) |
| 2 | Up-Right |
| 3 | Right (leaning up) |
| 4 | Right |
| 5 | Right (leaning down) |
| 6 | Down-Right |
| 7 | Down (leaning right) |
| 8 | Down |
| 9 | Down (leaning left) |
| 10 | Down-Left |
| 11 | Left (leaning down) |
| 12 | Left |
| 13 | Left (leaning up) |
| 14 | Up-Left |
| 15 | Up (leaning left) |
Check playfield while moving (checkbox on the Fire block): a fast missile can jump over a thin playfield pixel between one frame and the next and never touch it, so no collision is detected. With the box ticked the object moves one pixel at a time, checks the playfield after each pixel, and stops on the first lit pixel it reaches. It then overlaps that pixel, so your usual Collided [object] and Playfield check fires as normal. It costs a little extra time every frame while the object is moving, so leave it off for slow shots.
Fire angle of [Missile 0 / Missile 1 / Ball] — the direction an object that a Fire block launched is traveling in (the same numbers as the Fire block's angle). It changes when Bounce turns the object around.
Stop fired [object] — stops a missile or ball that a Fire block launched, leaving it exactly where it is. Its height and visibility aren't touched (use Missile set Height to hide it), and a later Fire block launches it again. Does nothing to a player, or to an object no Fire block ever launched.
Fired [object] has gone off screen — true once an object a Fire block launched has left the screen and stopped there (it is then hidden in the top left corner, so it never shows up on the other side), and it stays true until a Fire block launches it again. It is not true when Stop fired or a collision stopped the object. Use it as the condition of an If block. With DPC+ the bottom edge is line 212.
Set fired [Missile 0 / Missile 1 / Ball] speed to [n] — changes the speed, in pixels per frame, of an object a Fire block launched, while it is moving. The Fire block sets the speed it starts at; this changes it afterward, from the next frame, and the direction stays the same. The speed is held to 0-7. 0 holds the object still without cancelling the Fire, so setting the speed back above 0 moves it again (use Stop fired to cancel it). Does nothing to an object no Fire block launched. An object whose Fire blocks all use the same plain number for the speed normally doesn't keep a speed variable; using this block gives it one.
Inertia (Player 0/1, Missile 0/1, Ball):
Velocity-based movement, independent of Fire - an object can use either or both (Bounce reflects whichever is active).
Accelerate [object] toward direction [dir] by [rate], max speed [n] — accelerates the object toward a direction each frame, up to max speed, until "Stop accelerating" runs. Re-running updates in place without resetting velocity.
Stop accelerating [object] — stops accelerating; existing velocity keeps moving the object unless Decelerate is also on.
Decelerate [object] by [rate]: [Start/Stop] — Start applies friction toward 0 each frame (clamped, never overshoots) until Stop. Works alongside Accelerate.
Shared across all five:
Bounce [object] [ ] off screen edges [ ] set angle manually [n] — reflects the object off whatever it just collided with. Call it every frame the collision persists, not just once.
Straight up, down, left or right movement flips just that direction. At an angle, the block looks at the playfield pixels beside and above or below the object to tell a vertical wall, a horizontal wall and a corner apart. It works for all 8 and 16 directions. If the object is still stuck a few frames later it turns back around instead. All of this needs one variable per object.
Off screen edges: no collision is needed. Put the block where it runs every frame (for example a Gameplay update event) and the object bounces the moment it goes past the left, right, top or bottom edge of the screen, and a fired missile or ball keeps moving instead of stopping off-screen. The bottom edge follows the playfield height.
Set angle manually: tick it to show a number input (0-7, or 0-15 when the Fire block uses 16 directions, clockwise from Up). A fired missile or ball then leaves the surface at that angle instead of the automatic reflection. It applies to collision bounces only, not to "off screen edges". Untick it and the reflection is automatic again.
Move [Player 0/1 / Missile 0/1 / Ball] to X [x] Y [y] at speed [n] (called Seek in older versions) — moves the object toward a target at up to "speed" px/frame per axis, stopping on arrival. "Throttle movement" (with "every X frames") paces the movement to that rate. One axis at a time makes it move along X until it is in the target column, then along Y, never both in the same frame (unticked, it moves both together and arrives diagonally).
[object] arrived at its seek target — true from arrival until a new Seek target is given.
Player 0/1 set animation to [name] — Sets the chosen player's active animation by name, in one step. "restart" on (the default) plays the new animation from its first frame, or from the frame you pick in at frame [n] next to it (1, the default, is the first frame; the animation then plays on from that frame); off carries on from the current position in the animation that was playing. "loop" on (the default) replays it from the start every time it ends; off plays it once and leaves it on its last frame (see "Player animation has finished" to react to that moment).
Player 0/1 set animation to ID [n] — Sets the chosen player's active animation directly by its numeric list position (0-based, top to bottom) - for a fixed animation picked by name instead, see "set animation to" above. "restart" on (the default) plays the new animation from its first frame; off carries on from the current position in the animation that was playing. "loop" on (the default) replays it from the start every time it ends; off plays it once and leaves it on its last frame (see "Player animation has finished" to react to that moment).
Player 0/1 current animation ID — Reads the chosen player's currently playing animation as its numeric list position (0-based, top to bottom) - for a fixed animation's ID by name instead, see "Player animation [name]", which does the reverse (name to ID).
When Player 0/1 animation has finished — Runs the connected blocks once, on the single frame the animation ends on: the moment a non-looping animation (see the "loop" checkbox on the Set Animation blocks) reaches its last frame and stops. Never fires for a looping animation (the default), which never actually stops.
Lock [sprite] to [sprite] at X offset [n] Y offset [n] — Makes the first sprite follow the second one, the given number of pixels to the right (X) and down (Y) of it (a negative number goes left or up), every frame until it is unlocked. When the second sprite is a player facing left (flipped), the first one is put on the other side of it and flipped too, so a sword stays in the same hand.
Unlock [sprite] — Lets a sprite locked to another one move freely again; it stays where it is.
[object] set scroll with playfield to [true/false] — Turns automatic playfield-scroll following on or off for this object. While on, every "Background scroll" block using Up/Down/Up (2x)/Down (2x) also shifts this object's Y position by the same amount, so it stays in the same spot relative to the scrolling background instead of the screen. Has no effect on Left/Right scrolling. Accepts true/false or 1/0.
Is [object] scrolling with playfield? — True while this object currently has playfield-scroll following turned on (see "set scroll with playfield to").
Platform [sprite] jump speed [n] gravity [n] max fall speed [n] allow [ ] multi-jump up to [n] jumps [ ] stop at walls left and right — A platformer jump with gravity, for Players 0 and 1, Players 2 to 9 on DPC+, Missile 0, Missile 1 and the Ball. Put it inside an if block (with Joystick 0 Fire, say): each time that runs the sprite jumps, and from then on, every frame, the sprite is pulled down by gravity and stops on top of a lit playfield pixel (and under one above it). A new press is needed for each jump; with multi-jump on it can jump again in the air, up to the number of jumps set (at most 4). The numbers are sockets for number, math or variable blocks: jump speed and max fall speed are 1 to 16 pixels a frame, gravity is 1 to 16 eighths of a pixel a frame. The sprite is put exactly on top of the pixels (never overlapping them), and a sprite standing on a pixel does not move at all, so it does not jitter. Walking off an edge makes the sprite fall and counts as a jump used. Left and right are moved by the other blocks; with stop at walls left and right ticked, a move left or right that would put the sprite's whole box in a lit pixel is taken back, so the sprite stops against a wall (not needed with an Undo last move block for the same sprite). The code is written in assembly and keeps its numbers, speed and state in five bytes a sprite.
[sprite] jumps made — How many jumps a sprite moved by the Platform block has made since it last stood on the ground: 0 on the ground, 1 after the first jump, 2 after a second one in the air (with multi-jump on), up to 4. Walking off an edge counts as a jump used. Use it with a comparison block in an if block, for example "jumps made = 2".
Is [sprite] jumping / falling / on the ground / moving? — True while a sprite moved by the Platform block is going up, coming down, standing on a playfield pixel, or (moving) has changed its x or y in the last frame. Use it in an if block, to change the animation for each, for example.
Joystick 0/1 [Up/Up-Right/Right/Down-Right/Down/Down-Left/Left/Up-Left/Fire/Difficulty A/Difficulty B] — reads a joystick direction, the fire button, or a difficulty switch. A diagonal is true while both of its directions are pushed. (A diagonal inside a not block doesn't build, because batari Basic doesn't accept !(a && b); compare the 8-way direction block below to a number instead.)
Joystick 0/1 direction (8-way) — the current 8-way direction (0=Up, clockwise), or 255 if centered/contradictory.
Keypad 0/1 key [1-9,*,0,#] is pressed — whether a specific key is currently held.
Any key is pressed on Keypad 0/1 — whether any key is currently held.
Key ID pressed on Keypad 0/1 — the ID of whichever key is held (1-9, then *=10, 0=11, #=12), or 0 if none.
Collided [object] and [object] [ ] use box [whole sprite / 8x8 / 8x4 / 8x2] — checks whether two objects collided (Player 0/1, Missile 0/1, Ball, Playfield). With use box ticked, a player and the Playfield are tested with the player's whole box (its full width and height, whatever pixels are lit in it) instead of the hardware flag; the answer is as of the end of the last frame. The last list picks the part of the sprite that is tested: whole sprite, or only its lowest 8, 4 or 2 lines (8x8, 8x4, 8x2), all of its width (double and quad wide too), for its feet. With the DPC+ kernel the dropdowns also list Players 2 to 9. The hardware flag of DPC+ Player 1 stands for all the virtual sprites (Players 1 to 9) at once, so a project that uses any of Players 2 to 9 compares Player 1 (and Players 2 to 9) by their boxes: for the Playfield with the box test, for another player or a missile or the ball with the boxes (and the hardware flag of the missile or the ball), again as of the end of the last frame.
Sprite [object] and [object] overlap [starts / stops] — true for exactly one frame: the frame in which the two sprites begin to overlap (starts), or stop overlapping (stops). Use it in an if block to react to the moment of contact or of leaving, once, instead of on every frame the sprites touch. Pick the two sprites in the dropdowns (Player 0/1, Missile 0/1, Ball; with the DPC+ kernel also Players 2 to 9). The sprites overlap when their boxes touch: a player's box is its whole width and height, including the right half of a 16 pixel wide player and the copies of a player with copies. The answer is as of the end of the last frame. Use one block for each pair of sprites; each block takes two bits of memory, which are shared with other blocks of its kind. It is in the Input group of the block list, next to Collided.
Undo last move for [Player] if it collided with Playfield, going back [1 frame / 2 frames] using the [whole sprite / 8x8 / 8x4 / 8x2] — reverts the player's position if it collided with the playfield last frame. Going back 2 frames puts the player where it was two frames ago instead of one (it takes two more variables). Place before whatever moves the player. The last list works as on the Collided block: it can test only the lowest 8, 4 or 2 lines of the player, so the player can walk past things that are higher up. When several of these blocks are for the same player, the whole sprite is used unless every one says 8x8, 8x4 or 8x2 (the most lines of them is used).
Switch [Reset/Select/Color/Black-White] — reads a console switch. A "was just switched on" mode is true for one frame each time a switch is turned on, so the blocks under it run once per press instead of every frame the switch is held.
Color [swatch] — picks a color from the NTSC palette.
Distance X/Y between [object] and [object] — the always-positive X or Y distance between two objects.
Distance X/Y between [object] and [n] — same, against an arbitrary X or Y value instead of a second object.
Random 1..255 — a random number between 1 and 255.
Random [range] — a random number within a preset range.
Random from [min] to [max] — a random number from the first number to the second, both included, each equally likely (numbers up to 255; if the first is bigger than the second they swap places). It takes a few steps to work out, so a block that runs every frame is better off with one of the quicker Random blocks when a power of two range is enough.
Set random seed to [n] — reseeds the random generator (clamped 0-255), so runs don't repeat the same sequence.
bit [0-7] of [variable] — checks whether a single bit of a variable is set.
set bit [0-7] of [variable] to [value] — sets a single bit of a variable.
[first / last] 4 bits of [variable] — a number from 0 to 15: the first 4 bits are bits 0 to 3 (the variable AND 15), the last 4 bits are bits 4 to 7 (the variable divided by 16).
set [first / last] 4 bits of [variable] to [number] — sets one half of a variable to a number from 0 to 15 and leaves the other half alone. Only the lowest 4 bits of the number are used.
[built-in variable] — reads a built-in batari Basic variable directly: player0size, player1size, player0frame, player1frame, framecounter, CTRLPF, NUSIZ0, NUSIZ1, SWCHA, or SWCHB. The list also has the variables the blocks of the open project make, such as the Platform block's state, speed and fraction for a player (platState, platSpeed, platFrac), a Seek block's target and speed, and the timer of Clear text after.
Display RAM area [1-6] byte [0-127] set to [n] / change by [n] / Display RAM area [1-6] byte [0-127] — DPC+ only: the display memory has six areas of 128 spare bytes (numbered 0 to 127) that work like variables, so a project can keep another 768 numbers in them. They are not available while the playfield has more than 127 rows or a background scrolls (those use the whole memory), and a get takes a few dozen cycles longer than a normal variable.
Joystick 0/1 Fire [pattern] [n] frames — Reads the chosen joystick's Fire button press pattern - "frames" means something different depending on which pattern is picked (60 frames = 1 second), and is ignored entirely for "released" (hidden for that pattern - there's nothing to set): • tapped - true for exactly one frame, the instant Fire is pushed down (no waiting for it to be released; "frames" is not used). • held - true on every frame Fire has been continuously held down for at least "frames" so far - stays true for as long as it's still held past that point, not just one frame. • released - true for exactly one frame, the instant Fire goes from held down to released. • double-tapped - true for exactly one frame, the instant Fire is released for the SECOND time within "frames" of the first release. Every release starts (or restarts) its new window; a release that doesn't land inside a still-open window from an earlier release just opens another window instead of triggering this. Doesn't care how long either individual press was held, only the gap between the two releases.
Draw title screen — draws the chosen Title tab page. Call every frame it should show; it takes over the whole frame.
Set title screen scroll position of [graphic] to [n] — scrolls a Title graphic with scrolling enabled. 0 is the top; animation keeps playing by itself.
Set title screen player [0/1] sprite frame to [n] then [loop / play once] — changes which frame of a "Player sprites" card is showing; an animation with several frames plays by itself. Position with the normal Player X/Y blocks.
Animate title screen graphic [graphic] [forward / in reverse] then [loop / play once], When title screen graphic [graphic] animation finishes, Set title screen graphic [graphic] to frame [n] hold it [ ] then [loop / play once], Set title screen graphic [graphic] color to [n], Set title screen graphic [graphic] picture background to [...], ...picture background color to [n], Set title screen background color to [n], Reset title screen background color, Fade title screen graphic [graphic] color to [color] over [n] frames End title screen and Start title screen — see Title.
Scroll title screen graphic [graphic] [Up/Down] by [n] — Moves a scrolling Title Screen graphic up or down by the given number of rows from its current position (use "Set title screen scroll position" to start anywhere). With "stop at edge" on, scrolling halts when the top of the graphic reaches the top of its window, or the bottom of the graphic reaches the bottom of its window. With more than one animation frame, the edge is that of the frame currently showing.
When title screen scroll of [graphic] reaches the [Top/Bottom] — Runs the connected blocks once, each time a "Scroll title screen graphic" block with "stop at edge" on lands on the top or bottom edge of that graphic. Setting the position directly does not count.
Sprite priority [Sprites above playfield / Playfield above sprites] — whether the playfield/ball draw in front of or behind sprites.
Playfield [name] — looks up a background by name and reports its number, for "Background set to."
Playfield set to [selection] — updates the currently displayed background.
Playfield [name] (statement form) — sets the displayed background directly, without a separate select+set pair.
Playfield set [Background/Playfield] color to [color] — sets the background or playfield color.
Get [Background/Playfield] color — reads the current background or playfield color.
Fade [Background/Playfield] color to [color] over [n] frames — fades that color toward a target over roughly that many frames. Trigger once; keeps running until it arrives.
When [Background/Playfield] color has finished fading — runs once when a matching fade reaches its target.
Is [Background/Playfield] color fade active? — true while a fade is in progress.
Playfield get pixel at X [x] and Y [y] — reads a single playfield pixel (if-statement only).
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] area [from / centered at] ... — sets, clears or flips every playfield pixel in a rectangle (columns and rows are numbered from 0, the same numbers as Playfield get pixel). The mode in the middle of the block picks how the rectangle is given:
- from X [x1] Y [y1] to X [x2] Y [y2] — the rectangle between the two corners, which can be given in either order.
- centered at X [x] Y [y] width [w] height [h] — a rectangle of that width and height with the column and row in the middle of it (an even width or height has the extra pixel to the right or below). Its padding is how many columns at the left and at the right of the playfield, and how many rows at the top and at the bottom, it leaves alone (0 draws to the edges), one number for all the sides or one for each side.
Any part of the rectangle outside the playfield is ignored. It draws a row at a time, so a big area takes a while. It can't be used inside a custom function.
Playfield [Set / Clear / Flip] circle at X [x] Y [y] radius [r] padding [the same on all sides / separate for each side] — sets, clears or flips every playfield pixel within the radius (in playfield pixels, up to 15) of the center column and row. A pixel is in the circle when its distance from the center is no more than the radius, and any part of the circle outside the playfield is ignored. The padding is how many columns at the left and right of the playfield, and how many rows at the top and bottom, the block leaves alone: 0 draws to the edges. It can be one number for all the sides or a number for each (left, right, top, bottom). It draws a row at a time, so a big circle takes a while. It can't be used inside a custom function.
Reset playfield scroll — moves the scroll back to the top row of the background, as it is when a background is switched to (the same as Set playfield scroll to row 0). It only does something for a background taller than the screen, and works whether it comes before or after a Set background block in the same event.
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 at any angle between two points.
Playfield height (rows) — the playfield's row count (Superchip pfres if enabled, otherwise 11).
Convert playfield [X/Y] [n] to [single-wide sprite/double/quad-wide sprite] — converts a playfield column/row to the matching sprite coordinate. With DPC+ and playfield columns that have different rows (Playfield tab), the optional column socket (an X from 0 to 31) says which playfield column's rows a Y conversion uses.
Convert [single-wide sprite/double/quad-wide sprite] [X/Y] [n] to playfield — converts a sprite coordinate to the matching playfield column/row.
Find playfield pixel [Player 0/1, Missile 0/1, Ball] collided with, moving in direction [n] — works out exactly which playfield pixel a sprite just hit. Put it right after a "Collided [object] and Playfield" check, then read the result with Playfield collision column (0-31) and Playfield collision row.
The direction is the way the sprite is traveling: 0-7 clockwise from Up (0 Up, 1 Up-Right, 2 Right, 3 Down-Right, 4 Down, 5 Down-Left, 6 Left, 7 Up-Left), the same numbers as the Fire block's angle and the joystick direction. When the direction is a Fire angle block for a Fire block set to 16 directions, it reads the full 0-15 range. 255 (or any other value) means no direction.
A sprite's position doesn't always land exactly on a pixel, and a missile or ball can be wider than one pixel and taller than one row unit. So the block tries these cells in order and keeps the first lit one: the cells the sprite touches, the cells directly above or below it, the cells beside it in the direction it is moving, and last the diagonal one. A pixel directly above, beside or a little below a sprite moving at an angle is found without needing anything else lit around it.
If the direction is a Fire angle and Bounce has just turned the object around, the block uses the direction from before the bounce, so the pixel that was hit is still found. Combine it with Playfield [Set/Clear/Flip] pixel to, for example, shoot holes in a wall (see the Shoot the Wall example on the Project tab). Projects made before this version may contain an older "moving right / moving down" version of the block; it still works, but takes two true/false inputs instead of one direction, and the new block replaces it in the toolbox.
Playfield collision column / Playfield collision row — the pixel found by the last "Find playfield pixel" block that ran. Only meaningful right after it runs in the same frame.
Playfield clear all pixels — turns off every playfield pixel at once.
Playfield rainbow colors, offset [n] — gives every playfield row a different color, reading raw ROM bytes the same way the player rainbow colors block does. Leave the offset unplugged (or plug in the frame counter) for an automatically shimmering pattern, or plug in a number or variable to hold or scroll the pattern yourself. It needs Playfield row colors turned on in Options; without it the block does nothing.
Playfield scroll colors [direction] — scrolls only the playfield row colors and leaves the pixels where they are, with the same Up/Down/Up (2x)/Down (2x) directions and stop at top/bottom edge option as Background scroll. It needs per-row playfield colors turned on. With DPC+ the colors move a scanline at a time; the standard kernel moves them a whole playfield row at a time, since each playfield row has one color.
Playfield offset [alternate rows left and right / alternate rows right and left / 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; alternate rows right and left starts the other way round (the first row goes right, the next left). Untick whole playfield to move just an area: from X [column] Y [row] to X [column] Y [row] (the columns are any of the playfield's columns 0 to 31 and the rows are counted from 0 like Playfield get pixel; the four numbers can be variables or any math block, and a pixel that leaves one edge of the area goes in at the other edge of the next row). Run it every few frames for a slower drift. Only pixels move; per-row colors stay where they are. It works with the standard kernel (with or without Superchip RAM) and DPC+. With DPC+ the coprocessor does the work, for any area and any direction: a 2 row alternate offset every 4 frames costs about 4 scanlines of the frame instead of 16.
Stop playfield rainbow colors — stops it and puts the playfield rows back to the row colors of the background that is loaded (the colors set for it on the Background tab). The playfield pixels are left alone.
Playfield scroll [direction] — scrolls the background left, right, up, down, or up/down by 2 pixels. Down moves the background down and Up moves it up, whatever its height. Up/down can scroll through a background taller than the screen (set its height on the Background tab); "stop at top/bottom edge" stops on the first/last row, otherwise it wraps around. "scroll playfield colors" moves each row's color with its pixels (see the Background page).
Playfield transition to [background] scrolling [Up/Down] — scrolls another background in over the one showing, a row at a time, instead of swapping to it. The block only starts the transition: each Playfield scroll block that moves the same way (Up or Down, 1x or 2x) then brings in one more row of the new background, and once its rows have filled the screen it is the background showing and scrolling carries on through it. Up brings the new background in from the bottom, Down from the top. Scrolling the other way waits until the transition is over, and "stop at top/bottom edge" is not checked during it. With "scroll playfield colors" the row colors change over to the new background when the transition is complete. The standard kernel only (DPC+ ignores the block). The backgrounds should have the same height. Using the block makes every background of the project go through the row-loading routine, which costs a little ROM and RAM.
Set playfield scroll to row [n] — starts or jumps the scroll at row n of a background taller than the screen (0 = top, clamped to the last scrollable row).
When playfield scroll reaches the [Top/Bottom] — runs its blocks once each time Up/Down scrolling lands on the top or bottom row.
Draw screen — batari Basic's "drawscreen."
Fade [Playfield/Background] rows from [color] up/down to row colors over [n] frames — Starts every playfield (or background) row at the brightness of the chosen color and fades each row up or down to its real color from the Background editor, over roughly this many frames. Needs "Enable per-row playfield colors" (Options tab; for the background rows, "Enable per-row background colors" on DPC+) and a color from the color picker block. Only needs to be triggered once. Switching backgrounds cancels it. "Fade color to" does the opposite, from the row colors down to a color.
Playfield scroll position — How many rows Up/Down scrolling has moved the currently shown background from its top row (0 = top). Only updated by "Background scroll" blocks using Up/Down/Up (2x)/Down (2x) - Left/Right don't affect it. Resets to 0 whenever a different background is switched to.
Shake screen for [n] frames — Vibrates the whole screen up and down by one scanline, every other frame, for roughly this many frames (at most 127; a longer count is shortened to 127), then stops automatically. Only needs to be triggered once - the shake keeps running by itself every frame afterward, even from inside an "if" block that only briefly becomes true, same as "Fade color to". Triggering it again while already shaking restarts the countdown at the new frame count, rather than stacking.
The scenes are made on the Scene tab: each holds a playfield and the sprites placed on it, with their positions, colors, widths and animations. The Scene category has two blocks that put a scene on the screen.
Set scene [scene] — puts the chosen scene on the screen: its playfield, and each sprite it holds with its position, color, width, animation, direction and whether it is hidden. The list shows the project's scenes and follows renaming, adding and deleting. A sprite that the scene does not hold is left as it was. When the project is built the block is replaced by the ordinary Playfield and Sprites blocks that do the same, so it costs the same ROM as writing them by hand.
Set scene by ID [n] — the same, for the scene whose card on the Data tab has the number n (the ID badge on the scene's card). n is a number, so it can come from a variable or a calculation, for example the number of the stage the player has reached.
Use them where a stage or a menu starts: in an event such as "Gameplay start", or when the game state changes.
Score / Score set to [n] / Score change by [n] — reads, sets, or adds to the six-digit score.
Score color / Score set color to [color] / Score change color by [n] — reads, sets, or changes the score's color.
Fade Score color to [color] over [n] frames — fades the score's color toward a target over roughly that many frames.
When Score color has finished fading — runs once when a matching fade reaches its target.
Score set background color to [color] — sets the score row's background color (Text Minikernel only).
Score digit [1-6] / ...set to [n] / ...change by [n] — reads, sets, or changes a single digit (0-9), left to right. No wrap/carry.
Score Bar [1/2] / ...set to [n] / ...change by [n] — reads, sets, or changes a playfield score bar's binary pattern (%00000000-%11111111).
Score Bar [1/2] set health to [0-8] — fills a bar with a solid block of the given width.
Score Bar [1/2] set lives to [0-4] — fills a bar with evenly spaced dots.
Score Bar [1/2] change health by [n] — grows/shrinks a health-style bar.
Score Bar [1/2] change lives by [n] — adds/removes dots from a lives-style bar.
Score set font to [primary/secondary] — Switches the score digits to the primary or the secondary font chosen on the Score tab, at once. Does nothing without a secondary font.
Data table [name] at index [n] — reads a value from a read-only Data tab table.
Data table ID [n] at index [n] — same lookup, table chosen by ID instead of name.
Data table [name] bit [0-7] at index [n] — checks a single packed bit of a table value.
Data table ID [n] bit [0-7] at index [n] — same bit check, table chosen by ID.
Size of data table [name] / Size of data table ID [n] — how many values the table holds.
Show text [name] — displays a Text tab message in place of the score, auto-scrolling if it's too long.
Show text ID [n] — same, but the message is chosen by its position on the Text tab (1 = first) so it can be picked at runtime from a variable.
Show text [free-typed text] — same, typed directly instead of picked from the Text tab.
Show text row [1/2] [name] / ...ID [n] / ...[free-typed text] — writes only one row (the other stays blank); only the message's first line is used, no word-wrap or scrolling.
Clear text — clears the currently displayed message.
Clear text after [n] frames — put it after any block that shows text (by name, by ID, scrolling, several lines, one row, typed text): the message is cleared once n frames (1 to 255; 60 is about a second) have passed. It clears whatever text is shown then, so run it again after showing another message to give that one its time.
Scroll text [name] / ...ID [n] / ...[free-typed text] — like "Show," but adds "every [n] frames"/"wait [n] at limits" fields to tune scroll speed/pause. Ignored if the message already fits.
Text scroll [Start/Pause/Unpause/Stop/Restart] — Start/Unpause resume from where it is; Pause freezes it in place; Stop resets to the start and freezes there; Restart resets but keeps scrolling.
Is text scroll at [Left/Right]? — true while paused at that end (always true for Left on a message that never needed to scroll).
Scroll text lines up/down [1 line/2 lines] — reveals an earlier/later line of a message with more than 2 lines; never scrolls past the first/last line.
End of text? — true whenever the "end of message" icon would be showing.
Text scroll cursor [show/hide] — shows/hides the scroll cursor at runtime (only if the Text tab's "Show a scroll cursor" switch is on).
Text set [row 1/row 2/both] color to [color] — sets message color; Row 2 only matters for a wrapped second line and falls back to Row 1 until set.
Text set scroll cursor color to [color] / Text set end icon color to [color] — sets those indicator colors.
Fade Text color to [color] over [n] frames — fades the message color toward a target. Trigger once; keeps running every frame until it arrives.
When Text color has finished fading — runs once when a matching fade reaches its target; does nothing if no fade ever runs.
Play sound effect [name] on [channel] [loop] — plays a Sound tab preset on channel 0 or 1. With loop ticked (off by default) the sound starts over every time it ends, until another sound is played on the channel or a Stop sound on block ends it. The preset's frequency sweep, frequency envelope, arpeggio and volume envelope all play.
Play sound [type] with frequency [n], volume [n] and duration [n] on [channel] [loop] — plays a one-off sound directly, no Sound tab entry needed. loop works as on the block above.
Stop sound on [channel] — silences whatever sound is playing on the channel, a loop included. Music on the channel carries on with its next note.
Set max sound volume to [0-15] — the loudest volume any sound or music note can play at, on every channel, until it is set again. 15 is no limit; the value can be a variable, so sounds can get quieter while something happens.
The AtariVox is a speech chip in the Player 2 controller port. These blocks make a game talk through it. The preview speaks in both emulators (the speech chip is emulated in each): the AtariVox is plugged in for you while the loaded ROM has a speech block, or turn on AtariVox in the Emulator settings yourself for a ROM made some other way. The Player 2 joystick can not be used with an AtariVox in the port.
A phrase goes out to the chip one byte a frame while the game runs on; the block returns at once. Each saying block has a choice: now stops what is being sent and says the new phrase at once, after the current phrase waits for the phrase being sent and the one waiting (a queue of two; a third is dropped). The speech blocks of a project together can have at most 254 different phrases.
AtariVox say text [message] — speaks a message of the Text tab. The text is turned into speech sounds when the project is built, by rules for English (numbers are spoken as words, a comma is a short pause and a full stop a longer one). Most plain words are understood, but not all of them. The play button on the block speaks the message in the editor. The Text tab can fix how a message or a word is spoken.
AtariVox say text card ID [number] — speaks the Text card whose ID is the number (a number typed in the block, a variable or a calculation), so the program chooses which message while it runs. Every card of the project goes in the ROM as speech, so it takes more room than "say text". An ID no card has says nothing. The play button speaks the card when the ID is typed in the block.
AtariVox say number [value] — speaks a number from 0 to 255 as words (a value or variable: the lives left, a level). The words for 0 to 99 and for 100 and 200 take about a kilobyte of ROM, once, however many of these blocks there are.
AtariVox say phonemes [words] — speaks a phrase of sounds separated by spaces, for a phrase that has to be exactly right. The words are:
| Kind | Words | What they do |
|---|---|---|
| Allophones | IY, IH, EH, AY, UW, OWWW, MM, SO, HE and so on | The sounds of speech. HE EH LE OWWW is "hello". |
| Sound effects | R0 to R9, A0 to A9, B0 to B9, C0 to C9, D0 to D11, M0, M1, M2 | R robot, A alarm, B beeps, C biological, D tones, M0 sonar ping, M1 pistol shot, M2 "wow". |
| Pauses | PAUSE30, PAUSE60, PAUSE90, PAUSE200, PAUSE700, PAUSE1000 | A silence of that many milliseconds. |
| Speech changes | FAST, SLOW, STRESS, RELAX | Change how the words after them are spoken. |
| Settings | VOLUME n, SPEED n, PITCH n, BEND n, DELAY n | A number from 0 to 254 after the word. |
| Any byte | #n | The byte n (0 to 254) as it is. |
AtariVox set [volume / speed / pitch / bend] to [number] — changes the voice for the phrases after it: volume 0 to 127, speed 0 to 127, pitch 0 to 255, bend 0 to 15. It goes in the queue like a phrase, so it comes in its place between phrases.
AtariVox stop sending speech — stops sending the rest of the phrase. What the chip has already been sent is still spoken.
AtariVox is still being sent a phrase — true while the bytes of a phrase are still going to the chip (it may go on speaking a little after that).
An AtariVox also holds a 32 KB memory chip, for a high score or a setting kept between plays. A project with one of these blocks has the AtariVox plugged in for the preview.
AtariVox memory: save [value] in slot [number] — keeps a byte (0 to 255) in a slot from 0 to 255. It waits for the chip to finish writing (a few milliseconds), so save at a quiet moment, not every frame.
AtariVox memory: load slot [number] into [variable] — reads the byte of a slot into a variable. A memory that does not answer (no AtariVox plugged in) leaves the variable as it was. A slot never saved holds 255.
In the editor's emulators the memory lasts until the page is closed; a real AtariVox keeps it.
Play song [name] — starts/restarts a Music tab song. Plays once and stops if Loop is off.
Play song [id] — same, song chosen by a runtime ID.
Song [name] is playing — true while that song is the current one (including paused).
Song ID [n] is playing — same check, song chosen by a runtime ID.
Stop music — stops playback immediately; a later "Play song" restarts from the beginning.
Pause music — freezes playback in place until "Unpause music."
Unpause music — resumes playback frozen by "Pause music."
When song has stopped playing — runs once when a non-looping song ends naturally.
When song has stopped playing [name] / ...[id] — same, only for the specified song.
When a sequence chip has finished playing — runs once whenever any Sequence chip finishes its repeat count.
When sequence chip ID [n] has finished playing — same, for a specific chip position in a named song.
When sequence chip ID [n] has finished playing (current song) — same, for whichever song is currently playing.
When a note is played by instrument [name] — runs whenever any channel starts a note with this instrument.
When a note is played by instrument ID [n] — same, instrument chosen by ID.
Sequence chip [song] ID [n] is playing — True for as long as the chosen song is the one currently playing (including while paused) AND its Sequence position is at this chip - read the position off the small "ID: N" badge next to that chip in the Sequence list (1 = first chip; changes if you reorder, insert, or delete chips before it). False if that song doesn't have that many chips.
Sequence chip ID [n] is playing (current song) — True for as long as whichever song is CURRENTLY playing has its Sequence position at a chip in this position - checks every song that has a chip in this position, not just one fixed song. Read the position off the small "ID: N" badge next to that chip in the Sequence list (1 = first chip; changes if you reorder, insert, or delete chips before it). False if no song has that many chips, or nothing is playing.
On [System start / Title screen start / Title screen update / Gameplay start / Gameplay update / Gameover start / Gameover update] — runs the connected blocks when the given event happens.
Change state to [Title screen / Gameplay / Gameover] — changes the game's current state.
On even frames / On odd frames — runs different blocks depending on the current frame's parity.
Every [n] frames, plus [n] — runs the connected blocks on a power-of-2 interval, with an optional offset.
Run once — runs the connected blocks only the first time reached; skipped every time after.
Define subroutine / Call subroutine — defines and calls a reusable, parameterless block of code.
Define function / function parameter / return [value] / call function (statement) / call function (value) — defines and calls a reusable block that accepts arguments and can return a value.
[Comment text] — inserts a comment into the generated code; no effect on the game.
[Comment text] (wrapper) — groups connected blocks under a comment label; everything inside still runs normally.
Return from subroutine — Ends the subroutine this block is in and goes back to the "Call" block that ran it (batari Basic return). A subroutine also returns by itself after its last block.
Label [name] — A named place in the code that a "Go to label" block can jump to, with the blocks inside it. The code goes on with the blocks inside the label and then with the blocks after it. The jump and the label have to be in the same event, subroutine or function.
Go to label [name] — Jumps to a "Label" block in the same event, subroutine or function (batari Basic goto). Put it at the end of a stack, often inside an "if".
Pre-built drag-in example blocks (this category was called Examples in earlier versions) meant as starting points to learn from or build on.