Introduction

Changes since last version

Scripts

Advanced searches

Special variables

Database format

Faster searches, other formats and formulas

The Database Creator Program

Introduction:

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 complicated 'if' statements. Also in this version you can fully customise your database files through advanced and easy to use scripts that enable you to change any information in your database in-game.

Some examples of how this could be useful are:

• Your own highscore table - You could have it store the name, level, score, difficulty, etc. and even let the players choose how many spaces there are.
   
• Preferences - The database support is excellent for storing changable controls and other preferences, such as difficulty, speed, etc.
   
• AI lookups - You could have all your AI (artificial intelligence) in a database and get it to go to a certain cell that matches the criteria (criteria in table/row/column names), in the cell could be the command of what to do/where to move next. Although this'll usually need to be loaded into an array for fast access as explained later on.
   
• Specs - If you have [for instance] a lot of weapons with different specs then you could put them all into a database and make it look up the weapon that the player is using when you need to.
   
• Level editors - You could make the level editor create databases, all the custom levels could be stored in one file and you'd be able to make it store what object to create, where, and what variables to declare/change to it.
   
• Shops - You could use the database to store all items that each shop has in stock (and their specs) and add/delete them whenever you like.

Remember you can execute a string by using the execute_string(string) function (very useful).

Changes since last version:

Since version 2.2:

• A major bug in one of the scripts was fixed. It was either ins_table_direct or array_table, or perhaps insert_array, I can't actually remember! Anyway, they all work fine now.
• I made a whole load of examples. Hope you like them!

Since version 2.1:

• The bug that means you can't change a cell to '0' in lookup_direct has been fixed as it now checks arguments properly to check if they're string/real.
• The searches are now much more user-friendly.
• The checking against the z/x/y names as commands against variables has been taken out as it's useless and complicates matters.
• -1 is now returned if any of the scripts fail for any reason.

Since version 2.0:

• Some major bugs have been fixed, especially in the ins_table_direct script.
• You can now give the number columns and rows in the ins_table_direct script.
• A database_create script has been added.

Since version 1.0:

• It's all been totally redone, the old tables are not compatible.
• Several tables can now be stored in one file.
• Encryption is supported.
• The searches can be more advanced.
• You can now lookup table/column/row names.
• You can now change cells (you can change anything you can lookup).
• You can now add additional tables/columns/rows from code.
• You can pull any table out of the database file and store them in a 2D array for faster access.
• And many more new functions are also included (including loading the array back into the file).

Scripts

Several scripts have been produced to enable you to edit the database file in almost any way, you only need to add the ones you're going to use. The encryption script will need to be included even if you aren't using it, although you only need to leave it blank in that case as it won't be called upon.

The scripts you're using will need to be copied and pasted into a script from the script menu of GM. Alternatively you can select import scripts from the file menu and load the database script file containing all the scripts.

To call the scripts use the format as shown below. You can call a script at any time during the game.
Eg. to set the variable jeff to the value of the 4th column, 3rd row, in the 1st table of database file data.txt use:

jeff=lookup_direct('data.txt',1,4,3)

The format shows you what each argument is for and the field types are the type of value that can be entered.

Argument types is the type of argument required; string, real or adv.

Adv means it uses the advanced search (see advanced searches section).

If any of the scripts fail they return -1.

lookup_direct
encryption
insert_direct
ins_table_direct
convert_direct
array_table
array_search
insert_array
database_create

lookup_direct:
format: lookup_direct(file_name,z,x,y,change_to)
argument types: lookup_direct(string,adv,adv,adv,string)

This script is the main one, it enables you to check a database directly (from the file) and return/change the info of any cell in that database.

• file_name is the path or filename of the database file.
• z is the table position in the file.
• x is the column position in that table.
• y is the row position in that table.
• change_to is the new value you wish to put in the cell. If a string is put in change_to then the cell is changed to this string. If a real is put in change_to or no value at all then the script just returns the value of the z, x, y cell.

