Data system

A space on the website that your game shares between all its players: what one player's game saves, the other players' games can read, change or remove. It's what you need for a market between players, levels made by players, a world boss, a ranking… Read the warnings first.

How it works

• Each thing you save is an entry: it has a kind (a label you choose: 'offer', 'score', 'map'…) and a value (anything JSON can store). The entries belong to your game, not to the players: the same entry is seen by every player of the game.
• The player has to be signed in for every call. A guest gets the error login_required.
• Each entry is public or private for writing and public or private for reading. Both are public unless you say otherwise when you create it, and they can't be changed afterwards:
  • Public reading: any signed-in player can read it. Private reading: only its author.
  • Public writing: any signed-in player whose email is verified can change or remove it. Private writing: only its author.
• The website stamps each entry itself, the game can't fake it: the author (by), the account that changed it last (editedBy), the dates (createdAt, updatedAt) and whether it is yours (mine).
• Every change is kept in a history, so a mistake or an abuse can be undone from your Data tab.
• It only works in a game that is on the website. Anywhere else (your own computer, the preview of a submission), every function answers no_game.

Functions

Every function returns a promise and never throws.

An entry looks like this:

{
  id: 4821, kind: 'offer', data: { item: 'strawberry', qty: 12, price: 30 },
  by: 'ana', editedBy: null, mine: false,
  createdAt: '2026-10-15T10:21:07Z', updatedAt: '2026-10-15T10:21:07Z',
  publicWriting: true, publicReading: true
}

data is the value that was saved. by is null when the account that wrote it was deleted afterwards (see “What happens to the data”).

Errors

When something goes wrong the answer is { ok: false, error, message }: error is a short code you can compare, and message a sentence in English that explains it (also written in the browser console when the mistake is yours).

const result = await HGSDK.data.add('offer', { item: 'strawberry', qty: 12, price: 30 });
if (!result.ok) {
  if (result.error === 'login_required') showSignInButton();
  else if (result.error === 'email_not_verified') showMessage('Verify your email to sell');
  else if (result.error === 'rate_limited') showMessage('Slow down a little');
  else showMessage('Something went wrong');
}

Recipe: a market between players

1. Decide what an entry means. One entry per offer: kind 'offer', value { item, qty, price }. Save facts, not conclusions.
2. Save with add. The entry has to be public for writing so another player can remove it when buying: that is the default.
3. Read and check. list the newest offers and pass them through filter with the 'market' template.
4. Buy. remove the offer: whoever removes it first gets ok and the goods; the rest get not_found and refresh.
5. Handle the errors from the table above, at least login_required and rate_limited.
6. Choose your limits in the Data tab and test with two accounts (two browsers) before you publish.

// sell
const sold = await HGSDK.data.add('offer', { item: 'strawberry', qty: 12, price: 30 });
if (!sold.ok) handleError(sold);

// show the market: the 50 newest offers that follow the rules
const read = await HGSDK.data.list('offer', 0, 50);
if (read.ok) HGSDK.data.filter(read.entries, 'market').forEach(drawOffer);

// buy: whoever removes the offer first gets it
const bought = await HGSDK.data.remove(offer.id);
if (bought.ok) giveItems(offer.data);
else refreshMarket();

Check what you read

HGSDK.data.filter(entries, rules) returns an array with the entries that follow the rules, in the order they were written. The entries that break a rule are not thrown away: they are listed in result.marked as { entry, rule }, in case you want to show or log them. Nobody is punished: you decide what to do. rules is an object with the rules you want, or the name of a template.

The templates are ready-made sets of rules. Use them by name, or copy their values and change the ones you want:

// a template by name
const clean = HGSDK.data.filter(entries, 'ranking');

// your own rules (the values of 'chat', made stricter)
const calm = HGSDK.data.filter(entries, { minSecondsBetween: 5, maxPerMinute: 6 });

// what was ignored, and why
calm.marked.forEach((m) => console.log(m.entry.id, m.rule));

filter works with the entries you give it, so give it enough of them (up to 50 per list call) for the rules that count per player to make sense.

More examples

