Game Maker Firebase Firestore

Game Maker Firebase Firestore extension allows you to do realtime database operations in the Firebase. With this extension, you can add/set/merge/get and query data in realtime. Powerful Google servers allow you to easily synchronize data between your players.

GAME MAKER FIRESTORE EXTENSION IS IN BETA PHASE AND IS BEING IMPROVED!

Setup Firebase Tools for Game Maker Studio

To be able to use the extension, you must prepare Game Maker Studio 2 to be able to compile for it. Click the link above to complete it.
For now, the extension only works at Android Exports.

DOCUMENTATION

firebase_firestore_init();
Description : Initializes Firestore Extensions.
Returns : N/A

firebase_firestore_debug_mode(TrueFalse debugMode);
Description
: Enables/Disables debug mode for the Firebase Extension
Returns : N/A

firebase_firestore_disable_network();
Description
: Prematurely disables network connection to the Firebase servers. This means that all the data you’ll query/write or anything you do, goes through your local database. All network operations are suspended.
Returns : A Social Async Event
[category] : “firestore_network_disabled” (string)
[status] : 0 (real)

firebase_firestore_enable_network();
Description
: Enables network connection to the Firebase servers. This means that all the data you’ll query/write or anything you do, goes through the online database first. If user has no internet connection, then the data will be written to the local database where it’ll be kept until the network connection is established. (This process is automatically handled by Firebase)
Returns : A Social Async Event
[category] : “firestore_network_disabled” (string)
[status] : 1 (real)

Writing Data

Creating Data Cache

To be able to write data to Firestore database, we must form a kind of Map(similar to ds_map). This map is then can be added to a collection, or merged with a document. You can change a documents values with this map as well.

All writing operations are real-time & online. If the user has no internet connection, then the data is written to a local database in your device. It’ll be synchronised and be sent to Firebase once the user becomes online.

firebase_firestore_write_begin();
Description
: Clears cache for writing data to Firebase. Must be used before writing data to Firebase.
Returns : N/A

firebase_firestore_write_begin();
firebase_firestore_write_string("album","Exile on Mainstream");
firebase_firestore_write_string("message","Can you tell me what was special about me all this time?");
firebase_firestore_write_double("length",3.30);
firebase_firestore_write_set("song_data/matchbox_twenty");

firebase_firestore_write_string(String key, String Value);
Description : Writes a string value to the cache. This process adds a value to a map working in the background.
Returns : N/A

firebase_firestore_write_double(String Key, Real Value);
Description
: Writes a double(number) value to the cache. This process adds a value to a map working in the background.
Returns : N/A

Sending Data to Database

After creating the Map with the functions above, we can now send the map to our database. The most used arguments here.
documentLocation : Location of the document (songFiles/queen_under_pressure)
collectionLocation : Location of the collection (songFiles)

firebase_firestore_write_set(String documentLocation);
Description
: Clears everything in the selected document and fills it with your Map.
Returns : Social Async Event
[category] : firestore_write_set (string)
[location] : Location of the collection (string)
[status] : 0 if fails, 1 if succeeded (real)
[error] : Description of error if status is 0 (string)

firebase_firestore_write_add(String collectionLocation);
Description
: Adds your Map into a collection. Notice that your document’s ID is automatically generated by Firebase. It is very useful for, like sending chat messages.
Returns : Social Async Event
[category] : firestore_write_add (string)
[location] : Location of the collection (string)
[status] : 0 if fails, 1 if succeeded (real)
[error] : Description of error if status is 0 (string)

firebase_firestore_write_merge(String documentLocation);
Personal Note : I really love this function!!!
Description : Merges your Map with a document. This means that if the existing document previously had some values, they are not deleted. Only the keys that tamper with the keys in your Map are changed.
Returns : Social Async Event
[category] : firestore_write_merge (string)
[location] : Location of the collection (string)
[status] : 0 if fails, 1 if succeeded (real)
[error] : Description of error if status is 0 (string)

Merge function can be used in many places. One example is: When users change their profile informations, they do not have to set all the data. They just have to send the pieces they changed. Therefore, the data sent/processed stays at minimun, allowing your app to perform better.

