Steam Community :: Guide :: Lua Documentation

Store Page

DX-Ball 2: 20th Anniversary Edition

All Discussions Screenshots Artwork Broadcasts Videos Workshop News Guides Reviews

DX-Ball 2: 20th Anniversary Edition > Guides > CSY's Guides

Not enough ratings

Lua Documentation

By CSY and 1 collaborators

This technical guide documents the specifics of the DX-Ball 2's unique functions.

Award

Created by

CSY
Online

McDude73
Offline

Category: Modding or Configuration, Workshop

Languages: English

Posted

Updated

3 Feb, 2023 @ 8:29am

14 Jun @ 8:31am

129	Unique Visitors
8	Current Favorites

Guide Index

Overview

Introduction

function onCollectPowerup(pwrup)

function onHitBrick(x, y, layer)

function onHitButton(x, y, layer)

function onUpdate(msecs)

dxball.addPowerupCrate(position, layer, pwrup)

dxball.addPowerupCrateClr(position, layer, pwrup, color)

dxball.addSaveVariable(varName)

dxball.addSaveVariables(varArray)

dxball.clearBricks()

dxball.disablePowerup(pwrup)

dxball.drawBricks()

dxball.getBrick(position)

dxball.getBrickOnLayer(position, layer)

dxball.getFirstBall()

dxball.getGameTime()

dxball.getLayerOffset(layer)

dxball.getPaddlePosition()

dxball.getRandomBrickPos(minY, maxY, layer)

dxball.pauseUpdates(flag)

dxball.rerollPowerups()

dxball.setAllBricks(brush)

dxball.setBackground(backId)

dxball.setBrick(position, brush)

dxball.setBrickOnLayer(position, brush, layerID)

dxball.setBrickFlags(position, layer, flags, active)

dxball.setBrickFlagsByName(position, layer, flag, active)

dxball.setBrickState(position, layer, state)

dxball.setBrickStateByName(position, layer, state)

dxball.setLayerBrickFlags(layer, flags, active)

dxball.setLayerBrickFlagsByName(layer, flag, active)

dxball.setLayerBrickState(layer, state)

dxball.setLayerBrickStateByName(layer, state)

dxball.setLayerOffset(layer, offsetX, offsetY, wrap)

dxball.setLayerVisible(layer, vision)

dxball.setPowerup(pwrup, weight, duration)

dxball.setUpdateInterval(msecs)

dxball.setZapOnNonBreak(enabled)

About Brick Flags

About Brick States

About Powerup Strings

Comments

Introduction

The 20th Anniversary Edition of DX-Ball 2 has introduced scripting for levels in version 2.2, via the LUA programming language. The objective of this guide is to document each unique function of the DX-Ball 2 library.

Customizable function blocks in this document are optional, and do not have to be present in every scripted level.

Fixed functions start with dxball.

function onCollectPowerup(pwrup)

A function that will execute its code whenever a specific powerup is collected. Usually, this is used to implement functionality to time powerups.

Can also equal an existing function in order to reuse that function.

pwrup - string; The specific powerup that was acquired

function onHitBrick(x, y, layer)

A function that will execute its code whenever any brick gets hit. For documentation purposes, the brick that just got hit will be termed the "victim". Brick information is retrieved before damage is applied, while ball information is retrieved after bounces take place (if any).

x - integer; x coordinate of the victim
y - integer; y coordinate of the victim
layer - integer; layer of the victim

function onHitButton(x, y, layer)

A function that will execute its code whenever a switch brick gets hit by a ball (not by lasers or splash damage). Has a debounce delay that prevents the function from being triggered too frequently. For documentation purposes, the brick that just got hit will be termed the "victim".

x - integer; x coordinate of the victim
y - integer; y coordinate of the victim
layer - integer; layer of the victim

Optionally supports a "return true;". If this is reached, it will prevent the switches from being flipped.

function onUpdate(msecs)

