Tcl API Reference

Welcome to the Tcl API reference guide for the Brick Engine, v5.1.

By default, when you start the brick engine, it loads the file named main.tcl in the current directory and executes it as a tcl script. If you start the brick engine with a command-line argument (e.g. br game.tcl), it loads and executes this file instead.

If you are using the brick engine as a Tcl extension, all you need to do is execute the proper load command for your platform.

The br::graphics command contains routines used to open the graphics display and set general options for the output.

br::graphics modes

Returns a list of the available graphics modes.

br::graphics info

Returns a list of information about the current display mode, consisting of the active display mode, width, and height.

br::graphics open sdl width height fullscreen
br::graphics open accel width height fullscreen zoom-factor

Opens the graphics display. The sdl mode is always available, and accel will be available if the Brick engine has been built with OpenGL-based acceleration. The width and height values determine the size of the output display. The fullscreen flag is a boolean value to indicate whether or not to use the full-screen mode. The accel mode takes an optional pixel multiplier for zoomed display; note that this does not change the display resolution, only its size. There is a maximum width and height set at compile-time, by default 640×480.

br::graphics close 

Closes the active graphics display.

br::graphics window-title title

Sets the title of the display window.

The br::audio command contains routines to open and close the audio output.

br::audio modes 

returns a list of the available audio modes.

br::audio open speaker

Opens the audio output. If the mode is speaker, the audio is sent to the speakers. No other modes are presently available.

br::audio close 

Closes the active audio output.

The br::list command provides a number of routines to create and work with the internal lists used by the brick engine.

br::list create 

Creates a new list and returns its id.

br::list empty list-id

Empties the given list. This does not delete any of the items in the list.

br::list delete list-id

Deletes the given list. This does not delete any of the items in the list.

br::list add list-id item-id

Adds the given item to the list.

br::list prepend list-id item-id

Adds the given item to the head of the list.

br::list shift list-id

Removes the first item from the list and returns it.

br::list pop list-id

Removes the last item from the list and returns it.

br::list remove list-id item-id
br::list remove list-id item-id head
br::list remove list-id item-id tail
br::list remove list-id item-id all

Removes the given item from the list. If the optional third argument is head, then the first matching item is removed. If the optional third argument is tail, then the last matching item is removed. If no third argument is given, or the third argument is all, all matching items are removed.

br::list length list-id

Returns the number of items in the given list.

br::list find list-id item-id

Determines whether the given item is in the given list.

The br::render command contains functions that control general rendering properties, as well as the subcommand that renders the display.

br::render bg-fill mode

mode is a boolean that determines whether or not the background will be filled in with a color before the layer rendering begins.

br::render bg-color r g b

Sets the background fill color to the value given by r, g, b, which have a range from 0-255.

br::render set-overdraw width height

Sets the amount of overdraw applied to the internal render canvas. This does not affect the displayed canvas size. Some sprite frame types (e.g. the pixel-repositioning frame) may depend on graphics data being drawn outside the screen borders for proper composition of the display, and the overdraw instructs the renderer to generate this extra data.

br::render display

Renders the current frame.

br::render to-disk filename

Dumps the current frame in RAW format to the named file.

The br::layer command contains functions for creating and adjusting the brick engine layers. Each layer has a camera position, sprite list, map, and string list, as well as several more options. All of the active layers are drawn in sequence, and the layers can be reordered at any time.

br::layer info 

Returns a list of settings for the specified layer:

	{ sprite-list map string-list visible sorted { camera-x camera-y } }

br::layer add 

Adds a new layer and returns its id. When a layer is added, a sprite list, map, and string list are automatically created.

br::layer swap first-layer-id second-layer-id

Swaps the first layer with the second.

br::layer remove layer-id

Removes the specified layer.

br::layer copy layer-id

Makes a copy of the specified layer, assigning its properties (sprite list, map, etc) to the new layer.

br::layer sprite-list layer-id list-id

Assigns a new sprite list for the given layer.

br::layer map map-id

Assigns a new map to the given layer.

br::layer string-list layer-id list-id

Assigns a new string list for the given layer.

br::layer visible layer-id boolean

Enables or disables the given layer.

br::layer sorted layer-id boolean

Enables or disables z-hint sorting on the given layer.

br::layer view layer-id x1 y1 x2 y2

