Hacking Beans

This page shows you how to make some fun changes to the Beans source code. This allows you a glimpse of how the code works and shows how easy it is to make games in TNT Basic.

To do any of these hacks you will need to have downloaded both TNT Basic and the Beans source code.

Beans Homepage


First, open the Beans source code in Hieroglyph, you may want to make a backup copy of Beans in case you make any mistakes! Then follow one of the following guides:

  1. Change the speed of the game (Easy)
  2. Add a 6th Bean colour (Easy)
  3. Add a new backdrop (Intermediate)
  4. Make the keys customisable (Advanced)

Change the Speed of the Game (Easy)

Like many games, Beans runs a loop called the main game loop while it is being played. This loop is repeated again and again while the game in playing. One execution of the loop corresponds to one frame being drawn on the screen.

We want Beans to play faster, so we can either move the falling Beans by a greater distance each frame, or we can draw the frames at a faster rate.

Drawing the frames at a faster rate is not a guaranteed way of speeding the game up however, because if the computer cannot draw the frames any faster (because it is already working flat out) then it won't work. However, if we assume that the computer has some speed to spare we can up the frame using the set framerate command.

First locate the line:

graphics mode 640,480

It should be around line 153 in the Beans source code.

After this line enter the following:

set framerate max
vbl sync off

Run Beans. Beans is now running as fast as your computer can go. If you have a slow computer this won't have made any difference, but if you have a fast computer you probably can't even play the game now! If you choose "Show Frame Rate" from the TNT Basic menu you can see the difference in the frame rate in a little box in the corner of your screen.

Why does this work?

As different computers run at different speeds, there has to be some way for TNT Basic to control how fast the game plays, so that it can be slowed down on faster computers. The draw frame command will only draw frames to screen within a maximum speed specified by the frame rate. If the framerate limiter is disabled by setting the framerate to the maximum possible, the draw frame command works as fast as possible and hence you get the maximum possible framerate available on the current computer - well, this is not entirely true because of something called vbl syncing.

TNT Basic tries to make animation as smooth as possible by using a technique called VBL syncing. VBL is short for vertical blank, this is a term applied to monitors. In short, by turning off VBL syncing with the vbl sync off command, you can get higher framerates, but at the cost of more flickery animation.

Fast paced action games want speed speed speed and don't care about the occasional flicker in the animation because it's all moving so quick you can't really tell anyway. With slower games like Beans, this flicker can be quite pronounced however.

But, the aim here is to get maximum speed, so we disable vbl syncing with the vbl sync off command.

That's it, Beans is now running as fast as your computer can manage!

Working Harder Instead of Faster

Making the game run faster by drawing the frames faster is all well and good, but sometimes the game cannot run any faster. When this is the case you have to make things appear to be faster by moving/animating them by larger steps each frame.

Here we will make the falling Beans fall at triple speed. Locate the line:

global float	kInitialBeanFallSpeed=0.8

It should be around line 65 in the Beans source code. This is the speed that the Beans fall at. It reads move the Beans by 0.8 pixels per frame. Change it to 3.0.

Run Beans, you will now find the Beans falling much faster, at 3 pixels per frame to be precise.

Add a 6th Bean Colour (Easy)

There are 5 different coloured Beans normally: blue, green, purple, red and yellow. However, Beans loads just one set of graphics for the Beans and then recolours it according to the colour of Bean needed. You can see the Bean graphics in Picture 137. Picture 138 contains the mask used to colourise the image to the different colours.

To add a new colour to Beans all we need to do is generate another Bean in a different colour by changing the code. Do the following, locate the line:

global int		kNumBeanColours=5

It should be around line 19. This defines the number of different Bean colours that can be selected when the Beans begin to fall. Change it to a 6 so we have an extra colour to choose from.

Now we need to define the colour. Go to the bottom of the procedure "LoadBeanGraphics" (around line 1290). You should see a collection of data statements like the following:

data make colour(24,74,49)  ' background colour for sprite mask
data make colour(0,189,0)   ' green bean (default - others are formed by recolouring this)
data make colour(231,8,239) ' purple
data make colour(0,0,189)   ' blue
data make colour(189,0,0)   ' red
data make colour(189,189,0) ' yellow

Each of these data statments is an integer, the result of a make colour function. The make colour function takes three arguments defining the strength of red, green and blue in the resultant colour. We're going to add another colour here. After the last data statement (before the "end proc") line, enter the following:

data make colour(240,240,240)	' white

Now run Beans, you will find that now white Beans appear as well as the existing 5 colours! You can enter any number of new Bean colours you wish in this way.

Add a New Backdrop (Intermediate)

You can replace any of the Beans backdrops by importing a picture over the top of an existing backdrop. Beans uses pictures 132 to 135 as its backdrops. We are going to replace the purple swirls used as a backdrop on levels 1 to 3 with another picture.

To try this do the following, find a picture on your hard disk, you can always use some of Apple's desktop pictures if can't find one. Open the picture up in an image editing utility and resize it to 640x480 pixels in 16-bit colour. (GraphicConverter is a good shareware utility that can do this task easily). Save the picture out to disk, you might want to save it as a compressed JPEG so that it doesn't make Beans too big.

Back in Hieroglyph, goto the Graphics section of Beans and select the pictures column on the left. Choose "Create new Picture" from the "Resource" menu, enter a resource id of 132 and click OK. Select "Overwrite" when asked if you wish to replace the exiting picture. Choose your picture in the file dialog, select OK and then run Beans.

You should find that the backdrop of the first three levels has been changed! If not, make sure you have imported your picture as resource id 132.

Make the Keys Customisable (Advanced)

This tutorial is forthcoming.