A function that will execute its code every so often.

msecs - integer; passed by reference from dxball.setUpdateInterval(msecs). Think of milliseconds* in between intervals.

*1 second = 1000 milliseconds

dxball.addPowerupCrate(position, layer, pwrup)

This function must be added to the Start Board code to work properly. It will place a powerup at a brick's position using a 2-dimensional vector. You will also have to choose a layer, and find the string name for a specific powerup for the brick. This command colors crates green; vec3d(0, 1, 0). An example is shown below.

position - vec2d(x, y); the position of the brick for where the powerup is being placed.
layer - integer; a specific layer chosen to place the powerup in the brick given from the position 2-dimensional vector.
pwrup - string; the powerup to assign to this crate. See "About Powerup Strings"

dxball.addPowerupCrateClr(position, layer, pwrup, color)

This function must be added to the Start Board code to work properly. It will place a powerup at a brick's position using a 2-dimensional vector. You will also have to choose a layer, find the string name for a specific powerup for the brick, and add a 3-dimensional vector for the color of the outlining of the brick. An example from Switch It Up is shown below, containing 2 bricks that are given red Kill Paddle crates.

position - vec2d(x, y); the position of the brick for where the powerup is being placed.
layer - integer; a specific layer chosen to place the powerup in the brick given from the position 2-dimensional vector.
pwrup - string; the powerup to assign to this crate. See "About Powerup Strings"
color - vec3d(r, g, b); float numbers that determine how much red, green, or blue you would like to use on the outlining. r, g and b can be a minimum of 0.0 and a maximum of 1.0.

dxball.addSaveVariable(varName)

Adds a single variable to the save system. This is effective only for one level.

varName - string; variable name to save

dxball.addSaveVariables(varArray)

Adds multiple variables to the save system. This is effective only for one level.

varArray - array of strings; collection of variables to save

dxball.clearBricks()

This function will clear the entire grid on layer 0. Bricks changed this way are automatically drawn.

dxball.disablePowerup(pwrup)

Disables the specified powerup from appearing randomly in the level. Only effective at setup (outside of functions), or if it precedes dxball.rerollPowerups().

pwrup - string; The powerup to disable. See "About Powerup Strings"

dxball.drawBricks()

Redraws the bricks. Changes made via dxball.setBrick or dxball.setBrickOnLayer will be rendered. Invisible bricks will also be properly applied.

dxball.getBrick(position)

Returns an integer containing a particular brick's ID number; based on the given position. Reads bricks from layer 0.

position - vec2d(x, y); the position given in order to find the brick ID.

dxball.getBrickOnLayer(position, layer)

Returns an integer containing a particular brick's ID number; based on the given position and layer.

position - vec2d(x, y); the position given in order to find the brick ID.
layer - integer; the layer to search.

dxball.getFirstBall()

Returns two values, based on the lowest ID ball currently in play. (If no balls are in play, returns nil instead.)

ballPos - vec2d(x, y); Returns the position of the ball
ballSpeed - vec2d(x, y); Returns the speed of the ball, likely in pixels per second

dxball.getGameTime()

Returns an integer containing the number of milliseconds since the board set has started.

dxball.getLayerOffset(layer)

Returns a vec2d containing the current offset of the selected layer.

layer - integer; the layer to read the offset from

dxball.getPaddlePosition()

Returns a vec2d(x, y) containing the coordinates of the middle of the paddle.
This may be followed by either .x to get the X-coordinate, or .y to get the Y-coordinate.

dxball.getRandomBrickPos(minY, maxY, layer)

A function that will search through eligible bricks. Only regular bricks are eligible to be picked this way. (Not switches, multiHits, invincibles, invisibles, nor permanents.)

minY - integer; top most row to search
maxY - integer; bottom most row to search
layer - integer; layer to search. If set to -1, all layers are searched

Returns a trio of values that corresponds to an existing brick.