Sets the layer's viewport, such that the layer will be rendered into the specified box on-screen. when used in conjunction with layer_copy(), a split-screen effect can be made very easily (e.g., make a copy of the playfield layer, set the layer viewports to sit side by side, and adjust the layers' camera positions to center on different players.)

br::layer camera layer-id x y

Moves the layer camera to the given position.

The br::map command has functions that will set the map's size properties, load tiles into the map tile array, and load a map with an array of data.

br::map create 

Creates a new map and returns its id.

br::map empty map-id

Removes map data and all tile associates. This does not, however, free the tiles themselves.

br::map delete map-id

deletes a map and frees all of its associated resources.

br::map size map-id width height

Sets the size of the given map.

br::map tile-size map-id width height

Sets the tile size for use on a given map. All tiles subsequently loaded should match these dimensions. Tiles larger than this size will be clipped, and tiles smaller than this size will have display aligned to the upper-left corner of the tile cell.

br::map tile map-id index tile-id

Loads the given tile into the map's tile index.

br::map set-data map-id map-data

Loads the data array into the given map. The map array is an array of 16-bit (big endian) words, each word containing the index of the tile to display at that position on the map.

br::map set-single map-id x y index

Sets a single element in the map data to the given tile.

br::map animate-tiles map-id index

Animates all map tiles.

br::map reset-tiles map-id

Resets all animated tiles to their initial state.

The br::frame command contains subcommands to create graphics frames, as used by sprites and tiles, and perform a variety of operations on them.

br::frame create none w h
br::frame create rgb width height rgb-data (r g b)
br::frame create displ width height displacement-data
br::frame create convo width height pixel-mask { kernel-width kernel-height { kernel-data .. } divisor offset }
br::frame create br width height rgb-adj-data
br::frame create ct width height adj-data
br::frame create lt width height rgb-adj-data
br::frame create sat width height adj-data
br::frame create lut width height pixel-mask { lookup-table-data .. }

Creates a new graphics frame using the given frame data. The mode determines the frame type:

• none - takes no display data and produces no output. this isn't very useful, except for situations where some unusual collision detection is needed.
• rgb - the data is three-bytes-per-pixel rgb data and an optional chroma key can be given as three additional arguments, r g b. the data is drawn directly onto the render canvas.
• displ - the displacement data is an array of 16-bit (big-endian) x/y coordinate pairs. each coordinate pair represents an offset from the specific pixel in the frame to a location in the underlying image data, from which to retrieve the given pixel.
• convo - the convolution kernel as specified is run on the underlying image data, for each non-zero pixel in the pixel mask.
• br - the data is unsigned char data in rgb format. a pixel component value of 64 is neutral and doesn't alter image brightness. values less than 64 darken the image, and values greater than 64 brighten the image.
• ct - the data is unsigned char data, one char per pixel. a pixel component value of 64 is neutral and leaves the image data unaltered. values less than 64 decrease contrast to the neutral grey, and values greater than 64 increase the contrast of the image data.
• lt - the data is unsigned char data in rgb format. a pixel component value of 128 is neutral and doesn't alter image lightness. values less than 128 darken the image toward black, and values greater than 128 lighten the image toward white.
• sat - the saturation of the underlying image is adjusted by the value in the unsigned char adjustment data. an adjustment value of 128 leaves the image unchanged. a value of 64 desaturates the image, and values between 64 and 128 give varying degrees of desaturation. values less than 64 invert the hue of the image data. values greater than 128 increase the saturation.
• lut - then each pixel in the underlying image data is replaced according to the the pixel value in the lookup table. the lookup table is a list, { { r g b } .. }

br::frame delete frame-id

Deletes the given frame.

br::frame copy frame-id

Makes a copy of the given frame.

br::frame mask frame-id mask-data

Sets the pixel mask for the given frame. The mask is specified as an array of data, one byte per pixel. The dimensions of the mask must match the tile dimensions. Any non-zero values mark the pixel as collidable.

br::frame mask frame-id source-frame-id

Sets the pixel mask for the given frame one of two ways, depending on the source frame. If the source frame has a color key set, then the pixel mask is generated by non-transparent pixels. If the source frame has no transparency set, then each pixel is desaturated and any pixels darker than middle gray are treated as solid. This routine only accepts RGB-type frames.