0 can be entered for x/y to make it check for the name of that row/col (see last section). If 0 is put for both x and y then it'll return the name of that table.
This script returns the value of the cell in table z, column x, row y. If the value is a number it returns it as a real value, if the value has any non numbers in it it's returned as a string.

encryption:
format: encryption(string,encrypt?)
argument types: encryption(string,true/false)

There's no need for you to know about this script when using the database support, the other scripts will call this one themselves when they need it. Details of this script are only included so you know how to use it if you want to encrypt a string of your own for another reason.

• string is the string in which to encrypt.
• encrypt? is if to encrypt the string of decrypt it. True/1=encrypt, false/0=decrypt.

You could use this script for encryption on anything else you want encrypted as well.
It doesn't encrypt all the characters, it misses some out at certain intervals which makes it quicker and more confusing to manually decrypt.

insert_direct:
format: insert_direct(file_name,z,pos,row/col,make/del)
argument types: insert_direct(string,adv,real,true/false,true/false)

This script creates/deletes columns/rows.

• file_name is the path or filename of the database file.
• z is the table position in the file.
• pos is the position along to insert/delete the row/column, eg. 2 would mean the second row/column.
• row/col means whether it's a row or a column you're wanting to create/delete. True/1=row, false/0=column.
• make/del is if you want to create a new row/column here or delete the current one. True/1=create, false/0=delete.

The cells inserted are all blank so you'll need to use the lookup_direct script to change them.

ins_table_direct:
format: ins_table_direct(file_name,pos(z),make/del,cols,rows)
argument types: ins_table_direct(string,real,true/false,real,real)

This inserts a blank cols*rows table at position pos, you'll need to edit the cells.

• file_name is the path or filename of the database file.
• pos(z) is the position along to insert/delete the table at, eg. 3 would mean the third table.
• make/del is if to create or delete this table. True/1=create, false/0=delete.
• cols is how many columns to create in this new table. This argument isn't used if you're deleting the table.
• rows is how many rows to create in this new table. This argument isn't used if you're deleting the table.

convert_direct:
format: convert_direct(file_name,encrypt?)
argument types: convert_direct(string,true/false)

This script converts the whole database file between encryptions.

• file_name is the path or filename of the database file.
• encrypt? is if to encrypt the file of decrypt it. True/1=encrypt, false/0=decrypt.

This script may be useful to decrypt the whole file at the start of the game and encrypt it again at the end, then when you come to use the other scripts they'll run much faster as they won't have to decrypt each line they want to read on the spot.

array_table:
format: array_table(file_name,z,var,write)
argument types: array_table(string,adv,string,true/false)

This script either puts a table into a 2D array or puts it back into a database.

• file_name is the path or filename of the database file.
• z is the position of the table you wish to extract/put back, eg. 4 would mean the forth table. When putting tables back into the database file this table is overwritten, you can use this to duplicate tables.
• var is the variable that it'll be put into/taken out of. The variable it's put into with x and y and the end contain the total x and y, eg. if var was 'bob' then 'bobx' would contain the total cols and 'boby' would contain the total rows. The names of the rows and columns are put into the 0 indexes and [0,0] contains the name of the table. See database format for more information.
• write is if to write it to the file or pull it out. True/1=write it to the file, false/0=extract it from the file.

array_search:
format: array_search(array_name,x,y,change_to)
argument types: array_search(string,adv,adv,string)

This script is similar to lookup_direct except it's used for arrays that have been created with the array_table script.
There's no point using this script if you're only putting numbers for both x and y, eg. if you want x3, y5 in the variable 'bob' it's located at bob[3,5].

• array_name is the name of the variable to search in (as a string).
• x is the column position in that table.
• y is the row position in that table.
• change_to is the new value you wish to put in the cell. If a string is put in change_to then the cell is changed to this string. If a real is put in change_to or no value at all then the script just returns the value of the z, x, y cell.

insert_array:
format: insert_array(array_name,pos,row/col,make/del)
argument types: insert_array(string,real,true/false,true/false)

