matibee.mbmframework: Functions Types Modinfo Source  

mbmframework (matibee's BlitzMax Framework)

mbmframework logo
Official site

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.


    Contents

    SystemDescription
    Application flow Automatic state changes between AppModules.

    AppModule fundamentals
    Flow logic.


    ProfilingProfiling and performance testing your code.
    AnimatorsAnimation 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

    LocalisationA 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 ProfilesManaging player profiles
    High scoresSaving and maintaining highscore lists
    ParticlesParticle 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
  • Register the AppModule instance
  • 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

    ParameterDescriptionDefault Value
    nameThe name of control, and the only way your app communicates with it!
    xX position relative to the form origin0
    yY position relative to the form origin0
    widthThe control width that defines it's clickable area0
    heightThe control height that defines it's clickable area0
    normalA sprite image for the controls Normal stateNull
    overA sprite image for the controls Mouse Over stateNull
    downA sprite image for the controls Clicked Down stateNull
    normalrectColor for an alpha blended rect for the normal stateNull
    overrectColor for an alpha blended rect for the mouse over stateNull
    downrectColor for an alpha blended rect for the mouse down stateNull
    off_normalA sprite image for a checkbox OFF Normal stateNull
    off_overA sprite image for a checkbox OFF Mouse Over stateNull
    off_downA sprite image for the checkbox OFF Clicked Down stateNull
    soundclickThe name of a sound effect file to be played on clickNull
    soundoverThe name of a sound effect file to be played on mouse overNull
    fontThe name of the font as defined in the GUI config fileThe first font in the config list
    captioncolorThe color of the caption text as comma seperated integer (0-255) values255,255,255,255
    overcolorThe color of the caption text on Mouse Over255,255,255,255
    downcolorThe color of the caption text on Mouse Down255,255,255,255
    captionhjustThe horizontal justification (0 = left, 1 = center, 2 = right)1 (center)
    captionvjustThe vertical justification (0 = left, 1 = center, 2 = right)1 (center)
    downxThe X offset postion for the caption text on mouse down+1 pixel
    downyThe Y offset postion for the caption text on mouse down+1 pixel
    downoffsetThe X and Y offset postion for the caption text on mouse down+1 pixel
    togglebuttonDenotes whether the button is a checkbox toggle0 (false)
    sliderminThe min pixel position of the slider button0
    slidermaxThe max pixel position of the slider button0
    sliderdirectionThe direction of the slider (0 = no sliding, 1 = horizontal, 2 = vertical)0
    onenterThe name of a button hit that can be faked when the user presses enter on the input lineNull

    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 )
    DescriptionInsert a set of dummy high scores into the managed list.
    InformationThis is used to populate a high score list when your game is first installed.

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

    Function AllowINIHash( allow:Int = True )
    DescriptionTell the application to hash the ini values when they are written to disc.
    InformationIn 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 )
    DescriptionRandomise the INI hash to your app specific seed.
    InformationThis 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 ( )
    DescriptionTurn off application profiling.

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

    Function EnableProfiling ( outfile:String )
    DescriptionTurn on application profiling.

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

    Function ExitProfileSection ( name:String )
    DescriptionExit a section of code to be profiled.
    InformationThe 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 )
    ReturnsThe score name.
    DescriptionGet the score value from the group and index.
    InformationIt's important that the score group is fully populated before you try and access it!

    Function GetHighScoreValue:Long ( iGroupID:Int, iScoreID:Int )
    ReturnsThe score value.
    DescriptionGet the score value from the group and index.
    InformationIt'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 )
    ReturnsIf there's an entry matching the name, the entry value, otherwise the.
    DescriptionRetrieve the value of an INI entry.

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

    Function isFullscreen:Int ()
    ReturnsWhether the app is running in windowed or fullscreen mode.
    DescriptionCheck if the current app is running fullscreen.
    InformationThis 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 )
    DescriptionLoad the GUI configuration.
    InformationA GUI config file defines what bitmap fonts to load, the mouse pointer images and any predefined buttons.

    Function LoadLocaleStrings( file:String )
    DescriptionLoad the locale strings.

    Function localeString:String ( key:String )
    ReturnsThe string value if successful, otherwise a lengthy error message string.
    DescriptionFind the locale string matching this name.
    InformationThe 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 )
    DescriptionAlpha blends two 32 bit ARGB pixels together.
    InformationUseful when overlaying one alpha'd image onto another.

    Function mbm_FrameworkInfo:String ()
    DescriptionRetrieve the framework name and version number.
    InformationUseful for displaying which version of the framework your game was built against.

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

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

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

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

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

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

    Function RunApp ()
    DescriptionRun the application.
    InformationRun the application. Application behaviour will depend on the number and types of registered AppModules.

    Function SetINIHash( hash$ )
    DescriptionProvide a unique hash string.
    InformationThis 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 )
    DescriptionSet the value of an INI entry.
    InformationThis 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 ()
    DescriptionWrite the INI file to disc.
    InformationA 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
    DescriptionThe base sprite type.
    InformationYou 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 )
    DescriptionAdd a new animation frame at the end of the current frames.
    InformationTo be used for procedurally generated MasterSprites.
    Method AnimationTime:Float ()
    InformationThe running time of the bitmap animations.
    Method CurrentFrame:Int ()
    InformationThe current animation bitmap frame, in the range 0 to TotalFrames - 1.
    Method Draw( timeMS:Int = 0 )
    DescriptionDraw the sprite.
    InformationThe sprites animation can also be updated by supplying a valid delta time.
    Method DrawDirect( fX:Float, fY:Float, timeMS:Int = 0 )
    DescriptionDraw the sprite at the supplied screen position.
    InformationThis 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 )
    DescriptionDraw the sprite with the current render settings (scale, alpha, rotation etc)
    InformationThis function ignores the sprites internal settings, useful for manual control of rendering a specific frame in a specifc way.
    Method GetAlpha:Float()
    DescriptionGet the sprites alpha value.
    Method GetPosition( x:Float Var, y:Float Var )
    DescriptionGet the sprite screen position.
    Method GetRotation:Float()
    DescriptionGet the sprites rotation.
    Method GetScale:Float()
    DescriptionGet the sprites scale.
    Method GetX:Float ()
    DescriptionGet the sprites screen position in X.
    Method GetY:Float ()
    DescriptionGet the sprites screen position in Y.
    Method Image:TImage ()
    DescriptionGet the sprites current image.
    InformationFor animated sprites, the image will be the one relating to the current animation time.
    Method RandomizeTime()
    DescriptionSets the animation time somewhere bewteen 0 and the total animation time.
    Method ResetTime()
    DescriptionPuts the sprite animation time back to zero.
    Method SetAlpha( a:Float )
    DescriptionSet the sprite alpha.
    InformationThis vale can also be affected by any animators that are running.
    Method SetFrame( frame:Int )
    InformationManually select a frame for the current sprite.
    Method SetPosition( x:Float, y:Float )
    DescriptionSet the sprite screen position.
    InformationThis position can also be affected by any animators that are running.
    Method SetRotation( r:Float )
    DescriptionSet the sprite rotation.
    InformationThis value can also be affected by any animators that are running.
    Method SetScale( s:Float )
    DescriptionSet the sprite scale.
    InformationThis value can also be affected by any animators that are running.
    Method SetX( x:Float )
    DescriptionSet the sprites screen position in X.
    InformationThis position can also be affected by any animators that are running.
    Method SetY( y:Float )
    DescriptionSet the sprites screen position in Y.
    InformationThis position can also be affected by any animators that are running.
    Method TotalFrames:Int ()
    InformationThe total number of bitmap frames in the animation.
    Method Update( timeMS:Int )
    DescriptionUpdate the sprite animation with a float based delta time (0.001 * millisecs_elapsed)

    Type Animator
    DescriptionAnimator.
    InformationA 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 ()
    ReturnsA new animator object.
    DescriptionDuplicate.
    InformationCreates a duplicate animator so it may have it's own delta time etc.
    Method HasExpired:Int ()
    ReturnsTRUE if the animator has indeed _expired, otherwise FALSE.
    DescriptionChecks to see if an animator has ran it's course.
    InformationNot all animators will expire. Bouncing animators with perfect bounyness, linear interpolators set to repeat etc, will basically run forever.
    Method Restart ()
    DescriptionResets an animator to it's original state and starts it going.
    Method Update( timeMS:Int )
    DescriptionUpdate the animtor with the current time delta.
    Method Value:Float()
    DescriptionGet the current value of the Animator.
    Function CreateAcclBrake:Animator( fStart:Float, fStartSpeed:Float, fEnd:Float, fBrakingPoint:Float, fAcceleration:Float, fMaxVelocity:Float, playOnce:Int = False )
    ReturnsA new animator object.
    DescriptionCreate a accelerating and braking Animator.
    InformationThis 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 )
    ReturnsA new animator object.
    DescriptionCreate a bouncing Animator.
    InformationThe 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 )
    ReturnsA new animator object.
    DescriptionCreate a custom Animator.
    Function CreateLERP:Animator ( fStart:Float, fSpeed:Float, fEnd:Float, reverse:Int, playOnce:Int = False )
    ReturnsA new animator object.
    DescriptionCreate a linear interpolation Animator.
    InformationLinear 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 )
    ReturnsA new animator object.
    DescriptionCreate a Sine curve based Animator.
    InformationThe current value is always between fStart and fStart + (fMagnitude * 2)
    Function Load:Animator( inFile:TStream, stop:String )
    ReturnsA new animator object.
    DescriptionLoads an animator from a current open stream.
    InformationAnimators 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 TypeParameters
    Linear Interpolatedata0 = start point, data1 = speed, data2 = end point, data3 = reverse flag, script = lerp
    Sin curvedata0 = start point, data1 = frequency, data2 = magnitude, script = sine
    Bouncedata0 = start point, data1 = start vector, data2 = floor value, data3 = bounce fall off (bounciness), data4 = gravity, script = bounce
    Accelerate and brakedata0 = 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
    DescriptionAppModule.
    InformationThe 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 )
    DescriptionAdd a new image to the systems list of reference counted bitmaps.
    InformationBitmaps 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 )
    DescriptionGet a constant value cast to a float.
    InformationSee ConstString.
    Method ConstInt:Int ( name:String )
    DescriptionGet a constant value cast to an integer.
    InformationSee ConstString.
    Method ConstString:String( name:String )
    ReturnsIf a matching constant exists, the constant value. In DEBUG builds,
    DescriptionGet a constant string value.
    Method CreateMasterSprite:MasterSprite ( name:String )
    DescriptionCreate a new, empty MasterSprite for manual creation.
    InformationThis is used for procedurally generating sprites. Once created you must AddFrames to it before it can be drawn.
    Method DestroyModule( iID:Int )
    Method DestroyScreenGrabImage()
    DescriptionDestroy the grabbed image and attempt to free the VRAM it occupied.
    Method Draw ()
    DescriptionA method that should be overidden in the derived types.
    InformationCalled 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 )
    ReturnsA valid TSound if a matching resource exists, otherwise NULL.
    DescriptionFind and return a sound resource by name.
    InformationSounds are defined in the resource script as "SOUND name = value" eg "SOUND boom = data\sounds\boom.wav"
    Method GetSprite:MasterSprite( name:String )
    ReturnsA valid MasterSprite if a matching resource exists, or NULL.
    DescriptionFind and return a Sprite resource by name.
    InformationLike 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 )
    ReturnsTRUE if a matching button was hit during the last GUI Update.
    DescriptionCheck for a GUI button hit beginning with this name.
    InformationIf 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 )
    ReturnsTRUE if the button was hit during the last GUI Update.
    DescriptionCheck for a GUI button hit.
    InformationIt'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 )
    ReturnsTRUE if the button was hit during the last GUI Update.
    DescriptionCheck for a GUI button hit.
    InformationIt'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 )
    DescriptionInform the AppModule if it should clear out it's loaded songs.
    InformationTo 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 )
    DescriptionLoad a new particle emitter.
    InformationManually load particle emitter, instead of loading via a resource script.
    Method LoadingNotify:Int ( file:String )
    DescriptionAn overridable function called each time a resource is loaded via a resource script.
    InformationThis 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 ( )
    DescriptionA Method that can be overridden by the derived types.
    InformationCalled 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 )
    DescriptionLoad a new sound resource.
    InformationManually load a new sound resource, instead of loading via a resource script.
    Method LoadSprite( name:String, file:String )
    DescriptionLoad a new sprite resource.
    InformationManually load a sprite resource, instead of loading a collection of resources via a resource script.
    Method LoadWindow( file:String )
    DescriptionLoad a new GUI window.
    InformationManually 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 )
    DescriptionLoad a new sprite resource in place of an existing one.
    InformationUseful for changing the look of a sprite without changing it's resource name, for example different player characters or background images.
    Method screenGrab:TImage ()
    DescriptionPerform a screen grab and return the resulting image.
    InformationThis 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 )
    DescriptionA method that should be overidden in the derived types (if needed).
    InformationCalled 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 ()
    DescriptionReturns the current Frames Per Second.
    InformationThe frames per second value is automatically updated every two seconds.
    Function FrameDelta:Float ()
    Informationreturns:
    Function GetMusicVolume:Float ()
    DescriptionGet the current application preference music volume level.
    Informationreturns: A float in the range 0.0 to 1.0.
    Function GetSoundVolume:Float ()
    DescriptionGet the current application preference sound volume.
    Informationreturns: A float in the Range 0.0 to 1.0.
    Function GetVolumeSliderPosition:Float ( windowName:String , controlName:String )
    DescriptionGets a Volume level from a GUI slider.
    Function LastMS:Int ()
    Informationreturns:
    Function PlayerProfileName:String ( userID:Int )
    Function PopulatePlayerProfileList()
    Function RemoveUser( userID:Int )
    Function ScreenshotKey( key:Int )
    DescriptionTell the app which key autosaves a screen shot (Default = F10)
    InformationSet the key to NULL to prevent saving screenshots.
    Function SelectUser( userID:Int )
    Function SetMusicVolume ( fVolume:Float )
    DescriptionSet the current application preference music volume.
    InformationThis sets the volume level as well as writing the value to the current ini file (if available).
    Function SetSoundVolume ( fVolume:Float )
    DescriptionSet the current application preference sound volume.
    InformationThis 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 )
    DescriptionSets a GUI slider position according to a volume value.
    Function ToggleFullscreen()
    Function UpdateFullscreenButton( windowName:String , controlName:String )
    DescriptionSets the toggle value of a button according to the status of the application.
    InformationUsed when showing an options form, so that the button matches the app state.
    Function UpdateFullscreenFromButton( windowName:String , controlName:String )
    DescriptionChecks a toggle button state and adjusts the fullscreen status.
    InformationIf 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
    DescriptionMasterSprite.
    InformationUsed 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 ()
    ReturnsA new Sprite object.
    DescriptionCreate and instance of a MasterSprite.
    InformationReturns 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()
    DescriptionDestroy a MasterSprite object.
    InformationIf 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 )
    ReturnsA new MasterSprite object.
    DescriptionCreate a MasterSprite from a file or series of files.
    InformationThe 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
    DescriptionA 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 )
    DescriptionEmit new particles at the specified screen coordinates.
    InformationParticle 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()
    DescriptionDraw the particle emitter.
    Method LiveCount:Int ()
    DescriptionGet the number of particles the emitter has.
    InformationLive particles are those that are drawn and updated.
    Method SetDirection( a:Float )
    DescriptionSet the angular direction of the emitter.
    InformationFor emitters that have a defined cone angle, this sets the direction of that cone ready for the next DoBurst call.

    Type scaleFader
    DescriptionA 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()
    DescriptionClear 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 )
    ReturnsThe new effect, but it's not really needed as it's added to a internal list.
    DescriptionCreate a new scaling / fading effect.
    Function Draw( Xoffset:Float, Yoffset:Float )
    DescriptionDraw all the effects.
    Function LiveCount:Int ()
    DescriptionGet how many effects are alive.
    Function Update( timeMS:Int )
    DescriptionUpdate all the faders in the managed list.

    Type Sprite Extends _mbm_BaseSprite
    InformationUsed 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 )
    DescriptionCreateInstance.
    InformationAn alternative to calling the CreateInstance method.

    Type SpriteList
    InformationUsed 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
    DescriptionThe list of 'free' sprites.
    InformationFree sprites are those that are sitting in reserve waiting to be called into action.
    Field live:TList
    DescriptionThe list of 'live' sprites.
    InformationLive sprites are Updated and Drawn.
    Method Draw()
    DescriptionDraw all the live sprites.
    Method FreeCount:Int ()
    DescriptionGet the number of free sprites available.
    Method FreeList:TList ()
    DescriptionRetrieve the list of 'free' sprites.
    Method Kill ( s:Sprite )
    DescriptionKill a sprite so it can be re-used.
    InformationThis 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 ()
    DescriptionRetrieve the list of 'live' sprites.
    Method NextFree:Sprite( forceRenew:Int = False )
    DescriptionGet a new sprite from the 'free' list.
    InformationThe 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 )
    DescriptionUpdate the animation of the live sprites.
    Function Create:SpriteList( master:MasterSprite, count:Int )
    DescriptionCreate a new sprite list from the supplied MasterSprite.
    InformationSpecify how many sprite instances are to be made with the count flag.

    Type TBMFont
    DescriptionType TBMFont.
    InformationBitmap 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
    DescriptionSets the horizontal text alignment.
    InformationThis can be ALIGN_LEFT (default), ALIGN_CENTER or ALIGN_RIGHT.
    Field CallBackChars: String
    DescriptionString of characters that generate a callback.
    InformationThis can be used for control characters that change the color or offset (dx, dy).
    Field HSpacing: Float
    DescriptionHorizontal spacing in pixels.
    InformationThis can be used to add extra spacing between characters.
    Field Kerning: Int
    DescriptionSets whether kerning should be used or not (on by default if FNT file has kerning).
    InformationKerning adjusts the distance between certain pairs of characters.
    Field Shadow: Int
    DescriptionSets whether the shadow should be drawn (use CreateShadow to create the shadow first).
    Field ShadowX: Int
    DescriptionHorizontal shadow offset.
    InformationRelative to the text.
    Field ShadowY: Int
    DescriptionVertical shadow offset.
    InformationRelative to the text.
    Field SkipChars: String
    DescriptionString of characters that should not be drawn.
    InformationThis can be used for control characters.
    Field VSpacing: Float
    DescriptionVertical spacing in pixels.
    InformationThis can be used to add extra spacing between lines.
    Method ApplyTexture (Tex: TImage)
    DescriptionAdds a texture to the font.
    InformationParameters:
    • Tex: The texture image or NULL to reset
    Method CreateShadow (ShadowBlur: Float = 3, Amount: Int = 255)
    DescriptionCreates a soft shadow of the bitmap font (position can be set with ShadowX and ShadowY). WARNING: CreateShadow uses the backbuffer!
    InformationParameters:
    • 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)
    DescriptionDraws the text using the bitmap font characters using the current values for Align, Shadow, ShadowX, ShadowY, HSpacing, VSpacing and Kerning.
    InformationParameters:
    • Text: The string (can have multiple lines)
    • XPos: Tye X position (center position for ALIGN_CENTER)
    • YPos: The Y position
    Method EnableCustomTexture (Value: Int)
    DescriptionSwitches custom textures on or off.
    InformationParameters:
    • Value: True for custom texture, False for no texture.
    Method Init (Prefix: String, FNTFile: String)
    DescriptionInitializes a new TBMFont object from a binary .fnt file.
    InformationParameters:
    • 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)
    DescriptionCallback function that is called before drawing a character that occurs in the string CallBackChars.
    InformationParameters:
    • Char: The character that is about to be drawn
    • X: The X position
    • Y: The Y position
    Method TextHeight: Float (Text: String)
    DescriptionReturns the height of a string in pixels using the current scale.
    InformationParameters:
    • Text: The string (can have multiple lines)
    Method TextWidth: Float (Text: String, Line: Int = -1)
    DescriptionReturns the width of a string in pixels using the current scale.
    InformationParameters:
    • Text: The string (can have multiple lines)
    • Line=-1: If supplied, TextWidth only counts this line
    Function Create: TBMFont (Prefix: String, FNTFile: String)
    DescriptionCreates a new TBMFont object from a binary .fnt file.
    InformationParameters:
    • 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

    AuthorMatt (matibee) Bennett but contains code by others, see below...
    Version1.7
    LicenseThis 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
    Historyv1.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).
    Historyv1.6 5th March 2010 - New functionality added for procedurally generated sprites and custom animation scripts.
    Historyv1.5 25th February 2010 - Several minor updates.
    Historyv1.4 18th February 2010 - More sprite functionality added.
    Historyv1.3 15th February 2010 - More particle system functionality added.
    Historyv1.2 10th February 2010 - Profiler added, some minor fixes.
    Historyv1.1 3rd February 2010 - Major fixes to BMFont to make it work under DX9
    Historyv1.0 31st January 2010 - First non-beta public release
    Historyv0.1 January 2010 - First release
    Bitmap fontsOriginal code; Mike Wierings' BMFont Mod.. www.wieringsoftware.nl/blitz/
    Other codeGrey Alien's Folder Access code for Vista & up... http://www.blitzbasic.com/Community/posts.php?topic=73305#819232