Introduction

About

Aviator is a client API library for the Cockpit CMS written for Game Maker: Studio 2. The library provides a set of scripts that will help you to easily access your data stored in a Cockpit installation.

Cockpit (https://getcockpit.com) is a self hosted, open source, headless CMS with an API-first approach, designed to simplify the process of publication by separating content management from content consumption on the client side. Aviator helps you accessing the API and retrieve your data by providing wrapper functions and a simple example project to get you started.

This asset has been developed for anyone needing a simple yet professional way to include any kind of remotely managed data into their games, like news feeds, alert systems, configuration profiles, etc... managed through user friendly web interface.
It's also easy to setup on your host and does not require any knowledge of MySQL or database systems in general.

Getting started

You are encouraged check out the demo project at first to get an idea of how a working implementation works.

Afterwards, in order to setup your project to be used with Aviator, you can follow these steps:

1. Install Cockpit on your host / server

Follow the official installation instructions in order to have a working cockpit installation.

2. Import and configure Aviator

  • Navigate to the script resources of the asset, and import all the contents of the cockpit folder.
  • Open the li script and edit the values of COCKPIT_CONFIG_HOST and COCKPIT_CONFIG_API_KEY accordingly.
  • COCKPIT_CONFIG_HOST should point to the root of your cockpit installation. Opening this url in a browser should bring you to the login page.
  • COCKPIT_CONFIG_API_KEY contains your API key. You find and generate API keys in cockpit under Settings > API access. Remember not to use your master api key in production. Instead, consider generating a new api key with a limited ruleset.
  • Run cockpit_config( ) in your game initialization routine.

Sample API calls

Calls to the API are performed by using the cockpit_get( ) and cockpit_post( ) scripts, generating an async HTTP GET and HTTP POST request respectively.
These functions return the request id of the HTTP call, to be used in the Async HTTP event.

//perform a request for a singleton containing the game configuration
var _url = cockpit_url(COCKPIT.singleton_get,"game_config");
game_config_id = cockpit_get(_url);

//request all the entries of the "posts" collection, sorted by date in ascending order
var _url = cockpit_url(COCKPIT.collection_get,"posts");
posts_id = cockpit_get(_url, "sort[date]=-1");

//try downloading a sprite by generating an image URL using its remote id
var _image_id = "5b9289d6303632639000023a";
var _url = cockpit_image_url(_image_id,288,100);
sprite_id = sprite_add(_url,1,false,false,0,0);

The cockpit_get( ) requests performed above will return and id to be used in the HTTP async event (see GM manual for details) to process the response sent by the server. A simple async event for the two requests above could look like this:

//check for game_info data
if (async_load[? "id"] == game_config_id && async_load[? "status"] == 0) {

var _result = async_load[? "result"];

if(async_load[? "http_status"] != 200) {
show_debug_message("ERROR: " + _result); }

else {
show_debug_message("SUCCESS: " + _result); }

}

//check for posts data
else if (async_load[? "id"] == posts_id && async_load[? "status"] == 0) {

var _result = async_load[? "result"];

if(async_load[? "http_status"] != 200) {
show_debug_message("ERROR: " + _result); }

else {
show_debug_message("SUCCESS: " + _result); }

}

Scripts reference

cockpit_config()

Contains Aviator configuration options. This script has to be edited to match your configuration options and must be run at the beginning of your game in order to use the other scripts.

cockpit_get(url,[params])

Generates an HTTP GET request with the specified url query parameters (if any). Returns the id of the request to be used in the HTTP Async event.

url {string} Full URL or relative path to the api action (as generated by cockpit_url() or cockpit_path())
[params] {string} (optional) GET parameters to pass to the http request. E.g: "w=640&h=480"

var _url = cockpit_url(COCKPIT.collection_get,"posts");
posts_id = cockpit_get(_url,"limit=10&filter[category]=alerts");
cockpit_image_url(image_id,width,height)

Generates and returns a full URL to an image asset. This call does not generate an HTTP request, it simply returns a url to an image file that can be used, for example, to load a remote sprite with sprite_add.
Setting either width or height to 0 or less removes that parameter from the generated url.

image_id {string} ID of the image generated by cockpit.
width {integer} width of the image
height {integer} height of the image

cockpit_image_url("xximageidxx", 640, 480);
//-> http://yourdomain.com/api/cockpit/image?token=xxtokenxx&src=xximageidxx&w=640&h=480&o=1
cockpit_image_url_ext(image_id,width,height,mode,filters,quality,base64)

Works like cockpit_image_url but allows for more options to be passed as url parameters.
Generates and returns a full URL to an image asset. This call does not generate an HTTP request, it simply returns a url to an image file that can be used, for example, to load a remote sprite with sprite_add.

image_id {string} ID of the image generated by cockpit
width {integer} width of the image
height {integer} height of the image
mode {string} crop mode. Either one of the following: "thumbnail", "bestFit", "resize", "fitToWidth", "fitToHeight"
filters {array} filters to apply to the image as an array of arrays. E.g: [["brighten",50],["flip","x"]]. An empty array or -1 = no filters
quality {integer} quality of the generated image (0 - 100)
base64 {integer} if true, returns the image base64 encoded

cockpit_image_url_ext("xximageidxx",288,-1,"",[["brighten",20],["flip","y"]],80,false);
cockpit_path(action,[...params])

Generates and returns a relative URL for the specified action of the API. If the action requires one or more arguments, those can be passed as strings. To generate the full url instead, see cockpit_url().

action {integer} The action (API method) to be used to generate the URL, as a value from the COCKPIT enum. See the contents of the cockpit_config() for a list of available values.
[...params] {string} (Optional) one or more action parameters to attach to the returned url, as separate string arguments

cockpit_path(COCKPIT.collection_get,"posts");
// -> /api/collections/get/posts
cockpit_post(url,body)

Generates an HTTP POST request with the specified parameters. Returns the id of the request to be used in the HTTP Async event.

url {string} Full URL or relative path to the api action (as generated by cockpit_url() or cockpit_path())
body {string|ds_map} POST parameters to pass to the http request, either as a JSON formatted string or ds_map

var _url = cockpit_url(COCKPIT.collection_get,"posts");
posts_id = cockpit_post(_url,data);
cockpit_url(action,[...params])

Generates and returns a full URL for the specified action of the API. If the action requires one or more arguments, those can be passed as strings. To generate the full url instead, see cockpit_path().

action {integer} The action (API method) to be used to generate the URL, as a value from the COCKPIT enum. See the contents of the cockpit_config() for a list of available values.
[...params] {string} (Optional) one or more action parameters to attach to the returned url, as separate string arguments

cockpit_path(COCKPIT.collection_get,"posts");
// -> http://yourdomain.com/api/collections/get/posts

Credits and contact

Contact me on the YoYoGames forums or by email at simoneguerra<at>ekalia.com