// a ranking where each player has one entry that only they can change
const mine = { name: playerName, points: 340 };
await HGSDK.data.add('score', mine, { publicWriting: false });
const board = await HGSDK.data.list('score', 0, 50);
if (board.ok) {
  HGSDK.data.filter(board.entries, 'ranking')
    .sort((a, b) => b.data.points - a.data.points)
    .forEach(drawScore);
}

// a save that follows the account to any device: private for writing and for reading
await HGSDK.data.add('save', gameState, { publicWriting: false, publicReading: false });

// a counter shared by everybody: read it, change it, save it
const read = await HGSDK.data.get(counterId);
if (read.ok) {
  read.entry.data.hits += 1;
  const saved = await HGSDK.data.set(counterId, read.entry.data);
  if (saved.error === 'changed') tryAgain();   // another player changed it at the same time
}

// a chat: the 20 newest messages that follow the rules
const chat = await HGSDK.data.list('message', 0, 20);
if (chat.ok) HGSDK.data.filter(chat.entries, 'chat').forEach(drawMessage);

• Two players at the same time. set only changes an entry if it is still the way your game last saw it (in add, get, list or its own set); otherwise it answers changed. remove answers ok only to the first one.
• Position in list. If entries are added or removed while players page through a list, a few can repeat or be skipped. For rankings and markets that is fine.

GameMaker (GML)

With the HGSDK extension (version 1.1 or later) the same functions exist in GML. Each call returns a request number, and the answer arrives at the Asynchronous → Social event, in async_load, with type equal to "hg_data". Values travel as JSON text: json_stringify to send them and json_parse to read them.

The map that arrives at the event has these keys: type, call ("add", "get", "list", "set" or "remove"), request, ok (1 or 0), error (the code of the Errors table, empty when everything went well), message, id (in add), entry (in get, JSON text) and entries (in list, JSON text). The extra error no_sdk means the SDK script is not loaded.

global.request_sell = hg_data_add("offer", json_stringify({ item: "strawberry", qty: 12, price: 30 }), 0);

global.request_market = hg_data_list("offer", 0, 50, "new");

global.request_buy = hg_data_remove(offer_id);

In the Asynchronous → Social event:

if (async_load[? "type"] != "hg_data") exit;
var request = async_load[? "request"];
var ok = async_load[? "ok"];
if (ok == 0)
{
    var error = async_load[? "error"];
    if (error == "login_required") show_sign_in_button();
    exit;
}
if (request == global.request_market)
{
    var clean = json_parse(hg_data_filter(async_load[? "entries"], "market"));
    for (var i = 0; i < array_length(clean); i++)
    {
        var offer = clean[i];
        draw_offer(offer.id, offer.data.item, offer.data.price);
    }
}

Limits and your Data tab

Open your game from My games: its Data tab is the control panel of the data system. Only you, the administrators and the founder see it.

• Limits per account. You choose how many writes (add, change, remove), reads and removals of other players' entries each account can make in your game, with a number and a unit of time (per second, minute, hour or day), and how many entries each account can have. The website sets a maximum for each one, shown next to the field. At first: 120 writes per minute, 600 reads per minute, 300 removals per day and 1,000 entries per account. A limit that is too low makes honest players fail; one that is too high lets a bot do more damage: the choice is yours.
• Alerts. The website marks accounts that do unusual things in your game (for example, too many writes) and lists them with a level from 1 to 5 and an explanation. An alert only marks: nothing is blocked by itself. For each one you can mark it as a false positive (similar alerts will then start lower), block the account from the data of your game for some hours or for ever, or undo what it did.
• History. Every change is kept with the old value, the date, the account and its IP for a limited time (90 days at first). You can search it and put an entry back as it was, or undo everything an account did in a period of time.

What happens to the data

• When a player deletes their account, the entries that are private for writing and for reading are deleted. The rest stay with their content intact but without any link to the account (by becomes null), so the other players' games keep working. You and the administrators can remove those entries from the Data tab.
• Because of that, anything personal inside the value of a public entry is your responsibility: don't put it there.
• The rules about accounts and personal data are in the terms of use and the privacy policy.