Skip to content

ScriptingStorage, bridge, HTTP, JSON

storage: per-script JSON

storage.set('seen', ['a', 'b']);
storage.get('seen', []);
storage.has('seen');  storage.remove('seen');  storage.keys();  storage.clear();
storage.save();                    // write to disk now

Lives in ~/.bitchos/scripts/data/<script>.json. Reads are in-memory and free; writes hit the disk only on save(), on unload, and on a slow timer once something has changed. Do not call save() from a tick handler. Whole objects and arrays are fine.

bridge: talk to other scripts

bridge.set('rushOrder', order);
bridge.get('rushOrder');
bridge.has(k);  bridge.remove(k);  bridge.keys();  bridge.clear();

For one script publishing something expensive that several others read. Publish data, not functions: a function put in the bridge runs in the publisher's scope but is blamed on the caller when it throws, so its errors land on the wrong script.

http

http.get(url, function (r) { /* … */ });
http.get(url, { 'Accept': 'application/json' }, function (r) { /* … */ });
http.post(url, body, function (r) { /* … */ });
http.post(url, body, headers, function (r) { /* … */ });

Always asynchronous. There is no blocking form, because one blocking request on the client thread is a frozen game for as long as the far end takes. The callback runs on the client thread, so it can touch anything.

A response has .status .body .json .error .ok.

  • A failure is a response, not a throw. A timeout, a refused connection or a bad host arrives with .status === 0 and .error set.
  • .json is null when the body is not JSON, rather than throwing. An HTML error page from a proxy is an ordinary thing to receive.
  • Timeouts: 10 s to connect, 15 s to read. Bodies are capped at 4 MB.
  • Only http:// and https:// are accepted; a file:// URL is refused, because otherwise it would be a way round the sandbox's file rules.
  • A non-string body is serialised as JSON and Content-Type: application/json is set unless you set one.

Replies to a switched-off script are dropped

A reply that arrives while your script, or the Scripts module, is switched off is dropped, not queued. "Switched off" means no script code runs, and a callback delivered minutes later against state that has moved on is worse than none. Requests are cheap to make again from onEnable.

function onEnable() {
    http.get('https://api.mojang.com/users/profiles/minecraft/' + player.name, function (r) {
        if (!r.ok || !r.json) { chat.print('§clookup failed: ' + (r.error || r.status)); return; }
        storage.set('uuid', r.json.id);
    });
}

json

json.parse(text)        // null when it is not valid JSON — does not throw
json.stringify(value)
json.stringify(value, 2)

The language's own JSON is present and identical, except that JSON.parse throws where json.parse answers null.