How Modules Work

The official modules all follow the same few rules. Learn them once, and every module will feel familiar. This page also explains the words that the modules' reference pages use.

Using a module

The official modules come with Blitz3D+. To use one, Import it at the top of your program, giving it a short name with As:

Dialect "modern"
Import blitz.tweening As T

Then use that name in front of the module's functions and Types: T.CreateTweens(), T.TweenOptions. A module that needs another imports it itself, so you only Import the ones your program uses.

Each module comes with example programs. Open one from the module's page, run it, and change it to see what happens. To keep your changes, save the example somewhere of your own.

Note

To change a module itself for one game, copy its .bb file and its folder into a modules/blitz folder beside your program's main file. Your program then uses that copy instead of the one that comes with Blitz3D+.

You make it, you delete it

Anything you make with a module's Create or Load function is yours, and you Delete it when you've finished with it:

Local group:T.TweenGroup = T.CreateTweens()
; ...
Delete group

Deleting something also deletes what it holds: deleting a tween group deletes its tweens. Setting a variable to Null, or letting it go out of scope, does not delete anything. Only Delete does.

Some things are only lent to you, such as the view of a slot that the Inventory module gives you to read. Never delete those. The reference pages say which things are lent.

Things a module uses but doesn't own, such as your entities or an item catalog, must last longer than the things using them. Delete a bag before its catalog, and a tween group before the entities it moves.

Options are copied

Many functions take their settings in an options Type. Fill in its fields and pass it. The module copies the settings, so you can change the options and use them again, or delete them straight away. Pass Null instead to use the usual settings.

Local options:T.TweenOptions = New T.TweenOptions
options.easing = T.Ease.BounceOut
T.TweenMove group, ball, 5, 0, 0, 1D, options
Delete options

Nothing happens behind your back

Importing a module does nothing by itself, and no module runs in the background or reads the clock. Modules that change things over time, such as Tweening and States, take the number of seconds that have passed as part of their update call. That puts you in charge: pass zero seconds to pause, or half the real time for slow motion. Only Input Actions reads the keyboard, mouse and gamepads, and only when you ask it to.

A frame of a game that uses modules usually goes:

1. Read the player's input.
2. Decide what happens in the game.
3. Update the modules with the time that has passed.
4. Draw everything and Flip.

When things go wrong

There are two kinds of problem.

Things that can happen in a working game, such as a full bag, no way through a maze or a damaged save file. The function tells you: it returns False, Null, zero or a status. Modules that have a LastError() function also say why. Check, and carry on in whatever way suits your game.

Mistakes in the program, such as a negative number of seconds, a slot that doesn't exist, or using something after deleting it. These stop the program with an error that explains the mistake, so that you find it while you're writing the game, not when someone is playing it.

Blip's tip

Most modules check their arguments carefully, so read the error message when a program stops: it usually says exactly what was wrong.

Words the reference pages use