matibee.mbmframework:

mbmframework (matibee's BlitzMax Framework)

The mbmframework provides a collection of fundamental types and utility functions to take the tedium out of coding cross-platform, multilingual games in BlitzMax. Some of the types may be used independently of the framework but most are part of the Object Oriented AppModule base type.

By deriving your own "Application Modules" from this type it's possible to code a complete game including;

Splash screen intros

Game menus

Options screens

Highscore management

Player account management

Loading screens

Exit nag screens

and much, much more with very little code other than your game specific stuff.

System	Description
Application flow	Automatic state changes between AppModules. AppModule fundamentals Flow logic.
Profiling	Profiling and performance testing your code.
Animators	Animation effects
Sprites	Image handling Sprite script file Bitmap animation format
Resources	Resource management Accessing resources Platform specific resources Loading progress Sprite resources Sound and Music resources Constant values GUI Windows
GUI	Graphical User Interface Initialising the GUI Loading GUI Windows GUI Controls Buttons, Sliders and Checkboxes Input lines Images
Localisation	A method of loading string literals and filenames from a language specific locale file.
INI settings	Methods for storing volatile values Setting Values Retrieving Values Managing encryption
Player Profiles	Managing player profiles
High scores	Saving and maintaining highscore lists
Particles	Particle system

Application flow

Application flow is achieved and managed by deriving and registering an AppModule type for each part of the application you require.

To begin an application at least one AppModule must be created and registered.
Resources are automatically loaded and unloaded as control passes from one AppModule to another. See: Start, EndModule, LoadResources and UnloadResources

AppModule Fundamentals

The simplest use of an AppModule would be to:

Derive your own type from AppModule with an Update function and a Draw function

Init the application

Run the application

SuperStrict 
Import matibee.mbmframework

' derive a simple type..
Type myDemo Extends AppModule
	
	Field x:Float, y:Float 	' some simple demo parameters
	Field xdir:Float = 0.44
	Field ydir:Float = 0.25
	
	' A derived update function, called once per frame with the delta time value
	Method Update( timeMS:Int )
		x :+ xdir * timeMS ' move our demo ball
		y :+ ydir * timeMS
		If ( x >= 779 Or x <= 0 ) xdir :* -1.0
		If ( y >= 579 Or y <= 0 ) ydir :* -1.0
		
		Super.Update( timeMS ) ' update the parent type
		
		' check if the AppModule needs to end
		If ( KeyHit( KEY_ESCAPE ) ) EndModule()
	End Method 
	
	' A derived draw method, no need to Cls or flip
	Method Draw( sync:Int )
		DrawText( "Press escape to exit", 0, 0 )
		DrawOval( x, y, 20, 20 )		
		Super.Draw( sync )
	End Method 
	
End Type 

' Initialise the app
InitApp(800,600,0)

' create a new demo instance
Local demo:myDemo = New myDemo

' initialise the instance as a "APP_GAME" AppModule
demo.Initialise( "", AppModule.APP_GAME )

' run the app
RunApp()

Flow logic

When the application runs it starts with the first existing AppModule, in this order: Intro (APP_INTRO), Main Menu (APP_MAINMENU), Game (APP_GAME), Outro (APP_OUTRO).

When an AppModule ends it moves onto the next with some simple control required when moving to and from a GAME AppModule:

When the Main Menu ends, it checks to see if a Game is available and if so, moves control it

If no game is available it moves to the Outro or the application ends

When the Game ends it checks to see if a Main Menu exists, and if it does, returns to it

This means:

To start a new game from a main menu, register a Game AppModule then End the Main Menu AppModule

To quit from the Main Menu ensure no Game AppModule exists

To "Quit to system" from a Game AppModule and avoid returning to the Main Menu AppModule, Destroy the Main Menu AppModule before Ending the Game AppModule

Normally an application will define an Intro, Loading Screen and Main Menu before calling RunApp(). Defining and registering an AppModule won't cause it to load any resources or take up any processing power because resources are only loaded when the AppModule is started.

During testing you may wish to skip the Intro and maybe even the Main Menu so it's common to test the Intro once or twice and then wrap it inside ?Debug/? optional compilation tags.

In cases where you want to skip the Main Menu as well, consider using a command line argument that contains the level number you wish to play. This way your code can detect the argument and skip the initialising of the Intro and Main Menu altogether and jump straight into a level.

Profiling

This code timing system will report how long any given piece of code takes to execute and can be used to find bottlenecks in your game code and for performance tuning.

First of all, profiling has to be enabled. This is done with a single call to EnableProfiling with an optional filename for the output log. The output is also sent to the Debuglog but that only works in Debug builds.

Then we can encase sections of code with matching EnterProfileSection and ExitProfileSection function calls. e.g.

Method UpdateAI()
  EnterProfileSection( "UpdateAI" ) ' Names must be unique and are case sensitive!

  ' do all your AI updates..


  ExitProfileSection( "UpdateAI" )
End Method

When the application ends it will dump the profiling data to the debug log and/or the specified output file. For the example above, we might see..

************ BEGIN PROFILE INFORMATION ************
Profile name    : UpdateAI
Number of calls : 19430
Slowest time    : 13 ms
Quickest time   : 2 ms
Average time    : 7 ms
---------------------------------------------------
************* END PROFILE INFORMATION *************

Profiling will work in debug and release builds. If it's not enabled it takes a very short code path for performance (it just checks one integer value and returns).

See EnableProfiling, DisableProfiling, EnterProfileSection, ExitProfileSection

Animators

An animator is a simple animation type that controls a single value over time. Animators can be defined in a text file or created in code, and they are used by GUI windows and sprites to provide transition effects, scaling, rotation and bouncing etc.

It's inefficient to try and provide bitmap animation frames all the time, and these animators can bring 2d images to life quite cheaply and with pleasing results.

See Animator type

Sprites

The sprite system provides a simple way to manage many instances of the same static or animated sprite. Instances of animated sprites have their own delta time so they're not all tied together playing the same animation frames at the same time.

Animation is handled in two ways;

A list of seperate frames to control bitmap animation

A script file of Animators
You can use either method, or combine them both. Bitmap animation is good for sprite walking animations etc, and the scripted Animators are perfect for bouncy scaling effects and rotations.

Sprite script file

Every time you load an image (or the system loads an image via a resource script), it looks for a corresponding .txt file. In that file you may specify the image handle position, blendmode and Animator scripts..

xhandle=16
yhandle=16
blendtype=1
<r>
data0=0
data1=90
data2=360
script=0
playonce=0
</r>

That will cause the image to rotate around the handle indefinitely and be drawn LIGHTBLENDED. All supported script tags are:

<x> X position

<y> Y position

<r> Rotation

<a> Alpha

<s> Overall scaling effects

<xs> X scale

<ys> Y scale

You may use one script for each attribute but you cannot use an overall scale animator with individual X and Y scale animators.

blendtype can be zero (default) for ALPHABLEND, or 1 for LIGHTBLEND

Bitmap animation format

The bitmap animations support a .CSV (comma seperated values) text file, as export by GraphicsGale but it's a simple format and is easily hand written.

"Name","Delay(1/60)"
"Frame1","2"
"Frame2","2"
"Frame3","3"
"Frame4","3"
"Frame5","3"
"Frame6","4"
"Frame7","4"
"Frame8","999999"

Upon loading this .CSV file, the system will expect bitmaps called "Framen.ext" (.bmp, .jpg, .tga or .png) to be in the same directory. The advantage to this system is that if we want to play the same frames in a different order we can create and load a new .CSV but internally the bitmaps are reference counted and only loaded once.

Resources

Each AppModule may have a list of resources that it needs to load, defined as a resource script. Here we can define GUI Windows, Sprites, Sounds, Songs and Constant values (typically constant numbers such as run_speed or message strings). The advantage of defining resources in this resource script is that it allows testers and game designers, and even you the coder, the chance to easily play around with different assets and values without needing to recompile or ensuring that you've correctly replaced the original asset. Any resource defined in this file is accessed in code by it's Name.

' A simple resource script (data\game.txt) ' ---------------------------------------- ' a gui window.. WINDOW forms\hud.txt

' a sound effect.. SOUND Boom = sounds\boom.wav

' a sprite.. SPRITE Player = images\player.png

' constants.. CONST speed = 2.4 CONST MaxLevels = 100 CONST FailMessage = You suck!

' a particle emitter EMITTER sparks = data\sparks.txt

' a seperate file with more resources in.. RESOURCE data\LevelNames.txt

NOTES
Comment lines and blank lines are allowed, but comments are not allowed at the end of definition lines.
Names are always case insensitive, values are not!
Whitespace is not preserved around Names or Values
The GUI Window doesn't need a name because it's specified in the GUI form file.
The RESOURCE tag allows common resources to be shared between AppModules. eg. The main menu and the game might need access to the list of level names, but instead of defining them twice, we can define them on their own in a seperate file;

' data\LevelNames.txt
' -------------------
CONST Level01 = In the cracks between your toes!
CONST Level02 = Just above the ankle!
CONST Level03 = Right on the shin!

Accessing resources

Accessing resources by name is fairly foolproof. The names are not case sensitive, and during DEBUG builds, trying to access a resource that doesn't exist will fail an assert. This way errors are easily found and corrected.

See GetSprite, GetSound, ConstString, ConstInt, ConstFloat, GetEmitter, PlaySoundByName

Platform specific resources

Resource scripts may use $$Win, $$Mac or $$Linux prefixes to adjust how the resource is treated on the target platform. For example, if we want to display a system logo depending on the platform, we could define one SPRITE called Logo, for each platform:

' Logo defined for each platform
$$Win SPRITE Logo = images\win.png
$$Mac SPRITE Logo = images\apple.png
$$Linux SPRITE Logo = images\tux.png

This is also useful for registration URL's where each product might have a unique product code and order page.

Loading Progress

It's possible to automatically generate loading progress information, which gives accurate feedback to the user. The resource scripts are automatically timed and it's possible to access the same timing system for your own code.

Loading times are monitored in DEBUG builds, and reported back to the user in RELEASE builds. The timings are stored in a text file with a .load extension that corresponds to the script.txt file (eg script.txt.load). Each resource creation (apart from constants which load almost instantaneously) is timed in order to arrive at set of percentage values that should end up at (or very close to) 100%.

You can use the same system to report loading progress for your own custom resources or procedurally generated content.

' The LoadResources function gives us access to a loadingProfile type
' so a user derived method can use it like so...
Method LoadResources:loadingProfile()
	' call the Super method which gives us a current loadingProfile
	local lp:loadingProfile = Super.LoadResources()

	' do some custom loading, or intensive content generation..
	GenerateAIVisibiltyNodes()
	lp.Update() ' tick the loading progress
	
	' do some more stuff
	MakeSynthSounds()
	lp.Update() ' tick the loading progress again
	
	lp.Close() ' it's nice to do this (and it's more accurate), but it's not necessary
End Method

Recording and displaying load times is simply down to the way the loadingProfile.Update() function is implemented between DEBUG and RELEASE builds.

Sprite resources

You can deal with sprite resources in one of two ways:

Create local (multiple) instances of it and update and draw those instances

Draw and update the resource directly

Sound and Music resources

Sounds are simply played on demand. You may use the sound name to retrieve a TSound handle, or simple play the sound by it's resource name everytime you need it. You can override it's volume with the play command too.

Music files are loaded into a global music manager and played by their resource name. It's possible to fade out a song and queue another to start when the fading is complete, all in one command. It's also possible to leave songs in RAM even when an AppModule ends, avoiding the loading time the next time around.

See

Constant values

Constants are so called, because they are read-only to the application. Accessed by name, they are ultimately string values loaded from the resource script file but there are short-cut functions to cast them to Integers and Floats.

See

GUI Windows

All the bitmaps and sounds used by your GUI windows are released when the AppModule ends (provided they were unique, as they are reference counted and shared across the whole application). You may Show and Hide GUI windows and access their controls, all by refering to the GUI Windows name.

See

GUI

The GUI is very simple to use, but slightly more complicated to set up. This GUI has been implemented to serve relatively simple games and while it can be very flash and easy to use, there isn't (and it's unlikely there ever will be) a large collection of controls available. If you want complex controls like multi-column list boxes or a file dialogs, please consider using a 3rd party GUI module or be prepared to code some of your own functionality. However, if you want fancy buttons, check boxes, sliders and input lines that look and behave as a sleek GAME UI should, with minimal code to handle them, then this system is for you.

Initialising the GUI

First the GUI must be initialised via a text file that will define;

The mouse pointer

The bitmap fonts

Control templates called Clones

<fonts>
Media/fonts/neuropol18.fnt
</fonts>
<clone>
name=fancy
normal=Media/gui/glowbutton/normal.csv
over=Media/gui/glowbutton/over.csv
down=Media/gui/glowbutton/down.tga
soundclick=Media/sounds/54405__KorgMS2000B__Button_Click.wav
width=160
height=38
font=neuropol18.fnt
captioncolor=255,255,255,160
captionhjust=1
captionvjust=2
</clone>

See LoadGUI

Loading GUI Windows

Next we need to define our GUI Windows from their own text files. The file will specify the name of the window, a collection of controls and if required, in and out transition animations. These window files can be loaded manually, or loaded automatically as part of a resource script.

name=Menu
<button>
name=NewGame
clone=fancy
x=100
y=100
captiontext=New Game
</button>
<button>
name=Exit
clone=fancy
x=100
y=100
captiontext=Exit
</button>

The opening line is the name of the Window. Names must be unique throughout the GUI system and is how we ask the GUI system to show, hide and retrieve a specific window.

Next we define the controls. In the above example we've created two buttons named NewGame and Exit. If the window is showing, all we have to do is ask if the buttons were hit during the last gui update..

'This code would go in an AppModules Update function..
If ( GuiButtonHit( "Exit" ) )
	EndModule()
	Return
Else If ( GuiButtonHit( "NewGame" ) )
	BeginGame()
End If

No waiting for events, event loops or callbacks to deal with. The system handles playing mouse over sounds and state changes while we're just interested in whether or not it's been "Hit"

Drawing the GUI is one simple call that you must add to your AppModules Draw method. This gives you control over the draw order (and even if it's drawn at all).

See DrawGUI, GuiShowWindow, GuiHideWindow, GuiIsWindowShowing, GuiIsMouseOver

Parameter Description Default Value

name The name of control, and the only way your app communicates with it!

x X position relative to the form origin 0

y Y position relative to the form origin 0

width The control width that defines it's clickable area 0

height The control height that defines it's clickable area 0

normal A sprite image for the controls Normal state Null

over A sprite image for the controls Mouse Over state Null

down A sprite image for the controls Clicked Down state Null

normalrect Color for an alpha blended rect for the normal state Null

overrect Color for an alpha blended rect for the mouse over state Null

downrect Color for an alpha blended rect for the mouse down state Null

off_normal A sprite image for a checkbox OFF Normal state Null

off_over A sprite image for a checkbox OFF Mouse Over state Null

off_down A sprite image for the checkbox OFF Clicked Down state Null

soundclick The name of a sound effect file to be played on click Null

soundover The name of a sound effect file to be played on mouse over Null

font The name of the font as defined in the GUI config file The first font in the config list

captioncolor The color of the caption text as comma seperated integer (0-255) values 255,255,255,255

overcolor The color of the caption text on Mouse Over 255,255,255,255

downcolor The color of the caption text on Mouse Down 255,255,255,255

captionhjust The horizontal justification (0 = left, 1 = center, 2 = right) 1 (center)

captionvjust The vertical justification (0 = left, 1 = center, 2 = right) 1 (center)

downx The X offset postion for the caption text on mouse down +1 pixel

downy The Y offset postion for the caption text on mouse down +1 pixel

downoffset The X and Y offset postion for the caption text on mouse down +1 pixel

togglebutton Denotes whether the button is a checkbox toggle 0 (false)

slidermin The min pixel position of the slider button 0

slidermax The max pixel position of the slider button 0

sliderdirection The direction of the slider (0 = no sliding, 1 = horizontal, 2 = vertical) 0

onenter The name of a button hit that can be faked when the user presses enter on the input line Null

Parameter	Description	Default Value
name	The name of control, and the only way your app communicates with it!
x	X position relative to the form origin	0
y	Y position relative to the form origin	0
width	The control width that defines it's clickable area	0
height	The control height that defines it's clickable area	0
normal	A sprite image for the controls Normal state	Null
over	A sprite image for the controls Mouse Over state	Null
down	A sprite image for the controls Clicked Down state	Null
normalrect	Color for an alpha blended rect for the normal state	Null
overrect	Color for an alpha blended rect for the mouse over state	Null
downrect	Color for an alpha blended rect for the mouse down state	Null
off_normal	A sprite image for a checkbox OFF Normal state	Null
off_over	A sprite image for a checkbox OFF Mouse Over state	Null
off_down	A sprite image for the checkbox OFF Clicked Down state	Null
soundclick	The name of a sound effect file to be played on click	Null
soundover	The name of a sound effect file to be played on mouse over	Null
font	The name of the font as defined in the GUI config file	The first font in the config list
captioncolor	The color of the caption text as comma seperated integer (0-255) values	255,255,255,255
overcolor	The color of the caption text on Mouse Over	255,255,255,255
downcolor	The color of the caption text on Mouse Down	255,255,255,255
captionhjust	The horizontal justification (0 = left, 1 = center, 2 = right)	1 (center)
captionvjust	The vertical justification (0 = left, 1 = center, 2 = right)	1 (center)
downx	The X offset postion for the caption text on mouse down	+1 pixel
downy	The Y offset postion for the caption text on mouse down	+1 pixel
downoffset	The X and Y offset postion for the caption text on mouse down	+1 pixel
togglebutton	Denotes whether the button is a checkbox toggle	0 (false)
slidermin	The min pixel position of the slider button	0
slidermax	The max pixel position of the slider button	0
sliderdirection	The direction of the slider (0 = no sliding, 1 = horizontal, 2 = vertical)	0
onenter	The name of a button hit that can be faked when the user presses enter on the input line	Null

Controls

Controls are grouped together onto a Window, but Window is just a term -- it doesn't mean there is any physical window drawn around them. Controls are defined in the Window file in an html-like fashion, where a tag is opened, parameters defined one per line and then the tags are closed. Controls are drawn in the order they are defined.

Parameters can be specified for every control to give each control a unique style. There's no concept of "skinning" in this GUI, simply provide a unique image for each state, and a font name and caption text. This is where Clones come into play. If you have a button style you use often you can declare a clone in the GUI configuration file that covers all the parameters that don't change.

Buttons, Sliders and Checkboxes

Why are all these under one heading? Because they are all the same control! A slider is a button that has freedom to move along the X or Y axis, and a checkbox is merely a tri-state button.

See GuiGetButtonState, GuiSetButtonState, GuiButtonHit, GuiGetSliderValue, GuiSetSliderValue, GuiGetControlCaptionText, GuiSetControlCaptionText

Input Lines

A text input line.

Images

Any sprite image can be loaded and drawn drawn simply by setting the "normal", "x" and "y"

Localisation

A locale text file simply contains a map of name strings to value strings. A name always begins with ## to identify it as a locale string name and not a string literal

' english.txt
' -----------
##Hello = Hello!
##Goodbye = Goodbye!
##ExitImage = data\exit.bmp

' deutsche.txt
' ------------
##Hello = Hallo!
##Goodbye = Auf Wiedersehen!
##ExitImage = data\ausgang.bmp

A locale string name may be used in place of a string literal in the resource scripts or GUI form files. This example will not load an image directly, but ask the locale for the correct filename;

' a resource script
' -----------------
SPRITE ExitSign = ##ExitImage

System specific locale strings are also supported via the $$Win, $$Mac and $$Linux prefixes. Useful for things like purchase url's where each language can be directed to a localised web page.

Retrieving a Locale String

As well as using Locale Strings in resource files, you may retrieve them in code:

Local msg$ = LocaleString( "##Hello" )

In code, locale strings are read only!

See LocaleString, LoadLocaleStrings

INI Values

Storing settings such as player profile names, high scores and preferences is handled automatically via this INI system to which you have full access. It provides:

Saving in the correct system location on XP and Vista

Optional encryption to deter cheating and unauthorised tweaking

Automatic write-to-disc

Simplified fallbacks to default values

Retrieving values

Sometimes an application will call for a value that doesn't yet exist and needs to rely on receiving a sensible default. These values may need to be stored but sometimes just keeping to the default is preferred. Here's one way to retrieve a value:

Local x:Float = GetINIValue( "XPos", 21.7 )

asking for a value named "XPos", and if it doesn't exist it will return 21.7 AND store XPos=21.7 in the INI file. To prevent storing if it doesn't exist, use the optional "allowCreate" flag:

Local x:Float = GetINIValue( "XPos", 21.7, False ).ToFloat()

NOTE The INI file only works with string names and string values, so you will occasionally need to convert, as the above example.

Setting values

To set (or store) an individual value, simply store it by a name that can be used to retrieve it:

SetINIValue( "XPos", 21.7 )

This function will immediately write the entire INI file to disc so values will not be lost if the user exits unusually. However, if you have many attributes to set at once, you can delay the writing operation:

For local i:Int = 0 to 10
	SetINIValue( "XPos" + ( i + 1 ), xarray[i], True )
Next
WriteINIFile()

Managing encryption

Encrypting the INI file ensures it's not human readable and is a reasonably secure method to prevent cheating by players tweaking their high scores, game progress or awards. You can turn off encryption altogether and customise the hash table string to be unique to your application.

By default, encryption is OFF in DEBUG builds. However it can still read encrypted files if they were previously saved in a RELEASE build.

See GetINIValue, SetINIValue, SetINIHash, CustomiseINIHash

Player profiles

High scores

Particles

Functions Summary

AddDummyHighScores	Insert a set of dummy high scores into the managed list.
AddHighScore	Try and add a new score into the high score list.
AllowINIHash	Tell the application to hash the ini values when they are written to disc.
CustomiseINIHash	Randomise the INI hash to your app specific seed.
DisableProfiling	Turn off application profiling.
EnableGuestAccount	Enable or disable the guest account.
EnableProfiling	Turn on application profiling.
EnterProfileSection	Enter a section of code to be profiled.
ExitProfileSection	Exit a section of code to be profiled.
GetHighScoreName	Get the score value from the group and index.
GetHighScoreValue	Get the score value from the group and index.
GetINIValue	Retrieve the value of an INI entry.
InitApp	Initialise the application.
isFullscreen	Check if the current app is running fullscreen.
LoadGUI	Load the GUI configuration.
LoadLocaleStrings	Load the locale strings.
localeString	Find the locale string matching this name.
mbm_AlphaBlendPixels	Alpha blends two 32 bit ARGB pixels together.
mbm_FrameworkInfo	Retrieve the framework name and version number.
mbm_GetStreamPrefix	Get the current prefix for all loading operations.
mbm_LoadImage	Loads an image using the current stream prefix.
mbm_LoadPixmap	Loads a pixmap using the current stream prefix.
mbm_LoadSound	Loads a sound using the current stream prefix.
mbm_OpenFileReadOnly	Opens a file using the current stream prefix.
mbm_StreamPrefix	Set a global prefix for all loading operations.
RunApp	Run the application.
SetINIHash	Provide a unique hash string.
SetINIValue	Set the value of an INI entry.
strcmp
strncmp
WriteINIFile	Write the INI file to disc.

Types Summary

_mbm_BaseSprite	The base sprite type.
Animator	Animator.
AppModule	AppModule.
MasterSprite	MasterSprite.
ParticleEmitter	A 2d Particle emitter.
scaleFader	A special fx type that scales a TImage and simulateounsly fades it away.
Sprite
SpriteList
TBMFont	Type TBMFont.

Functions

Function AddDummyHighScores( groupID:Int, name:String, iMaxScore:Int, iScoreDecr:Int, iCount:Int )
Description	Insert a set of dummy high scores into the managed list.
Information	This is used to populate a high score list when your game is first installed.

Function AddHighScore:Int ( iGroupID:Int, iScore:Long )
Returns	Less than zero if the score didn't qualify, or a zero based indexed.
Description	Try and add a new score into the high score list.

Function AllowINIHash( allow:Int = True )
Description	Tell the application to hash the ini values when they are written to disc.
Information	In debug builds the INI file isn't encrypted so it's human readable, but it's still capable of reading hashed files if they were previously saved in a release build.

Function CustomiseINIHash ( seed:Int )
Description	Randomise the INI hash to your app specific seed.
Information	This function generates a hash string unique to the see. It also prints the resulting Hash string to the debuglog, where you may copy and paste it into your code if you don't want to rely on the Rand function always building the same hash. The copy + pasted string can be used with the SetINIHash function.

Function DisableProfiling ( )
Description	Turn off application profiling.

Function EnableGuestAccount ( state:Int = True )
Description	Enable or disable the guest account.
Information	Not all games require a guest account. Use this function to enable or disable it. It's disabled by default.

Function EnableProfiling ( outfile:String )
Description	Turn on application profiling.

Function EnterProfileSection ( name:String )
Description	Enter a section of code to be profiled.

Function ExitProfileSection ( name:String )
Description	Exit a section of code to be profiled.
Information	The profiler will keep track of the number of times this section of code has been called and the time (in milliseconds) of each call.

Function GetHighScoreName:String ( iGroupID:Int, iScoreID:Int )
Returns	The score name.
Description	Get the score value from the group and index.
Information	It's important that the score group is fully populated before you try and access it!

Function GetHighScoreValue:Long ( iGroupID:Int, iScoreID:Int )
Returns	The score value.
Description	Get the score value from the group and index.
Information	It's important that the score group is fully populated before you try and access it!

Function GetINIValue:String ( name:String, defValue:String, allowCreate:Int = False )
Returns	If there's an entry matching the name, the entry value, otherwise the.
Description	Retrieve the value of an INI entry.

Function InitApp:Int ( width:Int = 1024, height:Int = 768, colordepth:Int = 32, constantsFile:String = "" )
Description	Initialise the application.
Information	Set the Window or screen size, and the constants ini file. Must be called before any other engine functions!

Function isFullscreen:Int ()
Returns	Whether the app is running in windowed or fullscreen mode.
Description	Check if the current app is running fullscreen.
Information	This function checks the ini file for a fullscreen setting. In DEBUG builds it will default to FALSE, in RELEASE builds it will default to TRUE.

Function LoadGUI ( file:String )
Description	Load the GUI configuration.
Information	A GUI config file defines what bitmap fonts to load, the mouse pointer images and any predefined buttons.

Function LoadLocaleStrings( file:String )
Description	Load the locale strings.

Function localeString:String ( key:String )
Returns	The string value if successful, otherwise a lengthy error message string.
Description	Find the locale string matching this name.
Information	The long error message makes it easy to see the locale string wasn't found, as well as reporting a message to the debuglog.

Function mbm_AlphaBlendPixels:Int( dest:Int, src:Int )
Description	Alpha blends two 32 bit ARGB pixels together.
Information	Useful when overlaying one alpha'd image onto another.

Function mbm_FrameworkInfo:String ()
Description	Retrieve the framework name and version number.
Information	Useful for displaying which version of the framework your game was built against.

Function mbm_GetStreamPrefix:String ()
Description	Get the current prefix for all loading operations.

Function mbm_LoadImage:TImage ( fileName:String, flags:Int = -1 )
Description	Loads an image using the current stream prefix.

Function mbm_LoadPixmap:TPixmap ( fileName:String )
Description	Loads a pixmap using the current stream prefix.

Function mbm_LoadSound:TSound ( fileName:String, flags:Int = 0 )
Description	Loads a sound using the current stream prefix.

Function mbm_OpenFileReadOnly:TStream ( fileName:String )
Description	Opens a file using the current stream prefix.

Function mbm_StreamPrefix( t:String )
Description	Set a global prefix for all loading operations.
Information	Useful for accessing an incbin'd resource ie "zip::incbin::Media.zip//"

Function RunApp ()
Description	Run the application.
Information	Run the application. Application behaviour will depend on the number and types of registered AppModules.

Function SetINIHash( hash$ )
Description	Provide a unique hash string.
Information	This string must be of the correct length, with the correct characters so it's easier to call CustomiseINIHash to obtain a string to use for this function.

Function SetINIValue ( name:String, value:String, delayWrite:Int = False )
Description	Set the value of an INI entry.
Information	This function automatically writes an updated file to disc to ensure values are not lost if the user kills the app. If you have a lot of values to write sequentially, you may use the delayWrite flag to prevent file writing for every call, then use WriteINIFile at the end.

Function strcmp:Int ( s1:String, s2:String )

Function strncmp:Int ( s1:String, s2:String, n:Int )

Function WriteINIFile ()
Description	Write the INI file to disc.
Information	A lot of modification functions will automatically write the file, but this function can be called to force a write if modifications have been made under delayWrite conditions.

Types

Type _mbm_BaseSprite
Description	The base sprite type.
Information	You won't need to use this type, but Sprite is derived from it and you have access to the following methods.

Methods Summary
AddFrame	Add a new animation frame at the end of the current frames.
AnimationTime
CurrentFrame
Draw	Draw the sprite.
DrawDirect	Draw the sprite at the supplied screen position.
DrawDirectEx	Draw the sprite with the current render settings (scale, alpha, rotation etc)
GetAlpha	Get the sprites alpha value.
GetPosition	Get the sprite screen position.
GetRotation	Get the sprites rotation.
GetScale	Get the sprites scale.
GetX	Get the sprites screen position in X.
GetY	Get the sprites screen position in Y.
Image	Get the sprites current image.
RandomizeTime	Sets the animation time somewhere bewteen 0 and the total animation time.
ResetTime	Puts the sprite animation time back to zero.
SetAlpha	Set the sprite alpha.
SetFrame
SetPosition	Set the sprite screen position.
SetRotation	Set the sprite rotation.
SetScale	Set the sprite scale.
SetX	Set the sprites screen position in X.
SetY	Set the sprites screen position in Y.
TotalFrames
Update	Update the sprite animation with a float based delta time (0.001 * millisecs_elapsed)

Method AddFrame( bitmap:String, timeMS:Int )
Description	Add a new animation frame at the end of the current frames.
Information	To be used for procedurally generated MasterSprites.

Method AnimationTime:Float ()
Information	The running time of the bitmap animations.

Method CurrentFrame:Int ()
Information	The current animation bitmap frame, in the range 0 to TotalFrames - 1.

Method Draw( timeMS:Int = 0 )
Description	Draw the sprite.
Information	The sprites animation can also be updated by supplying a valid delta time.

Method DrawDirect( fX:Float, fY:Float, timeMS:Int = 0 )
Description	Draw the sprite at the supplied screen position.
Information	This ignores the sprite position and uses the supplied position. The sprite animation can also be updated by providing a valid deltatime.

Method DrawDirectEx( fX:Float, fY:Float )
Description	Draw the sprite with the current render settings (scale, alpha, rotation etc)
Information	This function ignores the sprites internal settings, useful for manual control of rendering a specific frame in a specifc way.

Method GetAlpha:Float()
Description	Get the sprites alpha value.

Method GetPosition( x:Float Var, y:Float Var )
Description	Get the sprite screen position.

Method GetRotation:Float()
Description	Get the sprites rotation.

Method GetScale:Float()
Description	Get the sprites scale.

Method GetX:Float ()
Description	Get the sprites screen position in X.

Method GetY:Float ()
Description	Get the sprites screen position in Y.

Method Image:TImage ()
Description	Get the sprites current image.
Information	For animated sprites, the image will be the one relating to the current animation time.

Method RandomizeTime()
Description	Sets the animation time somewhere bewteen 0 and the total animation time.

Method ResetTime()
Description	Puts the sprite animation time back to zero.

Method SetAlpha( a:Float )
Description	Set the sprite alpha.
Information	This vale can also be affected by any animators that are running.

Method SetFrame( frame:Int )
Information	Manually select a frame for the current sprite.

Method SetPosition( x:Float, y:Float )
Description	Set the sprite screen position.
Information	This position can also be affected by any animators that are running.

Method SetRotation( r:Float )
Description	Set the sprite rotation.
Information	This value can also be affected by any animators that are running.

Method SetScale( s:Float )
Description	Set the sprite scale.
Information	This value can also be affected by any animators that are running.

Method SetX( x:Float )
Description	Set the sprites screen position in X.
Information	This position can also be affected by any animators that are running.

Method SetY( y:Float )
Description	Set the sprites screen position in Y.
Information	This position can also be affected by any animators that are running.

Method TotalFrames:Int ()
Information	The total number of bitmap frames in the animation.

Method Update( timeMS:Int )
Description	Update the sprite animation with a float based delta time (0.001 * millisecs_elapsed)

Type Animator
Description	Animator.
Information	A simple animation type that controls a value over time, for a given input.

Methods Summary
Duplicate	Duplicate.
HasExpired	Checks to see if an animator has ran it's course.
Restart	Resets an animator to it's original state and starts it going.
Update	Update the animtor with the current time delta.
Value	Get the current value of the Animator.

Functions Summary
CreateAcclBrake	Create a accelerating and braking Animator.
CreateBounce	Create a bouncing Animator.
CreateCUSTOM	Create a custom Animator.
CreateLERP	Create a linear interpolation Animator.
CreateSINE	Create a Sine curve based Animator.
Load	Loads an animator from a current open stream.

Method Duplicate:Animator ()
Returns	A new animator object.
Description	Duplicate.
Information	Creates a duplicate animator so it may have it's own delta time etc.

Method HasExpired:Int ()
Returns	TRUE if the animator has indeed _expired, otherwise FALSE.
Description	Checks to see if an animator has ran it's course.
Information	Not all animators will expire. Bouncing animators with perfect bounyness, linear interpolators set to repeat etc, will basically run forever.

Method Restart ()
Description	Resets an animator to it's original state and starts it going.

Method Update( timeMS:Int )
Description	Update the animtor with the current time delta.

Method Value:Float()
Description	Get the current value of the Animator.

Function CreateAcclBrake:Animator( fStart:Float, fStartSpeed:Float, fEnd:Float, fBrakingPoint:Float, fAcceleration:Float, fMaxVelocity:Float, playOnce:Int = False )
Returns	A new animator object.
Description	Create a accelerating and braking Animator.
Information	This animator accelerates from fStartSpeed up to fMaxVelocity (space permitting) until it reaches fBrakingPoint where is decelerates to reach zero speed at the fEnd position.

Function CreateBounce:Animator( fStart:Float, fStartSpeed:Float, fFloor:Float, fBouncyness:Float, fGravity:Float, playOnce:Int = False )
Returns	A new animator object.
Description	Create a bouncing Animator.
Information	The speed is affected by the fStartSpeed and fGravity, once the current value reaches the fFloor, its speed is reversed (bounced) and reduced by the factor fBouncyness (1.0 = perfect preservation of energy, 0.0 = no bounce). Use fBouncyness values over 1.0 with care.

Function CreateCUSTOM:Animator ( init_data:Float[], callback:String, playOnce:Int = False )
Returns	A new animator object.
Description	Create a custom Animator.

Function CreateLERP:Animator ( fStart:Float, fSpeed:Float, fEnd:Float, reverse:Int, playOnce:Int = False )
Returns	A new animator object.
Description	Create a linear interpolation Animator.
Information	Linear interpolation is a simple transition from start to end at speed. If fEnd is smaller than fStart, then fSpeed should be negative.

Function CreateSINE:Animator( fStart:Float, fFrequency:Float, fMagnitude:Float )
Returns	A new animator object.
Description	Create a Sine curve based Animator.
Information	The current value is always between fStart and fStart + (fMagnitude * 2)

Function Load:Animator( inFile:TStream, stop:String )

Returns

A new animator object.

Description

Loads an animator from a current open stream.

Information

Animators have 10 initial values (%data0 to data9) and two flags (%_playOnce and script). For each animation type, the initial values vary, the script value is unique and the _playOnce value depends on your usage.

Animator Type	Parameters
Linear Interpolate	data0 = start point, data1 = speed, data2 = end point, data3 = reverse flag, script = lerp
Sin curve	data0 = start point, data1 = frequency, data2 = magnitude, script = sine
Bounce	data0 = start point, data1 = start vector, data2 = floor value, data3 = bounce fall off (bounciness), data4 = gravity, script = bounce
Accelerate and brake	data0 = start point, data1 = start velocity, data2 = target point, data3 = braking point, data4 = acceleration, data5 = max velocity, script = acclbrake

A typical text file may look like this..

<script>
data0 = 20
data1 = 100
data2 = 400
data3 = 1
script = lerp
_playOnce = 1
</script>

Where you will detect the start of the script at the <script> tag, and ask this function to continue loading stopping at the </script> tag.

Type AppModule
Description	AppModule.
Information	The master type from which all other Application Modules should be derived.

Methods Summary
_EndModule
AddRefCountedBitmap	Add a new image to the systems list of reference counted bitmaps.
ConstFloat	Get a constant value cast to a float.
ConstInt	Get a constant value cast to an integer.
ConstString	Get a constant string value.
CreateMasterSprite	Create a new, empty MasterSprite for manual creation.
DestroyModule
DestroyScreenGrabImage	Destroy the grabbed image and attempt to free the VRAM it occupied.
Draw	A method that should be overidden in the derived types.
DrawGUI
DrawParticleEmitters
DrawScreenFade
EndModule
FadeInComplete
FadeOutComplete
GetEmitter
GetSound	Find and return a sound resource by name.
GetSprite	Find and return a Sprite resource by name.
GetVSync
GuiButtonArrayHit	Check for a GUI button hit beginning with this name.
GuiButtonArrayID	Check for a GUI button hit.
GuiButtonHit	Check for a GUI button hit.
GuiDisableControl
GuiDrawText
GuiEnableControl
GuiGetControlCaptionRegion
GuiGetControlCaptionText
GuiHideControl
GuiHideWindow
GuiIsControlEnabled
GuiIsControlShowing
GuiIsWindowShowing
GuiMouseOver
GuiSetControlCaptionText
GuiSetWindowPos
GuiShowControl
GuiShowWindow
GuiTurnMouseOff
GuiTurnMouseOn
Initialise
IsFading
LeaveSongsInMemory	Inform the AppModule if it should clear out it's loaded songs.
LoadEmitter	Load a new particle emitter.
LoadingNotify	An overridable function called each time a resource is loaded via a resource script.
LoadingProgress
LoadResources	A Method that can be overridden by the derived types.
LoadSound	Load a new sound resource.
LoadSprite	Load a new sprite resource.
LoadWindow	Load a new GUI window.
ParticleCount
ParticleEmitOverControlCaptionRegion
Pause
PlaySound
PlaySoundByName
ReplaceSpriteResource	Load a new sprite resource in place of an existing one.
screenGrab	Perform a screen grab and return the resulting image.
SetFadeColor
SetVSync
Start
StartFadeIn
StartFadeOut
Stop
Uninitialise
UnloadResources
UnloadSprites
Unpause
Update	A method that should be overidden in the derived types (if needed).

Functions Summary
AddNewUser
CountUsers
FPS	Returns the current Frames Per Second.
FrameDelta
GetMusicVolume	Get the current application preference music volume level.
GetSoundVolume	Get the current application preference sound volume.
GetVolumeSliderPosition	Gets a Volume level from a GUI slider.
LastMS
PlayerProfileName
PopulatePlayerProfileList
RemoveUser
ScreenshotKey	Tell the app which key autosaves a screen shot (Default = F10)
SelectUser
SetMusicVolume	Set the current application preference music volume.
SetSoundVolume	Set the current application preference sound volume.
SetUserName
SetVolumeSliderPosition	Sets a GUI slider position according to a volume value.
ToggleFullscreen
UpdateFullscreenButton	Sets the toggle value of a button according to the status of the application.
UpdateFullscreenFromButton	Checks a toggle button state and adjusts the fullscreen status.
UpdateLoadingProgress
UserID
UserName

Method _EndModule()

Method AddRefCountedBitmap( name:String, img:TImage )
Description	Add a new image to the systems list of reference counted bitmaps.
Information	Bitmaps are usually reference counted using their filenames as a means of detecting multiple usage, so adding a new image requires a unique name. The inital reference count of this image will be Zero.

Method ConstFloat:Float ( name:String )
Description	Get a constant value cast to a float.
Information	See ConstString.

Method ConstInt:Int ( name:String )
Description	Get a constant value cast to an integer.
Information	See ConstString.

Method ConstString:String( name:String )
Returns	If a matching constant exists, the constant value. In DEBUG builds,
Description	Get a constant string value.

Method CreateMasterSprite:MasterSprite ( name:String )
Description	Create a new, empty MasterSprite for manual creation.
Information	This is used for procedurally generating sprites. Once created you must AddFrames to it before it can be drawn.

Method DestroyModule( iID:Int )

Method DestroyScreenGrabImage()
Description	Destroy the grabbed image and attempt to free the VRAM it occupied.

Method Draw ()
Description	A method that should be overidden in the derived types.
Information	Called once per frame, and most of the time doesn't need to perform a Cls or a Flip. The derived method should always call Super.Draw() at the end of it's own drawing.

Method DrawGUI()

Method DrawParticleEmitters()

Method DrawScreenFade()

Method EndModule()

Method FadeInComplete()

Method FadeOutComplete()

Method GetEmitter:ParticleEmitter ( name:String )

Method GetSound:TSound ( name:String )
Returns	A valid TSound if a matching resource exists, otherwise NULL.
Description	Find and return a sound resource by name.
Information	Sounds are defined in the resource script as "SOUND name = value" eg "SOUND boom = data\sounds\boom.wav"

Method GetSprite:MasterSprite( name:String )
Returns	A valid MasterSprite if a matching resource exists, or NULL.
Description	Find and return a Sprite resource by name.
Information	Like all resource retrieval functions it will fail an assert if there is no resource of that name allowing you to quickly track down errors caused by mis-used resource names. Sprites are defined in the resource script as "SPRITE name = value" eg "SPRITE Player = data\images\player.tga"

Method GetVSync:Int ( )

Method GuiButtonArrayHit:Int ( button:String )
Returns	TRUE if a matching button was hit during the last GUI Update.
Description	Check for a GUI button hit beginning with this name.
Information	If you have an array of buttons eg "Select1", "Select2", "Select3" etc use this function with GuiButtonArrayID for simplified hit checking.

Method GuiButtonArrayID:Int ( button:String )
Returns	TRUE if the button was hit during the last GUI Update.
Description	Check for a GUI button hit.
Information	It's important to manage your GUI button names sensibly since there is no way to distinguish between buttons of the same name on different GUI windows.

Method GuiButtonHit:Int ( button:String )
Returns	TRUE if the button was hit during the last GUI Update.
Description	Check for a GUI button hit.
Information	It's important to manage your GUI button names sensibly since there is no way to distinguish between buttons of the same name on different GUI windows.

Method GuiDisableControl( windowName:String, controlName:String )

Method GuiDrawText( caption:String, x:Float, y:Float, font:String="" )

Method GuiEnableControl( windowName:String, controlName:String )

Method GuiGetControlCaptionRegion( windowName:String, controlName:String, rect:__RECT Var )

Method GuiGetControlCaptionText:String ( windowName:String, controlName:String )

Method GuiHideControl( windowName:String, controlName:String )

Method GuiHideWindow( windowName:String )

Method GuiIsControlEnabled:Int ( windowName:String, controlName:String )

Method GuiIsControlShowing:Int ( windowName:String, controlName:String )

Method GuiIsWindowShowing:Int ( windowName:String )

Method GuiMouseOver:Int ( windowName:String, controlName:String )

Method GuiSetControlCaptionText ( windowName:String, controlName:String, caption:String )

Method GuiSetWindowPos ( windowName:String, x:Int, y:Int )

Method GuiShowControl( windowName:String, controlName:String )

Method GuiShowWindow( windowName:String )

Method GuiTurnMouseOff()

Method GuiTurnMouseOn()

Method Initialise( resFile:String, moduleType:Int )

Method IsFading:Int ()

Method LeaveSongsInMemory( flag:Int )
Description	Inform the AppModule if it should clear out it's loaded songs.
Information	To save loading times, you can leave songs in the global song manager by calling this method before your AppModule ends.

Method LoadEmitter( name:String, file:String )
Description	Load a new particle emitter.
Information	Manually load particle emitter, instead of loading via a resource script.

Method LoadingNotify:Int ( file:String )
Description	An overridable function called each time a resource is loaded via a resource script.
Information	This gives your application the chance to refuse loading of a specific resource. returns: TRUE if the resource should be loaded, otherwise FALSE.

Method LoadingProgress:Int ()

Method LoadResources:loadingProfile ( )
Description	A Method that can be overridden by the derived types.
Information	Called each time the resources must be loaded. The derived type must call Super.LoadResources() BEFORE performing any loading operations. returns: An instance of a loadingProfile type that can be used to track loading times and update the loading screens.

Method LoadSound( name:String, file:String )
Description	Load a new sound resource.
Information	Manually load a new sound resource, instead of loading via a resource script.

Method LoadSprite( name:String, file:String )
Description	Load a new sprite resource.
Information	Manually load a sprite resource, instead of loading a collection of resources via a resource script.

Method LoadWindow( file:String )
Description	Load a new GUI window.
Information	Manually load a GUI Window instead of loading via a resource script.

Method ParticleCount:Int ()

Method ParticleEmitOverControlCaptionRegion( windowName:String, controlName:String, emitCount:Int, emitterName:String )

Method Pause()

Method PlaySound( sound:TSound, fVolume:Float = 1.0 )

Method PlaySoundByName ( name:String, fVolume:Float = 1.0 )

Method ReplaceSpriteResource( name:String, newFile:String )
Description	Load a new sprite resource in place of an existing one.
Information	Useful for changing the look of a sprite without changing it's resource name, for example different player characters or background images.

Method screenGrab:TImage ()
Description	Perform a screen grab and return the resulting image.
Information	This function calls the current Modules Draw function and grabs the screen before a flip is made ensuring the back buffer contents are correctly grabbed. The grabbed image is an AppModule field called screenGrabImage.

Method SetFadeColor( r:Int, g:Int, b:Int )

Method SetVSync ( sync:Int )

Method Start()

Method StartFadeIn()

Method StartFadeOut()

Method Stop()

Method Uninitialise()

Method UnloadResources ()

Method UnloadSprites()

Method Unpause()

Method Update ( timeMS:Int )
Description	A method that should be overidden in the derived types (if needed).
Information	Called once per frame with the delta time for the current frame. Remembering to call Super.Update( timeMS ) in the derived class will automatically ensure any particle emitters are updated.

Function AddNewUser( name:String )

Function CountUsers:Int ()

Function FPS:Int ()
Description	Returns the current Frames Per Second.
Information	The frames per second value is automatically updated every two seconds.

Function FrameDelta:Float ()
Information	returns:

Function GetMusicVolume:Float ()
Description	Get the current application preference music volume level.
Information	returns: A float in the range 0.0 to 1.0.

Function GetSoundVolume:Float ()
Description	Get the current application preference sound volume.
Information	returns: A float in the Range 0.0 to 1.0.

Function GetVolumeSliderPosition:Float ( windowName:String , controlName:String )
Description	Gets a Volume level from a GUI slider.

Function LastMS:Int ()
Information	returns:

Function PlayerProfileName:String ( userID:Int )

Function PopulatePlayerProfileList()

Function RemoveUser( userID:Int )

Function ScreenshotKey( key:Int )
Description	Tell the app which key autosaves a screen shot (Default = F10)
Information	Set the key to NULL to prevent saving screenshots.

Function SelectUser( userID:Int )

Function SetMusicVolume ( fVolume:Float )
Description	Set the current application preference music volume.
Information	This sets the volume level as well as writing the value to the current ini file (if available).

Function SetSoundVolume ( fVolume:Float )
Description	Set the current application preference sound volume.
Information	This sets the volume level as well as writing the value to the current ini file (if available).

Function SetUserName ( name:String )

Function SetVolumeSliderPosition( windowName:String , controlName:String , volume:Float )
Description	Sets a GUI slider position according to a volume value.

Function ToggleFullscreen()

Function UpdateFullscreenButton( windowName:String , controlName:String )
Description	Sets the toggle value of a button according to the status of the application.
Information	Used when showing an options form, so that the button matches the app state.

Function UpdateFullscreenFromButton( windowName:String , controlName:String )
Description	Checks a toggle button state and adjusts the fullscreen status.
Information	If the toggle state does not match the application state, the screen mode is changed. The screen mode is also saved in the ini if available.

Function UpdateLoadingProgress( iPercent:Int )

Function UserID:Int ()

Function UserName:String ()

Type MasterSprite Extends _mbm_BaseSprite
Description	MasterSprite.
Information	Used for loading a sprite, from which other instances (that contain their own screen position and animation time) can be created. This can also be used directly. It's derived from _mbm_Base_Sprite so refer to it's methods too.

Methods Summary
CreateInstance	Create and instance of a MasterSprite.
Destroy	Destroy a MasterSprite object.

Functions Summary
Create	Create a MasterSprite from a file or series of files.

Method CreateInstance:Sprite ()
Returns	A new Sprite object.
Description	Create and instance of a MasterSprite.
Information	Returns a Sprite instance that will have its own screen position and animation time. You should update each instance you make in order to update its animation, either by specifically calling its Update() function or when drawing it.

Method Destroy()
Description	Destroy a MasterSprite object.
Information	If it has no living instances it's animation controllers will be destroyed. If its bitmap(s) are not referenced by other Sprites, they will be unloaded.

Function Create:MasterSprite( strUrl:String )
Returns	A new MasterSprite object.
Description	Create a MasterSprite from a file or series of files.
Information	The file may be; .bmp, .jpg, .tga or .png or a .csv file of animation frames and their times. Any filename (eg player.bmp) may have a corresponding .txt file next to it (ie player.txt) that describes various parameters and scripts such as the image handle position and scripts for automatically manipulating the X position, Y position, Rotation and Scale.

Type ParticleEmitter
Description	A 2d Particle emitter.

Methods Summary
DoBurst	Emit new particles at the specified screen coordinates.
Draw	Draw the particle emitter.
LiveCount	Get the number of particles the emitter has.
SetDirection	Set the angular direction of the emitter.

Method DoBurst( iX:Int, iY:Int, fpsSync:Int = True )
Description	Emit new particles at the specified screen coordinates.
Information	Particle emitters are generally limited to 50 frames per second to prevent continuous bursts from generating too many particles on machines with a high frame rate. To overide the fps limitation set fpsSync to False.

Method Draw()
Description	Draw the particle emitter.

Method LiveCount:Int ()
Description	Get the number of particles the emitter has.
Information	Live particles are those that are drawn and updated.

Method SetDirection( a:Float )
Description	Set the angular direction of the emitter.
Information	For emitters that have a defined cone angle, this sets the direction of that cone ready for the next DoBurst call.

Type scaleFader
Description	A special fx type that scales a TImage and simulateounsly fades it away.

Functions Summary
Clear	Clear the internal list.
Create	Create a new scaling / fading effect.
Draw	Draw all the effects.
LiveCount	Get how many effects are alive.
Update	Update all the faders in the managed list.

Function Clear()
Description	Clear the internal list.

Function Create:scaleFader( i:TImage, x:Float, y:Float, alpha:Float = 1.0, scale:Float = 1.0, alphaSpeed:Float = 1.0, scaleSpeed:Float = 1.0 )
Returns	The new effect, but it's not really needed as it's added to a internal list.
Description	Create a new scaling / fading effect.

Function Draw( Xoffset:Float, Yoffset:Float )
Description	Draw all the effects.

Function LiveCount:Int ()
Description	Get how many effects are alive.

Function Update( timeMS:Int )
Description	Update all the faders in the managed list.

Type Sprite Extends _mbm_BaseSprite
Information	Used to create copies of a master sprite. This instance will have its own screen position and deltatime. It's derived from _mbm_BaseSprite so refer it's documented methods too.

Functions Summary
CreateInstance	CreateInstance.

Function CreateInstance:Sprite ( master:MasterSprite )
Description	CreateInstance.
Information	An alternative to calling the CreateInstance method.

Type SpriteList

Information

Used to manage lists of Sprite objects. You can make a list from any MasterSprite object. When you want to spawn a new sprite from this SpriteList call NextFree() that will return a Sprite object for you to work with (ie set it's screen position and set it's animation time etc). The returned Sprite will automatically be added to the SpriteLists list of 'live' sprites, that are drawn and updated.

The whole list can be drawn and updated by one simple call to their respective methods.

When you want to remove a sprite from the 'live' list, call Kill. That will free it up to be used again when you next call NextFree and prevent it from being Drawn and Updated.

You may derive your own types from SpriteList and override the methods to suit your purposes. For example you may want to override Update() to handle your sprites specific behaviour.

You have access to the 'free' and 'live' lists of sprites, but be careful how you use them. It's recommended you only use them for traversing and working on the individual sprites with EachIn.

Fields Summary
free , live

Methods Summary
Draw	Draw all the live sprites.
FreeCount	Get the number of free sprites available.
FreeList	Retrieve the list of 'free' sprites.
Kill	Kill a sprite so it can be re-used.
LiveList	Retrieve the list of 'live' sprites.
NextFree	Get a new sprite from the 'free' list.
Update	Update the animation of the live sprites.

Functions Summary
Create	Create a new sprite list from the supplied MasterSprite.

Field free:TList
Description	The list of 'free' sprites.
Information	Free sprites are those that are sitting in reserve waiting to be called into action.

Field live:TList
Description	The list of 'live' sprites.
Information	Live sprites are Updated and Drawn.

Method Draw()
Description	Draw all the live sprites.

Method FreeCount:Int ()
Description	Get the number of free sprites available.

Method FreeList:TList ()
Description	Retrieve the list of 'free' sprites.

Method Kill ( s:Sprite )
Description	Kill a sprite so it can be re-used.
Information	This removes the sprite from the live list and returns it to the free list so it will no longer be Updated or Drawn and can be reused when NextFree is called.

Method LiveList:TList ()
Description	Retrieve the list of 'live' sprites.

Method NextFree:Sprite( forceRenew:Int = False )
Description	Get a new sprite from the 'free' list.
Information	The sprite is automatically removed from the free list added to the live list so it will be updated and drawn until it's killed. If there are no sprites left in the free list you can force the method ro recycle the oldest living live sprite by setting the forceRenew flag to True.

Method Update( timeMS:Int )
Description	Update the animation of the live sprites.

Function Create:SpriteList( master:MasterSprite, count:Int )
Description	Create a new sprite list from the supplied MasterSprite.
Information	Specify how many sprite instances are to be made with the count flag.

Type TBMFont
Description	Type TBMFont.
Information	Bitmap Font Object.

Fields Summary
Align , CallBackChars , HSpacing , Kerning , Shadow , ShadowX , ShadowY , SkipChars , VSpacing

Methods Summary
ApplyTexture	Adds a texture to the font.
CreateShadow	Creates a soft shadow of the bitmap font (position can be set with ShadowX and ShadowY). WARNING: CreateShadow uses the backbuffer!
DrawText	Draws the text using the bitmap font characters using the current values for Align, Shadow, ShadowX, ShadowY, HSpacing, VSpacing and Kerning.
EnableCustomTexture	Switches custom textures on or off.
Init	Initializes a new TBMFont object from a binary .fnt file.
OnCallBack	Callback function that is called before drawing a character that occurs in the string CallBackChars.
TextHeight	Returns the height of a string in pixels using the current scale.
TextWidth	Returns the width of a string in pixels using the current scale.

Functions Summary
Create	Creates a new TBMFont object from a binary .fnt file.

Field Align: Int
Description	Sets the horizontal text alignment.
Information	This can be ALIGN_LEFT (default), ALIGN_CENTER or ALIGN_RIGHT.

Field CallBackChars: String
Description	String of characters that generate a callback.
Information	This can be used for control characters that change the color or offset (dx, dy).

Field HSpacing: Float
Description	Horizontal spacing in pixels.
Information	This can be used to add extra spacing between characters.

Field Kerning: Int
Description	Sets whether kerning should be used or not (on by default if FNT file has kerning).
Information	Kerning adjusts the distance between certain pairs of characters.

Field Shadow: Int
Description	Sets whether the shadow should be drawn (use CreateShadow to create the shadow first).

Field ShadowX: Int
Description	Horizontal shadow offset.
Information	Relative to the text.

Field ShadowY: Int
Description	Vertical shadow offset.
Information	Relative to the text.

Field SkipChars: String
Description	String of characters that should not be drawn.
Information	This can be used for control characters.

Field VSpacing: Float
Description	Vertical spacing in pixels.
Information	This can be used to add extra spacing between lines.

Method ApplyTexture (Tex: TImage)
Description	Adds a texture to the font.
Information	Parameters: Tex: The texture image or NULL to reset

Method CreateShadow (ShadowBlur: Float = 3, Amount: Int = 255)
Description	Creates a soft shadow of the bitmap font (position can be set with ShadowX and ShadowY). WARNING: CreateShadow uses the backbuffer!
Information	Parameters: ShadowBlur = 3: Blur size in pixels (1..9), be sure to add padding space on all sides! Amount = 255: Shadow darkness 1..255 or 0 to reset

Method DrawText (Text: String, XPos: Float, YPos: Float)
Description	Draws the text using the bitmap font characters using the current values for Align, Shadow, ShadowX, ShadowY, HSpacing, VSpacing and Kerning.
Information	Parameters: Text: The string (can have multiple lines) XPos: Tye X position (center position for ALIGN_CENTER) YPos: The Y position

Method EnableCustomTexture (Value: Int)
Description	Switches custom textures on or off.
Information	Parameters: Value: True for custom texture, False for no texture.

Method Init (Prefix: String, FNTFile: String)
Description	Initializes a new TBMFont object from a binary .fnt file.
Information	Parameters: Prefix: This can be either incbin:: or a path like CurrentDir() + "/" FNTFile: This must be a binary FNT file (version 2)

Method OnCallBack (Char: Int, X: Float, Y: Float)
Description	Callback function that is called before drawing a character that occurs in the string CallBackChars.
Information	Parameters: Char: The character that is about to be drawn X: The X position Y: The Y position

Method TextHeight: Float (Text: String)
Description	Returns the height of a string in pixels using the current scale.
Information	Parameters: Text: The string (can have multiple lines)

Method TextWidth: Float (Text: String, Line: Int = -1)
Description	Returns the width of a string in pixels using the current scale.
Information	Parameters: Text: The string (can have multiple lines) Line=-1: If supplied, TextWidth only counts this line

Function Create: TBMFont (Prefix: String, FNTFile: String)
Description	Creates a new TBMFont object from a binary .fnt file.
Information	Parameters: Prefix: This can be either "incbin::" or a path like "fonts\" FNTFile: This must be a binary FNT file (version 2 or 3)

Module Information

Author	Matt (matibee) Bennett but contains code by others, see below...
Version	1.7
License	This module is free for non commercial use only by students and hobbyists. All users please register for updates! More info at http://www.matibee.co.uk/mbmframework
History	v1.7 2nd April 2010 - More GUI functionality added: Coloured rects can be used in place of bitmaps. Caption color per-state allowed. Sprite methods no longer use underscores (ie Set_Position now SetPosition).
History	v1.6 5th March 2010 - New functionality added for procedurally generated sprites and custom animation scripts.
History	v1.5 25th February 2010 - Several minor updates.
History	v1.4 18th February 2010 - More sprite functionality added.
History	v1.3 15th February 2010 - More particle system functionality added.
History	v1.2 10th February 2010 - Profiler added, some minor fixes.
History	v1.1 3rd February 2010 - Major fixes to BMFont to make it work under DX9
History	v1.0 31st January 2010 - First non-beta public release
History	v0.1 January 2010 - First release
Bitmap fonts	Original code; Mike Wierings' BMFont Mod.. www.wieringsoftware.nl/blitz/
Other code	Grey Alien's Folder Access code for Vista & up... http://www.blitzbasic.com/Community/posts.php?topic=73305#819232

mbmframework (matibee's BlitzMax Framework)

Contents

Application flow

AppModule Fundamentals

Flow logic

Profiling

Animators

Sprites

Sprite script file

Bitmap animation format

Resources

Accessing resources

Platform specific resources

Loading Progress

Sprite resources

Sound and Music resources

Constant values

GUI Windows

GUI

Initialising the GUI

Loading GUI Windows

Controls

Buttons, Sliders and Checkboxes

Input Lines

Images

Localisation

Retrieving a Locale String

INI Values

Retrieving values

Setting values

Managing encryption

Player profiles

High scores

Particles

Functions Summary

Types Summary

Functions

Types

Module Information