Gambas Examples

"Gambas Examples" is a Piga Software project to help newcomers learn the Gambas language.

These examples are largely concerned with game development.

You may use the following example codes on this page anyway you want - they are public domain.

How To Add Comments
Comments are invaluable ways to keep code organized and help other programmers. To add them to Gambas code you need to start them with an "'":

'This is a comment. PUBLIC SUB Form_Open 'The above and bellow lines are actual code. END

Hello World
To create venerable "Hello World" application add this code to the start up form's .class file:

PUBLIC SUB Form_Open Message("Hello World!") END

Linking Two Forms
To make one form ("FOne") link to another form ("FTwo") with a button ("BLink") add this to "FOne"'s .class file:

PUBLIC SUB BLink_MouseDown FTwo.Show END

To close a form, try this:

FTwo.Close

Label Text Manipulation
To make a label ("LText") on a form ("FOne") change it's text with a click of a button ("BChange") add this to "FOne"'s .class file:

PUBLIC SUB BLink_MouseDown LText.text = "The Label now has different text" END

Object Picture Manipulation
Make a picture box ("PicBox") on a form as well as a button ("BChange"), and have a picture ("NewImage.png") in your project's directory.

PUBLIC SUB BChange_MouseDown PicBox.Picture = Picture["NewImage.png"] END

Form Colour Manipulation
To change the background colour of a form, create a button called "BChange" and add this code:

PUBLIC SUB BChange_MouseDown Form.BackColor = &H000000& END

This changes the from's background colour to black. This works to change any object's hexadecimal colour setting.

Common Hexadecimal Colours
Black: &H000000& White: &HFFFFFF& Red: &HFF0000& Blue: &H0000FF& Purple: &H55007F& Green: &H00AA00& Yellow: &HFFFF00& Orange: &HFF5500& Pink: &HFF557F& Grey: &H787878& Light Blue: &H00AAFF& Light Green: &H55FF00& Light Grey: &HACACAC&

Probability Example
You can use probability to make Gambas randomly display a message box. If you add this code to a form's .class file, it will make it so that if you click a button ("BDice") it will randomly pick a message box:

PUBLIC Dice AS Integer PUBLIC SUB BDice_Click RANDOMIZE Dice = Int(Rnd(0, 2)) IF Dice = "1" THEN Message("You rolled a One") END IF IF Dice = "2" THEN Message("You rolled a Two") END IF END

Adding to a Numeric String
On a form ("FOne") have a label or other object ("LNumber") that has a .text variable and set it to "1" and have a button ("BAdd").

PUBLIC SUB BAdd_MouseDown LNumber.text = LNumber.text + "1" END

Using Terminal Commands
A very useful ability of Gambas is its ability to link directly into the command line of your Unix-like operating system, which allows you to load programs, do system and file management and even create front-ends for applications. To access the terminal simply use the shell command:

SHELL ("insert command here")

Note that many terminal related tasks, such as shutdown, program installation and most administration requires the program to be run in root or as super-user.

Moving an Object
On a form ("FOne") create an object (in this case a picture box: "PBPlayer") and four buttons: "BLeft", "BRight", "BUp", "BDown".

PUBLIC SUB BLeft_MouseDown PBPlayer.X = PBPlayer.X - "32" END PUBLIC SUB BRight_MouseDown PBPlayer.X = PBPlayer.X + "32" END PUBLIC SUB BUp_MouseDown PBPlayer.Y = PBPlayer.Y - "32" END PUBLIC SUB BDown_MouseDown PBPlayer.Y = PBPlayer.Y + "32" END

Alternately, you can move an object with the keyboard's arrow keys:

PUBLIC SUB Form_Keypress

SELECT Key.Code

CASE Key.Left

PBPlayer.X = PBPlayer.X - "32"

CASE Key.Right

PBPlayer.X = PBPlayer.X + "32"

CASE Key.Up

PBPlayer.Y = PBPlayer.Y - "32"

CASE Key.Down

PBPlayer.Y = PBPlayer.Y + "32"

END SELECT

END

Collecting an Object
Expand on Moving an Object and add another object ("PBCollectible"). In this basis, both must fit an even grid (32x32 or 48x48 recommended) and as such their dimensions should fit these parameters as well as their placement must be even to grid. Create a timer ("TmrCollisions") and add this code, set it to be enabled and a delay of "1".

PUBLIC SUB TmrCollisions_Timer IF PBCollectible.x = PBPlayer.x and PBCollectible.y = PBPlayer.y THEN PBCollectible.x = "-9000" Message("You have collected this object!") END IF END

Align to Grid
This code aligns an object ("PBObject") to a given grid, (in this case 48x48). This is needed to allow grid-based collisions to work.

PBObject.x = (Round (PBObject.x/"48"))*"48"