br::frame slice frame-id x y w h

Copies out a section out of the given RGB frame and returns it as a new frame.

br::frame convert frame-id none 
br::frame convert frame-id convo { kernel-width kernel-height { kernel-data .. } divisor offset }
br::frame convert frame-id br
br::frame convert frame-id ct
br::frame convert frame-id lt
br::frame convert frame-id sat
br::frame convert frame-id lut { lookup-table-data .. }

Converts an RGB frame to almost any other frame type. This routine modifies the frame in-place, so you should make a copy if you plan to use the original again.

br::frame from-disk filename (r g b)

Loads and decompresses the given image file into an RGB frame. This routine is only available if the brick engine has been built with SDL_image support.

br::frame from-disk buffer (r g b)

Loads and decompresses an RGB frame from an image file stored in the given data buffer. This routine is only available if the brick engine has been built with SDL_image support.

The br::tile command contains subcommands to create tiles and set their properties.

br::tile create 

Creates a new tile and returns its id.

br::tile delete tile-id

Deletes the given tile and frees its associated image data.

br::tile anim-type tile-id animation-type

Sets the animation type for the given tile. The animation type must be one of still, fwd, rev, or pp (ping-pong).

br::tile collides tile-id collision-mode

Sets the collision mode for the given tile. The collision mode can be off to disable collision detection for the tile, box to enable bounding-box collision detection, or pixel to enable pixel-accurate collision detection.

br::tile add-frame tile-id frame-id

Loads the already-created frame into the tile.

br::tile add-frame-data tile-id none width height
br::tile add-frame-data tile-id rgb width height rgb-data (r g b)
br::tile add-frame-data tile-id displ width height displacement-data
br::tile add-frame-data tile-id convo width height pixel-mask { kernel-width kernel-height { kernel-data .. } divisor offset }
br::tile add-frame-data tile-id br width height rgb-adj-data
br::tile add-frame-data tile-id ct width height adj-data
br::tile add-frame-data tile-id lt width height rgb-adj-data
br::tile add-frame-data tile-id sat width height adj-data
br::tile add-frame-data tile-id lut width height pixel-mask { lookup-table-data .. }

Loads the given image data into the tile. Please see the documentation for br::frame create has a detailed description of the options, as they are the same for this command.

br::tile pixel-mask tile-id frame-id mask-data

Sets a pixel-accurate collision mask for the specified frame of the tile. The mask is specified as an array of data, one byte per pixel. The dimensions of the mask must match the tile dimensions. Any non-zero value indicates a collidable pixel.

br::tile pixel-mask tile-id frame-id source-frame-id

Sets a pixel-accurate collision mask for the specified frame of the tile from a source frame. If the source frame has a color key set, then the opaque pixels represent the collidable portions of the pixel mask. If the source frame does not have a color key, then each pixel is desaturated and any pixel lighter than medium gray counts as an active pixel.

br::tile animate tile-id

Animates the given tile.

br::tile reset tile-id

Resets the given tile to its initial animation frame.

The br::sprite command has functions to create, clone, and delete sprites, as well as adjust the various sprite properties such as collision mode, position, and the currently-active sprite frame.

br::sprite create 

Creates a new sprite and returns its id.

br::sprite copy sprite-id

Creates a duplicate of the given sprite and returns the new ID.

br::sprite delete sprite-id

Deletes the given sprite.

br::sprite frame sprite-id index

Sets the frame to be displayed for the given sprite.

br::sprite z-hint sprite-id z-value

Sets the suggested render order for the given sprite. Render order for sprites with the same zhint is undefined. If render order is not important, this setting can be ignored. If sprite sorting is disabled (the default) on a given layer, this setting does nothing.

br::sprite collides sprite-id collision-mode

Sets the collision mode for the given sprite to one of: off to disable collision detection for the sprite, box to enable bounding-box collision detection, or pixel to enable pixel-accurate collision detection.

br::sprite bounding-box sprite-id frame-id x1 y1 x2 y2

Sets the bounding box for the given frame of the sprite.

br::sprite pixel-mask sprite-id frame-id mask-data

Sets the pixel-accurate collision detection mask for the given frame to the given pixel mask. The mask is specified as an array of data, one byte per pixel. The dimensions of the mask must match the sprite dimensions. Any non-zero value marks the pixel as collidable.

