- Title: gQuery Crash Course
- Description: Brief tutorial on using the gQuery Standard Library
- GM Version: :GM8:
- Registered: Yes
- File Type: .gm81, .gml
- File Size: 15kb
- File Link: Example | Library
- Extension:: gQuery
gQuery is a Standard Script Library for Game Maker that simplifies many tasks. It is written in pure GML and can be included safely with any project.
gQuery Installation:
- Download the latest gQuery .gml file.
- Open your current project.
- Click the "Scripts" menu at the top of the GM IDE.
- Click Import Scripts.
- Select the .GML file and click Open.
gQuery Foreach:
gQuery introduces a for each loop into Game Maker. This syntax structure iterates through a list or file, setting each item or line to a variable for you to use inside the loop. The value is stored into a variable called "value", and the key (line number or item number) is stored inside the variable called "key". Suppose we have a list of player name stored in the variable playernames and we want to show each player name along with their place in the list. We first construct the foreach loop as such:
for(each(playernames) as key_value() ) show_message( string(key) + ": " + value )
The only part of this that ever changes in the "playernames" variable which could be any list you want, or a filename in string format. The foreach engine automatically opens and closes the file for you.
gQuery Simple Save:
gQuery includes a simple_x set of scripts which allow very simple saving/loading of variables between plays. Suppose you want to keep the score from the last time you opened the game, and load it into the new game, you would first check if you have played before and load the score if you have, then at the end of the game, you would save the new score. This is done like so:
Game Start:
if simple_exists("score")
score = simple_get("score")Game End:
simple_set("score",score)It works just like variables and is no-fuss. Keep in mind, the files are completely unencrypted. You can apply encryption using any encryption language just after saving, and just before loading you would unencrypt it. However, we at gQuery believe in allowing players to play single player games how they want, even if they want to cheat.
List Constructors:
gQuery comes with a few standard list constructors which all take a list as the first argument and return the list id back. Suppose you want a list of the numbers 1 to 5, you would run this code:
list = ds_list_range( ds_list_create(), 1, 5 )
Suppose you want to manually place several elements into a list, you would run this code:
names = ds_list( ds_list_create(), "Dan", "Fred", "Billy" )
Finally, there are implode and explode constructors, which will either combine all elements in a list into a string separated by some delimiter, or read all values from a string into an array separated by some delimiter. This example will fill a list with all the words in the sentence provided by using a space as the delimiter:
list = ds_list_explode( ds_list_create(), " ", "Hello my name is Bob" )
This example will construct a sentence from a list, separating each entry with a space.
sentence = ds_list_implode( wordlist, " " )
List Files
gQuery includes ds_list_to_file and ds_list_from_file. These two simple functions will quickly write all elements in a list to a given file (it overwrites!), or, read all of the lines in a file to a list, where each line is a separate entry. For example, to quickly write a list to "list.txt", you would run this code:
ds_list_to_file("list.txt",mylist)If you pass in a file handle instead of a file name, it will write to that file and not close it. This is helpful if you just want to APPEND a list to a file:
file = file_text_open_append("list.txt")
ds_list_to_file(file,mylist)
file_text_close(file)Then you can read a text file into a list with one simple function.
filelines = ds_list_from_file("file.txt",ds_list_create())gQuery List Sorting:
Suppose you have a list of names along with associated scores and you want to sort by scores, but keep the names in the right order, so that entry 1 in the Scores list matches entry 1 in the Names list. gQuery allows you to sort 1 list, and map the order of a second list in the same way that the first list was sorted, using ds_list_sort_assoc( sortinglist, copylist ). This is extremely useful functionality. Here is the above scenario in code:
ds_list_sort_assoc( scores, names )
gQuery gReal data type:
gQuery introduces a third data type into Game Maker called the gReal which lets you store several numbers into a single number and retrieve any of them later. This is much like an array, but can be passed around like a real. It stores the amount of values packed inside in the gReal data type itself (specifically, the first 14 bits). It can pack as many as 15 small numbers into a single gReal, and automatically assigns a certain amount of bits to each value, so the less you pack, the higher the numbers you can store. It only works with unsigned integers, so if you need negatives or decimals, you will have to subtract or multiply the values as you store them / retrieve them. To store your x and y coordinates into a gReal, you use:
coords = pack( floor( x ), floor( y ) )
Then to retrieve the x value, you unpack the gReal's 0th element (like arrays, gReals start at 0!)
x = unpack( coords, 0 )
You can also change a specific element in a gReal. To increase the x value by 1, I would do this:
coords = changebits( coords, 0, unpack( coords, 0 ) + 1 )
gReals are extremely useful in packing several values into every list element, for example, if you had a list of coordinates in 3D space, you could pack each x,y,z value into a single gReal and store the gReal's into a single list instead of 3 separate lists.
gQuery List Traversal:
gQuery provides several useful functions for traversing a list. First you can walk the list, applying a function to each of the elements. Note that the list index is fed to the callback function (along with the optional third argument), and then whatever that function returns is put into that index. Several callback functions are provided. For example, to square every element in a list, we use:
ds_list_walk( list, make_sqr )
If you provide a third argument, it will become the second argument in the callback function. Along with walking a list, you can filter a list, which simply deletes all elements who cause a function to return true when that element is passed to it. Again, there can be an optional argument. For example, gQuery comes with a "equalto" function, which takes the 2 arguments and returns true if they are equal. Thus, to filter out all "hello" strings from a list, you can do this:
ds_list_filter( list, equalto, "hello" )
To make a word filter, for example, you could write a callback function called "filter_swear_words", which takes a word and returns true if it is a swear word. You could explode the sentence, apply it to each element, then implode it back into a sentence, like so:
words = ds_list_explode( ds_list_create(), ' ', sentence ) ds_list_filter( words, filter_swear_words ) sentence = ds_list_implode( words, ' ' )
Don't forget to destroy the temporary list when you are done!
Summary
So thats the summary of the gQuery standard library. A few things should be noted: The foreach loop uses the variables key, and value, locally, so if you want to use the foreach loop, understand that the key and value variables are reserved for that instance. Also, you can not nest foreach loops, unless you have gQuery 1.1.1, which gave a second-level for each loop that stores the values into "key2" and "value2"; gQuery is a standard library and is easy to install without credit. It is open-source, which means it is constantly being updated and revised. You should feel free to use gQuery functions when answering questions for other users; gQuery provides readable and informational debug messages. To view those messages, run the game in Debug Mode, and open the Messages log. All messages beginning with gQ: are from gQuery; gQuery is based on the highly successful jQuery, and plans to use as many GM syntax quirks and tricks as possible to make it an invaluable tool for all GM coders; You can always find the latest version at www.danredux.com/gQuery/gQueryLatest.gml, and backwards-compatability is strived for, however, major version changes may not be compatible. For example, gQuery 2.0.4 may not be compatible with gQuery 1.7.5;
TAGS: GMCENGINE GMCSAVING GMCPROGRAMMING GMCGAMEMAKER