PBObject.y = (Round (PBObject.y/"48"))*"48"

This can also be used to move an object to the grid point nearest your cursor:

PBObject.X = (Round (Mouse.x/"48"))*"48"

PBObject.y = (Round (Mouse.y/"48"))*"48"

Changing a Border
You can change a given object's borders (in this case between plain and none) by using this code.

First put this on the very top of your class file:

CONST None AS Integer = 0 CONST Plain AS Integer = 1

Then you can use this to change your object's ("PBObject") border:

PBObject.Border = "1"

Or:

PBObject.Border = "0"

Animation
Animation is a somewhat more difficult in Gambas then in some other tools. You can not make an animated image file, like say a GIF or SVG, and then just import it into a picture box or load it into a drawing area and have the animation play. Instead you must specify slide transitions and timing in code, like so:

PUBLIC SUB Constants_Timer IF Object = Picture["Animation--4.png"] THEN

Object = Picture["Animation-5.png"]

END IF

IF Object = Picture["Animation-3.png"] THEN

Object = Picture["Animation-4.png"]

END IF

IF Object = Picture["Animation-2.png"] THEN

Object = Picture["Animation-3.png"]

END IF

IF Object = Picture["Animation-1.png"] THEN

Object = Picture["Animation-2.png"]

END IF END

While this is a bit complicated, it does give you more control over the animation. Especially if you adjust the timer's delay within the IF blocks. Note the descending order for the IF blocks, this ordering is vital to getting the animation running.

Using Tags
Tags are a useful object property in that they have no function in rendering it. They are used to tag in a new function. For example if you are building a strategy game you would want a building to be labelled "Not-Built" (eg, a worker needs to finish it) or "Built" (once the building is fully functional). To do this simply write this out:

Building.Tag = "Not-Built"

This can then be used as a property for this object for uses such as:

IF Building.Tag = "Not-Built" THEN

It is also useful for direction tracking, by using a tag to say "Left" or "Right" it can make it easier to adapt conditions to an object's direction by using this property to signify it.

Playing Sounds and Music
The Simple DirectMedia Layer (SDL) can be used to add sounds and music to your project. First you first must make sure it is set to use the Gambas SDL sound component. You can do this by clicking the "Project" menu, then clicking on "Properties." A window will appear showing various properties of your Gambas project. To add components, click the "Components" tab. Scroll through the list that appears until you find one called "gb.sdl.sound". Click the check-box beside the text and click the "OK" button. Now place a sound file ("AudioFile.ogg") into your project's directory. Finally, add the code below to the top of your start-up form's class file. When you start your project you should hear a sound.

PUBLIC AudioFile AS Sound PUBLIC SUB Form_Open AudioFile = NEW Sound("audiofile.ogg") AudioFile.Play END

The music channel is another useful function of the Gambas sound component. Using it you not only get to play a sound, but specify how often you want it to repeat and or when to pause or stop. This is useful for ambient sounds in games just as much as it is useful for music. Sadly there can only be one user of the music channel at one time, unlike the sound channel where you can have as many sounds as you want playing. However, it should be noted that you do not have to define anything for this channel unlike the sound equivalent. To use this channel, simply input this code and add a music or ambient sound file ("Music.ogg") to your project directory.

Music.Load("Music.ogg") Music.Play(-1)

Note that "-1" is infinite loop, to specify it to repeat five times for example simply replace it with "5".

Scrolling
Scrolling is a useful way to make your game world or GUI larger than the screen. In order to allow you to have a scene the user can scroll through you need to put your objects into a container ("World") such as a panel if you are using picture boxes, labels or buttons for your interface or game. If you are using a drawing area to render your world then you can just move the drawing area itself. Make it so the container is as large as the environment you wish the user to scroll through - do not worry if it goes beyond the form's borders as that is the effect we are looking for. Once everything is in the given container you can put in this code to allow you to scroll through it all with the container:

PUBLIC SUB Form_Keypress SELECT Key.Code CASE Key.Left World.X = World.X + "48" CASE Key.Right World.X = World.X - "48" CASE Key.Down World.Y = World.Y - "48" CASE Key.Up  World.Y = World.Y + "48" END SELECT END

This will allow the user to scroll around the container using the keyboard but you can move it around infinitely. If you wish to make it so you can't move it beyond certain parameters you will have to add the following code to you keyboard function.

Note: you will have to find, based on your own container, where the * Last Point Before Going Too Far * is. The "<" or ">" portions of the IFs are there in case it is not properly aligned to grid as it prevents the user from going too far past the end-points They are not strictly necessary. You can ensure that it is placed to grid yourself in the IDE or by using the align to grid code mentioned earlier.