br::sprite pixel-mask-from sprite-id frame-id mask-data

Sets the pixel-accurate collision mask for the specified frame of the sprite. If the source frame has a color key set, then the opaque pixels represent the collidable portions of the pixel mask. If the source frame does not have a color key, then each pixel is desaturated and any pixel lighter than medium gray counts as an active pixel.

br::sprite position sprite-id x y

Moves the sprite to the given position.

br::sprite velocity sprite-id x y

Sets the velocity of the sprite, used in the collision detection routines.

br::sprite add-frame sprite-id frame-id

Loads the frame into the sprite.

br::sprite add-frame-data sprite-id none width height
br::sprite add-frame-data sprite-id rgb width height rgb-data (r g b)
br::sprite add-frame-data sprite-id displ width height displacement-data
br::sprite add-frame-data sprite-id convo width height pixel-mask { kernel-width kernel-height { kernel-data .. } divisor offset }
br::sprite add-frame-data sprite-id br width height rgb-adj-data
br::sprite add-frame-data sprite-id ct width height adj-data
br::sprite add-frame-data sprite-id lt width height rgb-adj-data
br::sprite add-frame-data sprite-id sat width height adj-data
br::sprite add-frame-data sprite-id lut width height pixel-mask { lookup-table-data .. }

Loads one frame of image data into the given sprite. Please see the documentation for br::frame create has a detailed description of the options, as they are the same for this command.

br::sprite add-subframe sprite-id sprite-frame-id frame-id

Adds the frame to the sprite as a subframe on the given frame index. Subframes are rendered in reverse order, i.e. the last-added subframe is rendered first. This allows for easy compositing of sprite frames together (e.g. a shadow, a lighting effect, etc) into a single sprite. Please note that this does not make a copy of the frame, however, so it may be necessary or desirable to make a copy of the frame before passing it into this routine.

br::sprite load-program sprite-id motion-control-code

The motion control program system is a simple way to give sprites some simple autonomous movement, without interaction from the scripting level. Motion-control programs can also be used to generate simple particle systems, environmental effects, and the like. Motion-control programs aren't intended to be a full-blown replacement for sprite movement. For more information, please see the in-depth guide at the motion control programs page.

This routine loads the given motion-control program into the sprite. The program is a text string containing motion-control instructions, one per line. The following instructions are available:

set var, var/immediate  - store the right-side value in the left-side named var
add var, var/immediate  - add the right-side value to the left-side named var
stc var, var/immediate  - stochastic alter the left-side var with a range of -(var/imm)..var/imm
trk var, id             - copy over the left-side named var contents from another sprite
avg var, id             - average the left-side named var contents with those of another sprite

beq var, var/immediate  - break (immediately exit the program) if equal
bne var, var/immediate  - break if not equal
blt var, var/immediate  - break if less than
bgt var, var/immediate  - break if greater than
bmp id                  - break if there is a collision with the given map
bnm id                  - break if there is a not a collision with the given map
bst var/immediate       - stochastic break, i.e. exit if random value between 0 and imm is zero

copy id                 - make a copy of the sprite and replace the current sprite with the copy for
                          the remainder of the program
ladd id                 - add the sprite to the given list
lrem id                 - remove the sprite from the given list
del                     - delete the sprite

xchgp ptr               - exchange the sprite's motion control program with another sprite's program

sound id                - play the sound

eoc                     - end of code

The var is a named variable, one of the following: xpos, ypos, xvel, yvel, frame, tick. xpos and ypos refer to the sprite's position, and xvel and yvel refer to the sprite's velocity. Immediate values are integers, and id values specify a list, sprite, map, or sound. Argument order matches Intel-style assembly language syntax, i.e. instructions that set or change a variable have the destination given first (set xpos, 4 can be read as xpos = 4)

Every sprite also has its own internal tick counter, and this increments every time the sprite's motion-control program is run.

The br::motion command has routines to execute sprites' motion control programs. The motion control programs page takes an in-depth look at motion control programs.

br::motion single sprite-id

Executes the motion-control program for the given sprite.

br::motion list list-id

Executes the motion-control program for all of the sprites in the given list.

The br::sound command allows you to play sounds, halt the sounds that are currently playing, and adjust sound volume. Note that sounds must be loaded into the brick engine before they can be played.

br::sound load-file filename