Reading Data

For simple & fast reading operations, I’ve created five functions to handle the task.

firebase_firestore_get_document(String documentLocation);
Description
: Simply reads a document from Firestore.
Returns : Social Async Event
[category] = firestore_get_document (String)
[location] = Location of the document or N/A[if failed] (String)
[id] = ID of the document (String)
[status] = 1 if successfully read, 0 if failed.
Additionally, all the keys the document are included in this event.

firebase_firestore_listen_document(String documentLocation);
Description : Reads a document and starts listening to it. This will fetch the document for you and starts listening to it. If anything changes in the document, it will be re-fetched again.
Returns : Listener Detach ID (real)
Returns : Social Async Event
[category] = firestore_get_document (String)
[location] = Location of the document or N/A[if failed] (String)
[id] = ID of the document (String)
[status] = 1 if successfully read, 0 if failed.
Additionally, all the keys the document are included in this event.

Everyime you read a document, a clock in the background ticks. Firebase, by default, grants you 50.000 document reads per day. It’s important for you to detach the listener once you’re done with it.

firebase_firestore_listener_detach(Real listenerDetachID);
Description
: Stops listening to a document/collection.

Querying Data

Perhaps the most important work of a database is querying. With the functions below, we can retrieve and fetch documents that we want. These functions basically filter the request we receive.

There are 4 CONSTANTS used in this section. You must use them in appropriate positions. firestore_datatype_string, firestore_datatype_double, firestore_order_ascending, firestore_order_descending
Don’t forget that you can combine more than one filter anytime you want.

firebase_firestore_query_create(String collectionLocation);
Description : Creates a query. Must be used before any other query functions.
Returns : N/A

firebase_firestore_query_equal_to(String key, String value, const dataType);
Description : Adds a query filter, “==” in Game Maker Studio, which indicates that we’ll be fetching documents which include key==value. DataType can be firestore_datatype_string or firestore_datatype_double
Returns : N/A

firebase_firestore_query_greater_than_or_equal_to(String key, Real val);
Description
: Adds a query filter, “>=” in Game Maker Studio, which indicates that we’ll be fetching documents which include key>=value.
Returns : N/A

firebase_firestore_query_less_than_or_equal_to(String key, Real val);
Description
: Adds a query filter, “<=” in Game Maker Studio.
Returns : N/A

firebase_firestore_query_greater_than(String key, Double val);
Description
: Adds a query filter “>” in Game Maker Studio.
Returns : N/A

firebase_firestore_query_less_than(String key, Double val);
Description
: Adds a query filter “<” in Game Maker Studio.
Returns : N/A

firebase_firestore_query_limit(Double limit);
Description : Limits the amount of document fetched. This means that if there are 10 documents that’s selected from your query filter, and you set limit to 5; only 5 documents will be fetched. Below functions also determine which of these limited will be fetched.
Returns : N/A

Below functions are experimental and still being improved. Use them with caution!

firebase_firestore_query_orderby(String key);
Description : Orders the results according to the key.

firebase_firestore_query_orderby_ext(String key, const orderDirection);
Description : Orders the results according to the key, plus with the option to form them in ASCENDING or DESCENDING order. (Use firestore_order_ascending or firestore_order_descending constants)

firebase_firestore_query_execute_get(String queryMark);
Description : Executes the query! Results will be retrieved soon. queryMark here is just a string value to remind you that which document belongs to which query.
Returns : A Social Async Event
[category] = firestore_query_document (String)
[query_mark] = queryMark value of the query (String)
[id] = ID of the document (String)
[status] = 1 if successfully read, 0 if failed.

firebase_firestore_query_create("best_players");
firebase_firestore_query_greater_than("score",100);
firebase_firestore_query_orderby("nickname");
firebase_firestore_query_limit(10);
firebase_firestore_query_execute_get("My Query of Best 10 players");
GET THE EXTENSION

Open Source

Share

Marty

Truely speaking, I don't know what am I doing most of the time.

Leave a Reply