CASE Key.Left IF World.X = "0" OR World.X < "0" THEN ELSE World.X = World.X + "48" END IF  CASE Key.Right IF World.X = "* Last Point Before Going Too Far *" OR World.X > "* Last Point Before Going Too Far *" THEN ELSE World.X = World.X - "48" END IF  CASE Key.Down IF World.Y = "* Last Point Before Going Too Far *" OR World.Y > "* Last Point Before Going Too Far *" THEN ELSE World.Y = World.Y - "48" END IF  CASE Key.Up   IF World.Y = "0" OR World.Y < "0" THEN ELSE World.Y = World.Y + "48" END IF

To see this technique in action you can download the Lamp Refugee technical demo.

Gambler
Gambler Screenshot

Gambler is a probability example built with Gambas 2.7.0, and tested on Fedora 9 GNU/Linux. It allows you to gamble with virtual money (represented by a variable) using probability to simulate the throw of a die. Aspiring Gambas programmers should find this example useful in learning how to use probability and variable manipulation. The example is released Free Software under version three of the GNU General Public License.


 * Download Example

Walk About
Walk About Screenshot

Walk About is a movement example built with Gambas 2.7.0, and tested on Fedora 9 GNU/Linux. It allows you to move a player (represented by picture box) around, as well as being blocked by walls. Aspiring Gambas programmers should find this example useful in learning how to use coordinates for object movement and control. The example is released Free Software under version three of the GNU General Public License.


 * Download Example

String Fun
String Fun is a command line example built with Gambas 2.7.0, and tested on Fedora 9 GNU/Linux. It allows you to manipulate Strings to create a humorous paragraph. Aspiring Gambas programmers should find this example useful in learning how to manipulate strings and create simple command line programs. The example is released Free Software under version three of the GNU General Public License.


 * Download Example

Mouse Movement
Terrain Model Shot

A tech demo created for the Gambas Genie engine project tested in Fedora 8 GNU/Linux. It shows you how to make a selectable object, and how to make it so you can drop a movement point with your mouse which the object will move too. The example is released Free Software under version three of the GNU General Public License.


 * Download Example

Terrain Model
Isometric Projection Shot

A newer technical demo for Gambas Genie tested on Fedora 15 that demonstrates a terrain model utilizing either tiling and texturing. A must see for aspiring Gambas graphics programmers, this demo allows the placement, modification, resizing stacking of graphics on top of a Gambas drawing area. Much to learn here, as it shows the basics of drawing and the controlling of them afterwards.


 * Download Example, White Island Software entry

Isometric Projection
Another technical demo for Gambas Genie, released on August 7, 2013 and tested on Fedora 17, that demonstrates a isometric projection, with rendering, movement, collisions and a randomly positioned object. Can be used as an initial basis for a number of isometric games. Written in Gambas 3.4.1; the example is released Free Software under version three of the GNU General Public License.


 * Download Example, White Island Software entry

Random
A demo that places down two objects randomly onto a small grid when the player clicks the mouse, regualted in such a way that an object can not land on a grey square or the other object. In such an instance, it recalcuates.


 * Download Example

Piga's Pumpkin Carving
PPC Screenshot

Although not exactly a technical demo, it is still a fairly small program, though expanded notably in later versions. It will teach you the basics about using drawing areas, which support a wide variety of graphics features, including transparency! With version 2.0's inclusion of the "Creepy Jukebox" it is also a good guide to using the music channel and it also features global variables; version 2.5 also provides a working model for using shell commands. The example is Free Software under the GNU General Public License version 3 though the music is under the Creative Commons Attribution 3.0 Unported license (not share-alike/copyleft license meaning it can be license changed).


 * Main Article

PTDH Screenshot

Gambas Arcade Engine
Similar to Carving the games using this engine are somewhat larger then a code demo but still highly instructive and small enough to be easily examined. Studying them will teach you the basics of using drawing areas but more along the lines of a game instead of a graphics program. It will show you how to define game objects, render them and manipulate them in real time, use them in cut-scenes, as well as game logic functions such as grid-based collisions, score, projectiles, artificial intelligence, gravity and more! In addition each game comes with score board code which will teach you how to save and load information from text files. The article on the engine provides more complete technical information.


 * Main Article

DONKEY.GB

DONKEY.GB
Donkey (DONKEY.GB) is a modern free software GNU/Linux remake of the classic BASIC computer game Donkey. Written in Gambas, it is based on the original by Bill Gates and Neil Konzen that was created to demonstrate the power of GW-BASIC for the original IBM PC. It was also ported to QBasic and a first-person version was later made for Visual Basic .Net. As an example, it helps show basic grid-based collisions, computer-controlled movement patterns, keyboard control, treadmill-type scrolling and the basics of a Gambas "picture box"-type graphics engine.


 * Download Example, Gambas Forum Thread