Loads a sound into the brick engine from a file on disk and returns a sound ID.

br::sound load-buffer data

Loads a sound into the brick engine from the given memory buffer and returns a sound ID.

br::sound load-raw raw-sound-data

Loads a buffer of raw sound data into the engine and returns a sound ID. The data must match the compile-time sound format. By default, the sound format is 8-bit unsigned data.

br::sound play sound-id (volume)

Plays the named sound. The volume is optional and may range from 0 to 128. Returns the id of the audio channel that is playing the sound, so that the sound can be stopped or have its volume adjusted.

br::sound halt channel-id

Stops the sound playing on the given channel. If the channel is -1, halt all sounds.

br::sound adj-vol channel-id volume

Sets the volume of the given audio channel from 0 to 128. If the channel is -1, sets the volume for all channels.

br::sound adj-pan channel-id panning

Sets the panning of the given audio channel. The panning value ranges from 0 (left speaker only) to 254 (right speaker only). Sound playback is balanced at 127.

The br::song command contains routines that let you play music, pause and resume, and stop the music, as well as adjust music playback volume.

br::song play-file filename (fade-in-delay)

Plays the named song with an optional fade-in delay.

br::song play-buffer song-data (fade-in-delay)

Plays the song contained in the given buffer with an optional fade-in delay.

br::song pause 

Pauses the song.

br::song resume 

Resumes the paused song.

br::song halt (fade-out-delay)

Stops the currently-playing song with an optional fade-out delay.

br::song set-position position

Sets the song playback position.

br::song adj-vol volume

Sets the music playback volume from 0 to 128.

The br::io command has routines for configuring and retrieving input from keyboard, joystick, and mouse.

br::io fetch input-number

returns a list of motion and button-presses thus:

        { { axes .. } { hats .. } { buttons .. } space tab sel pause esc }
 Index       0           1             2           3    4   5    6    7

There are eight inputs from which movement and actions can be requested, numbered 0 through 7. Keys can be assigned to any action (axis, hat, or button) on any input. If joysticks are plugged in, they are assigned to the inputs starting at 0.

Axes have a range from -127 to 127. Key presses will set the axis to the ends of this range, while an analog joystick input may return any value within this range. Up to eight axes are read, either from joystick or from the assigned keys.

Usually, the first two axes will represent horizontal and vertical motion, either from the keyboard or the joystick. Joysticks with more than one analog stick will use additional axes to represent the movement on the additional sticks. By default, the arrow keys are mapped onto axes 0 and 1 on input 0.

Hats represent the four-way directional inputs present on some joysticks. Hat values range from -1 to 1 and are returned as pairs of horizontal and vertical results. Note that a joypad-style controller with just one directional input probably returns its results as a pair of axes rather than a hat. By default, the keys wasd are mapped onto hat 0 of input 0.

Button presses return either 0 or 1. By default, the keys left ctrl, left alt, z, and x are assigned to button presses 0 through 3 on input 0.

There are eight axes, four hats, and twenty buttons available on each input.

The keys space, tab, enter/return (as select), pause, and escape are always included in the results.

br::io mouse input-number

Returns the motion of the mouse along with button clicks in a list:

	{ x y { buttons .. } }

There will rarely be more than one mouse, so in most situations the only useful input number will be 0.

br::io assign input-number axis index direction key-id
br::io assign input-number hat index direction key-id
br::io assign input-number button index key-id

Assigns the key-id to the given action on the given input. Each axis has two directions, left or right, to which a keypress can be assigned. Hats can have a keypress assigned to any of the four directions, up, right, down, or left.

br::io grab mode

Enables or disables the input grab. If the window manager is interfering with the game controls, it can be useful to enable the input grab, but be warned that this makes it almost impossible to recover from a game stuck in an infinite loop.

br::io wait delay

Waits until all input buffers are cleared, and then waits until any activity on any of the inputs is received. If the application-quit button is pressed, this immediately returns -1. The delay value indicates how many times each second the inputs will be checked for activity, so that the processor use can be kept low.

br::io read-key 

Waits for a single keypress and returns the key-id. this is useful for assigning keypresses to inputs. This is not recommended as a general purpose input mechanism!

br::io has-quit

Returns true if the user has pressed the application's close or quit button.

The br::inspect command contains a variety of routines to examine the environment in different ways.