This script is similar to insert_direct except it's used for arrays.

• array_name is the name of the variable to search in (as a string).
• pos is the position along to insert/delete the row/column, eg. 2 would mean the second row/column.
• row/col means whether it's a row or a column you're wanting to create/delete. True/1=row, false/0=column.
• make/del is if you want to create a new row/column here or delete the current one. True/1=create, false/0=delete.

database_create:
format: database_create(file_name,tables,cols,rows)
argument types: database_create(string,real,real,real)

This script creates (or wipes) a blank database file.

• file_name is the path or filename of the database file to create.
• tables is the number of tables to create.
• cols is the number of columns each table will have.
• rows is the number of rows each table will have.

Advanced searches:

Many of the scripts support advanced searches, meaning you can use various different methods for finding the result you're looking for. These have recently been updated as the last advanced functions were pretty complicated for no good reason.

1. If a number greater than or equal to 0 is entered then it jumps straight to that number along. eg. 5 means the fifth table/row/column.
2. If a string is entered then it goes to the first table/row/column with that name (case sensitive).
3. If -1 is entered then it executes each name of the table/row/column as a command to see if it's true and the first that is is where it jumps to.
4. If -2 is entered then it executes each name of the table/row/column as a command to see if it's false and the first that is is where it jumps to.

Special variables:

After you use most of the scripts there will be certain variables that have been defined for the script's use that you may find useful.

• encrypttq - Whether the database is encrypted or not (true/false).
• tottablesq - How many tables are in the database.
• maxxq - The number of columns in the table you were looking at.
• maxyq - The number of rows in the table you were looking at.
• pathz - The z position from where the result was found.
• pathx - The x position from where the result was found.
• pathy - The y position from where the result was found.

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 now a database creator program to create database files (www.users.waitrose.com/~4sythe/database_setup.exe) but if you wish to do it manually in notepad the format looks like this:

Encrypted (0/1 - 0=no, 1=yes. Everything past here will be encrypted if true)
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.

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

0
3
{1}Table1{2}Second table{3}The third one{4}
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}

That would be a working decrypted database with 3 tables. The tables are called 'Table1', 'Second table' and 'The third one'.

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

Faster Searches, other formats and formulas:

To speed up the scripts:
Don't use encryption (or decrypt the whole file when the game starts and encrypt is again at the end).
Use positive numbers for the advanced checks.
For on-the-fly checking load the required table into an array.

Unfortunately it's not possible to use a program other than my database creator (or manual typing) to create databases. Both Exel and Lotus 1,2,3 use machine code to save their spreadsheets and their text saves are of such low quality that any program gets confused trying to import them. My format is the fastest for GM.

Formulas were also requested but I've come to the conclusion that they too would be impossible. The database stores independent information, you use programming for stuff like that. If you think about it, how am I supposed to incorporate formulas into those scripts? It would require several repeatedly useless checks which would be hell to program and store when it's loaded into arrays and things, then all they would do is take ages to work themselves out (this is directly from the file, not stored in memory). All that can be very simply done if you know exactly what you need to check for your game, with code.
If you are desperate for a formula and can't program (although you need a bit to use these things anyway) then you could put something like temp=lookup_direct('data.txt',1,2,3)*lookup_direct('data.txt',3,2,1) in a cell and execute it when you check for it. Temp would then contain the answer you'd like.

The Database Creator Program:

I've created a database creator program so you can easily create database files to use with these scripts.

You can download it here: http://www.users.waitrose.com/~4sythe/database_setup.exe

The program is a little slow with large files. I'm going to update it when version 5.0 of Game Maker comes out, until then you'll have to put up with this. Make sure you read the help before you use it as it explains everything you can do with the program.

The only major bug I know of is when you create new rows and columns by clicking on the total row and column numbers in the top right hand corner, all the new rows/columns have a value of 0. You'll need to change this value of 0 before you can save the table as these are real values, not string, and so can't be written into the database file.