GM Database Support - Introduction

GM Database Support v3.1.1 by Alasdair Forsythe (www.gmdatabase.co.uk)

Introduction

About

A database is a group of data stored in a structured way. In programming it can be useful for looking up information quickly from a large source without having to go through a massive script of 'if' statements. It's also useful for storing information that needs to still be accessible if the game is closed and opened again later (eg. highscores or preferences).

GM Database Support enables anyone to store any amount of information in tables, columns,and rows in a text file. The game can then call upon or edit this 'database file' in any way. This includes reading/modifying cells, inserting and removing tables, columns or rows, and even loading a table from the database file into an array for faster access, as well as many more less useful functions.

Don't worry if this sounds a bit complicated, no programming is required to use GM Database Support. The database support is all in scripts so you only have to call the scripts with specific arguments to perform any task to a database file. Eg. in the same way you would give the x, y and object index as arguments in the instance_create function you do the same with the database file, table, column and row in the lookup_direct database script to get the value of a cell in a database file. If you really are a beginner and this is still too complicated for you then I have created a drag-and-drop library with which you can use the GM Database Support scripts without any coding at all.

If you are not using encryption on your database file in a game then always remember you'll still need a blank script called 'encryption' for the game to run.

Use the data files ability of Game Maker 5 to store your database files. You can set it to extract them at the beginning of the game if they don't already exist.

To see some of the many uses for GM Database Support see the examples folder.

When not to use GM Database Support

When GM Database Support was first created it was created to fill in the gap for saving game information in an easy to handle way outside of Game Maker. Since then Game Maker has massively advanced and now includes many much better functions for storing data outside of the game, such as ini files and more advanced text and binary functions. Because these are all in-built functions of Game Maker they are easier to use and are much faster, so I really suggest that you use ini files in particular if possible.

For example, it would be more efficient to use ini files for saving preferences than GM Database Support.

Changes

Since version 3.1:

Bug fixed where file_close was used instead of file_text_close.

Since version 3.0:

The array scripts are faster as they now use the variables functions instead of execute_string function.
A bug was fixed in array_search so that strings are now written correctly into the array.
A bug was fixed in array_table that corrupted the database if update a table that has 0 columns or rows.
A couple of mistakes in the docs were corrected.
The file functions were updated to the new file_text functions.

Since version 2.3:

All the database scripts have been rewritten for Game Maker 5, they're much faster and use less memory.
A new script has been added: database_info. It gets information from database files like total tables and whether encrypted (special variables no longer work).
The scripts now support tables with 0 rows or columns (useful for an inventory system - see examples).
The ability to clear the contents of a table has been added to the ins_table_direct script.
The lookup_direct script will now always return a string even if the string just consists of numbers.
The column and row selection of the insert_direct script has been swapped round (1=column, 0=row).
A Random Encryption Script Creator has been added which creates encryption scripts that are different every time.
A new Database File Creator has been added which is much better and more stable than the previous one, it also supports the use of custom encryption scripts to encrypt the saved database files.
A library has been created for beginners (although it's not recommended - see library documentation).

Database Format

This section explains how to create the database files manually using notepad, the example of a working table is also a very good example of how the 'array_table' script extracts the tables into 2D arrays. The [1,2] bits are the indexes of the 2D array if the table was put into an array.

There's actaully no need to write to the database file manually using notepad anymore as the new Database File Creator will do this for you, but I've included this just so you know in case you do need to edit a database file manually.

Encrypted (0=no, >0=yes. Everything past here will be encrypted if greater than 0)
Total number of tables
{1}z name 1{2}z name 2{3} z name 3{4} etc.
totx,toty (first table total cols and rows separated by a comma)
Column names (same format as z names)
Row names (same format as z names)
Row 1 (x's in format as z names)
Row 2 (x's in format as z names)
etc.
totx,toty (second table total cols and rows separated by a comma)
etc.

The value of whether the database file is encrypted or not is actually the ID of the encryption script that has encrypted it. This was only done so that the Database File Creator knows which script to decrypt the file with, otherwise any value above 0 is treated the same.

So here's an example of what a working database file could look like:

0
4
{1}Table1{2}Second table{3}The third one{4}Empty Table{5}
2,2
{1}col1{2}col2{3}
{1}row1{2}row2{3}
{1}x1,y1{2}x2,y1{3}
{1}x1,y2{2}x2,y2{3}
1,1
{1}x>10{2}
{1}y>10{2}
{1}jeff=fred{2}
3,4
{1}jeff{2}bob{3}fred{4}
{1}bill{2}bernard{3}gertrude{4}alasdair{5}
{1}hey{2}people{3}how{4}
{1}good{2}that is{3}very{4}
{1}nice{2}of{3}you{4}
{1}to{2}say{3}so{4}
0,0

That would be a working decrypted database with 4 tables. The tables are called 'Table1', 'Second table', 'The third one' and 'Empty Table'. The last table has 0 columns and rows so nothing comes after the size of the table (as there's nothing in it).

This is what the 3rd table actually looks like (without the indexes displayed):

[0,0] The third one [1,0] jeff [2,0] bob [3,0] fred

[0,1] bill [1,1] hey [2,1] people [3.1.1] how

[0,2] bernard [1,2] good [2,2] that is [3,2] very

[0,3] gertrude [1,3] nice [2,3] of [3,3] you

[0,4] alasdair [1,4] to [2,4] say [3,4] so

Speed

If you wish to make the database scripts run faster you could try this:

Don't use encryption (or decrypt the whole file when the game starts and encrypt is again at the end). If your database file never has to be changed then I recommend adding it as a data file and extracting it at the start of the game to the temporary directory and working on it from there (see advanced RPG example).
Use positive numbers for the advanced checks instead of search by column or row name.
If you need to check, write to, or draw a value from a table at every step always load it into an array (array_table script) and work on it from there or face a drastic drop in game speed.

[0,0] The third one	[1,0] jeff	[2,0] bob	[3,0] fred
[0,1] bill	[1,1] hey	[2,1] people	[3.1.1] how
[0,2] bernard	[1,2] good	[2,2] that is	[3,2] very
[0,3] gertrude	[1,3] nice	[2,3] of	[3,3] you
[0,4] alasdair	[1,4] to	[2,4] say	[3,4] so