BlitzMax Game Framework FAQ V1.06 (Technical)
Index
Q. What do I compile to run the AOTMG mini-game demo?
Q. What does the AOTMG.ini file do?
Q. If I have several files open at once, how can I get the IDE to always compile AOTMG.bmx?
Q. Why is the Include folder outside of the AOTMG folder?
Q. Why is GameTypes.bmx not in the Include folder?
Q. How can skip all the intros and screen fades so that I can test the code faster?
Q. Why is VSync off by default instead of on?
Q. Why do I get a funny little black window behind the game window in windowed mode?
Q. How do I make a icon which is automatically included in the exe?
Q. How do I make icons that are anti-aliased to a transparent background?
Q. Why do I need a .ico (icon) file?
Q. What module tweaks do I need to make for perfect VSync in windowed mode?
Q. How can I enable Build Modules in the IDE?
Q. What is "Vertical Tearing"?
Q. What causes jerkiness?
Q. What do I compile to run the AOTMG mini-game demo?
A. The main example source you compile is in the AOTMG folder and is called AOTMG.bmx.
Q. What does the AOTMG.ini file do?
A. The AOTMG.ini file can be edited with Notepad and controls
several aspects of the game as follows:
Set FULL SCREEN to 0 if you want the game to start in windowed mode instead of full screen mode.
You can disable music, sounds and speech by changing the corresponding flags to 0.
You can set the music, sound and speech volumes to values from 0-100.
Set FADE to 0 to skip the intro and to bypass screen fades.
Change PARTICLES from 0 to 100 in increments of 10 to change the amount of explosion particles drawn in-game.
You may need to change this setting to a lower number on slower PCs. (This flag is not currently active)Set PORTAL SPLASH to 0 to skip the portal splash screen.
INTRO doesn't do anything in AOTMG but you might use it for your own games.
Change VSYNC to 1 for a smoother display on some systems. Note
that it may look worse on some systems.Set DRIVER to 0 (DirectX) or 1 (OpenGL).
Change SOUND DRIVER from FreeAudio to OpenAL Generic Software or DirectSound if you want to try out different sound drivers.
FULL SCREEN PROCESS PRIORITY, FULL SCREEN THREAD PRIORITY, WINDOWED PROCESS PRIORITY, and WINDOWED THREAD PRIORITY control the game priority in Windows. By default these values are set to 0 (normal) but you can boost them to 1 or 2 if you want. A good setting is 1 on all flags; this will help if other windows programs are hogging too much CPU time. However, a value of 1 for the PROCESS flags is not supported in Windows 95/98/ME; nothing will happen. Also a value of 2 for the PROCESS flags may make the OS unstable. Please see ccSetPriority in CommonCode.bmx for more information. Note that when the game is paused or suspended (minimised or loss of focus) that the thread priority will be returned to normal.
PROFILE NAME stores the name of the last profile used.
REGION is a flag that you can change if you want your game to do different things in different regions (e.g. display different languages).
Q. If I have several files open at once, how can I get the IDE to always compile AOTMG.bmx?
A. In the IDE, open up all the files you need, then click on AOTMG.bmx. Then click Program/Lock Build File. This means that when you compile (with F5 or whatever), it will always compile AOTMG.bmx, no matter what other file you are currently viewing. This is very useful because if you try to compile one of the other files, it won't compile because it's not a standalone piece of code; it depends upon the other files which are all included in the AOTMG.bmx file.
Q. Why is the Include folder outside of the AOTMG folder?
A. It's intentional that the Include folder is outside of the AOTMG folder so that when you make other games you can put their source code in a folder on the same level as the AOTMG folder; then you can use the same set of include statements at the top of your game code.
Q. Why is GameTypes.bmx not in the Include folder?
A. GameTypes.bmx contains types specific to AOTMG, which is why it's in the AOTMG folder instead of the Include folder. The Include folder is only for generic reusable code and types.
Q. How can skip all the intros and screen fades so that I can test the code faster?
A. Whereas all the splash screens and fading look cool, you'll want to switch them off when developing to save time. So go into AOTMG.ini and change FADE to 0 and PORTAL SPLASH to 0 (don't forget to re-enable them when you make a release version!) Also in AOTMG.bmx, find the line that says:
If Game.Fade Then GreyAlienSpash(Game.Sound)
and comment it out. This way, even if you enable FADE in the .ini file for testing, you won't have to watch the Grey Alien splash screen each time.
Q. Why is VSync on by default instead of off?
A. I did a lot of testing and found that VSync off worked on a wider range of PCs without jerking problems, even though a small amount of random vertical tearing is sometimes visible. However, VSync on simply looks better in my opinion. By all means try pressing V to toggle VSync on/off in-game. If you decide that you want VSync off in your game, just make sure VSYNC is 0 in the Default.ini file when you release the game. The user can also toggle VSync via the options page.
Q. Why do I get a funny little black window behind the game window in windowed mode?
A. In the BlitzMax IDE make sure that you have Program/Build Options/Build GUI App ticked,
otherwise you will get a little black console window appearing behind your game.Q. How do I make a icon which is automatically included in the exe?
A. Please follow this guide by Jim Brown. This is only suitable for Windows builds. A different process is required for Mac OSX builds.
Q. How do I make icons that are anti-aliased to a transparent background?
A. Use a professional paint package to make your icon, and save it as a 32-bit icon file with an 8-bit Alpha Channel. Then you can have an icon that is anti-aliased to a transparent background - this looks cool and professional. I think this only works in XP/Vista/MAC OSX though. So check to see what your icon looks like in Windows 98/Me/2000; it may only have a solid background.
Q. Why do I need a .ico (icon) file?
*** This is now obsolete because since V1.02 the framework grabs the icon directly from the .exe file (providing it contains an icon.) ***
A. Even though the AOTMG.bmx source code imports projecticon.o, this only makes the .exe and the task bar have an icon. To have an icon in the top left of windowed mode and on the Alt+Tab task switching screen, you need to make an .ico file with the same name as your .exe name and put it in the same folder.
Q. What module tweaks do I need to make for perfect VSync in windowed mode?
*** This is now obsolete because Blitz Research have fixed the module themselves. ***
A. In windowed mode, you may notice some vertical tearing. This is because BlitzMax does not perform any kind of waiting for vertical refresh even with Flip 1 or -1! Therefore if you toggle the Game Framework VSync option in windowed mode, you will not notice any difference. To obtain perfect VSync in windowed mode you have two choices as follows:
a) In CommonTypes.bmx look for the TGame.PostDraw() method. There is a comment about Skidracer's module tweak and a line of code commented out underneath. If you uncomment this line, ccVWait() will be called in windowed mode. This works well on some faster PCs but may result in a permanent tear somewhere near the top of the screen on slower PCs. The best solution is b) as follows.
b) You need to tweak two of BlitzMax's modules (until BRL apply this tweak themselves, if ever). Remember, until BRL apply these tweaks themselves (may require a Game Framework update), you'll have to tweak the modules again each time they do a release, because the changes will get overwritten when you Synchronise Modules. There is no way round this I'm afraid. This method gives a much better result than method a) because it doesn't seem to result in any permanent tears. Note that some cards are unable to wait for vertical refresh, or their drivers have VSync completely disabled; therefore these module tweaks will have no effect on such systems, unfortunately. The tweaks are as follows:
Go into the BlitzMax folder and press Ctrl+F for find.
Search for graphics.bmx and open it.
Move to line 359 (approx.) in Function Flip()
Find the line that says: _driver.Flip False
Change False to Sync
Save the module.
Go into the BlitzMax folder and press Ctrl+F for find.
Search for d3d7graphics.bmx and open it.
Move to line 380 (approx.) in TD3D7Device.Flip()
Find the line that says: PrimarySurface.Blt dest,BackBuffer,src,0,Null
Insert the following line before it: If sync<>0 Then ddraw.WaitForVerticalBlank DDWAITVB_BLOCKBEGIN,0
Save the module.
In the IDE click Program/Build Modules.
BlitzMax will rebuild the modules that have changed and any related modules.
That's it, Phew! Now test it out by going into windowed mode and toggling VSync On. Any vertical tearing should disappear.
Q. How can I enable Build Modules in the IDE?
A. You need to download and install MinGW and set/alter two environment variables. You can download MinGW from here (although you should probably check for a more up-to-date version via a Google search or check the BlitxMax forums). Then you need to do the following (in Windows XP):
- Exit the BlitzMax IDE.
- Go into Control Panel and open the System Properties. (Try holding the Windows key and tapping Pause/Break as a shortcut.)
- Click Advanced.
- Click Environment Variables.
- In top list (user variables) create a New one called MINGW and set it to the path of your MinGW installation directory (e.g. C:\mingw)
- Then Edit your PATH variable and add ;c:\mingw\bin on the end (alter the path if you installed MinGW elsewhere). Don't miss out the semi-colon at the start!
- If you don't have an existing PATH variable, then make one with the New button, but don't put a semi-colon on the front of the path.
- Click OK twice to close System Properties.
- Go back into the BlitzMax IDE and check that Build Modules is enabled.
Q. What is "Vertical Tearing"?
A. Please read the essay posted
here.Q. What causes jerkiness?
A. Please read the essay posted here.
LIMITED WARRANTY (Disclaimer of Warranty)
THIS SOFTWARE PACKAGE, SERVICE AND THE ACCOMPANYING FILES ARE SOLD
"AS IS" AND WITHOUT WARRANTIES AS TO PERFORMANCE OF
MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED OR
IMPLIED. ADDITIONALLY, NO WARRANTY OF FITNESS FOR A PARTICULAR
PURPOSE IS OFFERED. ANY LIABILITY OF THE SELLER WILL BE LIMITED
EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE. NO
OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE
LAW, JAKE BIRKETT COMPUTER SOLUTIONS LTD, DISCLAIMS ALL OTHER
WARRANTIES AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING,
BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD
TO THE SOFTWARE, AND THE PROVISION OF OR FAILURE TO PROVIDE
SUPPORT SERVICES. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL
RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM COUNTRY/JURISDICTION
TO COUNTRY/JURISDICTION.LIMITATION OF LIABILITY
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT
SHALL JAKE BIRKETT COMPUTER SOLUTIONS LTD OR ITS SUPPLIERS BE
LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL
DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR
LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE
OF OR INABILITY TO USE THE SOFTWARE OR THE PROVISION OF OR FAILURE
TO PROVIDE SUPPORT SERVICES, EVEN IF JAKE BIRKETT COMPUTER
SOLUTIONS LTD HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
IN ANY CASE, JAKE BIRKETT COMPUTER SOLUTIONS LTD'S ENTIRE
LIABILITY UNDER ANY PROVISION OF THIS EULA SHALL BE LIMITED TO THE
GREATER OF THE AMOUNT ACTUALLY PAID BY YOU FOR THE JAKE BIRKETT
COMPUTER SOLUTIONS LTD PACKAGE OR £5.00 GBP. BECAUSE SOME
COUNTRIES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR
LIMITATION OF LIABILITY, THE ABOVE LIMITATION MAY NOT APPLY TO
YOU.