x - integer; x-coordinate of the selected brick
y - integer; y-coordinate of the selected brick
layer - integer; layer of the selected brick

dxball.pauseUpdates(flag)

This function will determine whether to pause the usage of onUpdate.

flag - boolean; if set to true, will stop onUpdate calls. If set to false, will resume onUpdate calls.

dxball.rerollPowerups()

A bit of a misnomer, this function applies mid-level dxball.disablePowerup() calls.
Example: If Thru Brick is disabled mid-level via dxball.disablePowerup(), then it won't take effect until dxball.rerollPowerups() is also called.

dxball.setAllBricks(brush)

This function will set a particular brick to the entire grid on layer 0. Bricks changed this way are automatically drawn.

This function is applied in between the damage calculation and the damage dealt steps on a multiHit or soft brick.

brush - integer; a brick identification number that is chosen to be placed based on the given brush position.

dxball.setBackground(backId)

This function will change the background of the level to the new backId stated. ID bindings are based on the background IMG file that has been used for the board set.

backId - integer; the ID number of the background to load.

dxball.setBrick(position, brush)

This function will set a particular brick as a position given using a 2-dimensional vector, along with the ID of the brick in the IMG file. This places the brick on layer 0. To see the changes, you must draw the bricks afterwards.

This function is applied in between the damage calculation and the damage dealt steps on a multiHit or soft brick.

position - vec2d(x, y); the position of where you want to place a brick.
brush - integer; a brick identification number that is chosen to be placed based on the given brush position.

dxball.setBrickOnLayer(position, brush, layerID)

This function will set a particular brick as a position given using a 2-dimensional vector, along with the ID of the brick in the IMG file, bound to the specified layer. To see the changes, you must draw the bricks afterwards.

This function is applied in between the damage calculation and the damage dealt steps on a multiHit or soft brick.

position - vec2d(x, y); the position of where you want to place a brick.
brush - integer; a brick identification number that is chosen to be placed based on the given brush position.
layerID - integer; the layer to place the brick on.

dxball.setBrickFlags(position, layer, flags, active)

This function sets flags to a specific brick. See "About Brick Flags" for more information.

position - vec2d(x, y); the position given in order to find the brick ID.
layer - integer; the layer to search.
flags - integer; one or more flags to assign to this brick.
active - boolean; enable these flags?

dxball.setBrickFlagsByName(position, layer, flag, active)

This function sets a named flag to a specific brick. See "About Brick Flags" for more information.

position - vec2d(x, y); the position given in order to find the brick ID.
layer - integer; the layer to search.
flag - string; a flag to assign to this brick.
active - boolean; enable this flag?

dxball.setBrickState(position, layer, state)

This function sets a state to a specific brick. See "About Brick States" for more information.

position - vec2d(x, y); the position given in order to find the brick.
layer - integer; the layer to search.
state - integer; sets the brick to the appropriate pressed state

dxball.setBrickStateByName(position, layer, state)

This function sets a state to a specific brick. See "About Brick States" for more information.

position - vec2d(x, y); the position given in order to find the brick.
layer - integer; the layer to search.
state - string; sets the brick to the appropriate pressed state

dxball.setLayerBrickFlags(layer, flags, active)

This function sets flags to an entire layer. See "About Brick Flags" for more information.

layer - integer; the layer to search.
flags - integer; one or more flags to assign to this layer.
active - boolean; enable these flags?

dxball.setLayerBrickFlagsByName(layer, flag, active)

This function sets a named flag to an entire layer. See "About Brick Flags" for more information.

layer - integer; the layer to search.
flag - string; a flag to assign to this layer.
active - boolean; enable this flag?

dxball.setLayerBrickState(layer, state)

This function sets a state to an entire layer. See "About Brick States" for more information.

layer - integer; the layer to search.
state - integer; sets the layer to the appropriate pressed state

dxball.setLayerBrickStateByName(layer, state)

This function sets a state to an entire layer. See "About Brick States" for more information.