br::inspect adjacent-tiles sprite-id direction map-id

Returns a list of tiles in the given map adjacent to the sprite. The direction is one of nw, n, ne, e, se, s, sw, w.

br::inspect obscured-tiles sprite-id map-id

Returns a list of tiles in the given map covered by the sprite.

br::inspect line-of-sight sprite-id x-offset y-offset distance target-id map-id

Performs a line-of-sight test to determine visibility from the originating sprite to the target sprite within the given map. The x-offset and y-offset offsets determine the point, relative to the sprite's upper left corner, from which the visibility test is performed. These offsets can be negative, performing the visibility test from a point outside the originating sprite's frame. The distance value is the maximum range for the test.

The originating sprite does not need to have collision detection enabled, but the target sprite must have collision detection enabled. If the target sprite has bounding-box collision enabled, the four corners of the bounding box are checked for visibility from the originating sprite. If the target sprite has pixel-accurate collision enabled, the visibility test is performed on the four corners of the pixel mask's bounding edges.

br::inspect in-frame list-id x1 y1 x2 y2

Returns a list of every sprite in the list that falls within the given rectangle.

br::inspect near-point list-id x y dist

Returns a list of every sprite in the list that falls within the specified distance of the point.

br::inspect layer-vis layer-id (x-pad y-pad)

Returns a list of every sprite on the given layer that is currently visible. If x-pad and y-pad values are given, sprites within this number of pixels of the window boundary are included.

The br::collision command has the routines used to detect collisions among sprites and between maps and sprites.

br::collision map sprite-id map-id (slip)

Checks the given sprite for collision against the given map. The optional slip argument indicates that, when a collision occurs, the sprite will be adjusted by the given number of one-pixel increments to continue motion. The slip factor allows sprites to travel near the corners of maps without stopping on all single-pixel collisions. The result is a list:

	{ mode x-stop y-stop x-go y-go }

Mode is -1 to indicate that the sprite and map were colliding before motion began, 0 to indicate that no collision has occurred, or 1 to indicate that collision occurred during motion. The stop values indicate the pixel distance before the sprite hits the map, while the go is the distance in each direction that the sprite may travel after collision.

br::collision sprites sprite-id list-id

Tests the given sprite for collisions with all collidable members of the given sprite list. Returns a list which itself contains sub-lists, arranged thus:

	{ { mode target x-hit y-hit x-dist y-dist } .. }

Target is a pointer to a sprite that has had a collision event. Mode is -1 to indicate that the sprites were colliding before motion began or 1 to indicate that collision occurred during motion. The hit values show the direction in which the collision took place. The dist values show how far the sprite traveled before it hit the target.

The br::font command contains routines to load fonts into the text renderer.

br::font add font-name char-width char-height rgb-data (r g b)

Loads the bitmap data for a new font with the given name. The rgb data is an array of three-bytes-per-pixel data, with each letter in the font having the specified width and height. The font must be 128 character long, though any letters may be left blank. If optional color components are given, they will be used as a color key.

br::font from-disk font-name filename (r g b)

Adds a new font named font-name from the compressed image filename. If optional color components are given, they will be used as a color key. The font image is assumed to be 128 characters wide. This routine is only available if the brick engine has been built with SDL_image support.

br::font from-buffer font-name buffer (r g b)

Adds a new font named name from the data buffer which contain a compressed image file. If optional color components are given, they will be used as a color key. The font image is assumed to be 128 characters wide. This routine is only available if the brick engine has been built with SDL_image support.

The br::string command contains routines to create and display text strings. Note that strings are positioned absolutely on the display canvas and do not move when the camera moves.

br::string create 

Creates a new string and returns its id.

br::string delete string-id

Deletes the given text string.

br::string font string-id font-name

Sets the font for the given string to the so-named font.

br::string position string-id x y

Adjusts the position of the given string.

br::string text string-id text

Sets the given string to the given text. Respects the ascii control characters for tab stop, new line, carriage return.

A useful routine to hold the game's frame rate steady.

br::delay fps

If the time between calls to delay is less than necessary (i.e. the game would otherwise run too fast) to maintain the given fps rate, then the routine will delay until enough time has passed. If the game is running too slowly to maintain the requested fps rate, delay will return the number of frames that must be skipped to maintain speed.