layer - integer; the layer to search.
state - integer; sets the layer to the appropriate pressed state

dxball.setLayerOffset(layer, offsetX, offsetY, wrap)

This function makes the given layer move horizontally, vertically, or both. Depending on the offset, the bricks could go off-screen, but depending on what you do with wrap, you will see the bricks remain on the board.

layer - integer; A given layer number.
offsetX - integer; Move the layer horizontally either to the right or the left.
offsetY - integer; Move the layer horizontally either down or up.
wrap - boolean; If this is set to false, the bricks will leave the screen. Bricks that leave outside the board still exist in the layer. If it is set to true, any bricks that would go outside of the board will appear from the other side.

dxball.setLayerVisible(layer, vision)

This function can only be called while present in Init Board and not during the transition to the board itself. Sets whether the layer is visible in play or not. If invisible, none of the bricks in the layer can be hit.

layer - integer; the layer to edit
vision - boolean; whether to make it visible or not

dxball.setPowerup(pwrup, weight, duration)

Activates a powerup, with the given weight and (if applicable) duration.

pwrup - string; The powerup to enable or modify. See "About Powerup Strings"
weight - integer; The odds of this powerup appearing.
duration - integer; The duration of the powerup. If set to -1, there is no duration value. (Fair warning, not a widely used setting.)

dxball.setUpdateInterval(msecs)

This function will determine how often onUpdate is called.

msecs - integer; the number of milliseconds in between each call of function onUpdate.

dxball.setZapOnNonBreak(enabled)

This function will determine whether or not the game will autoZap the board in case a player becomes stuck.

enabled - boolean; true by default. If set to false, then existing balls in play become erased. A fresh ball will be placed in the player's paddle.

About Brick Flags

Brick Flags are a binary-style flag system that DX-Ball 2 uses. (Examples; 2 will edit the second bit, while 5 will edit the first and third bits.) For some bizarre reason, these flags do not correctly transfer when Falling Bricks is in effect.

Not much is known about this system, but we do know the bits and (if any/known) their corresponding names:

The first bit is the stickyness bit (string "sticky"). If true, it prevents switches from automatically flipping back after being pressed
The second bit is the invisibility bit. If true, it causes that brick to be invisible. If false, it becomes visible. Invincible bricks rendered invisible this way can neither be revealed, nor do they have to be revealed/damaged in order to finish a level. Any bricks that become invisible mid-level needs to be followed by dxball.drawBricks().

About Brick States

Brick States are a button/switch-specific mechanic. They are used to determine whether a switch is set to its unpressed state ("button_up" / 0), or its pressed state ("button_down" / 1).

About Powerup Strings

In the main menu as of 2.3.0, there are currently 27 different powerups present, plus the "Plasmaball" powerup, which is not visible on the main menu.

Each powerup has its own unique string. The table below shows what the powerup's string is according to DX-Ball 2's LUA code:

Powerup

String

Thru Brick

"through"

Explode

"dynamite"

Fireball

"fireball"

Laser Paddle

"laser"

Grab Paddle

"catch"

Lightning

"lightning"

Zap Bricks

"zap"

Slow Ball

"slow"

Expand (Exploding)

"multiply"

Extra Life*

"life"

Level Warp

"level"

Double Points

"doublescore"

Kill Paddle

"kill"

Shrink Ball

"small"

Fast Ball

"fast"

Super Shrink

"supershrink"

Falling Bricks

"fall"

Megaball

"bigball"

Gravity Ball

"gravityball"

Shrink Paddle

"shrink"

Expand Paddle

"expand"

Split Ball

"split"

Eight Ball

"megaball"

Pause Bricks

"timestop"

Faster Bricks

"timefast"

Slower Bricks

"timeslow"

Reverse Bricks

"timereverse"

Plasmaball

"plasmaball"

*This powerup has a rare chance of appearing after destroying the brick it is added to.