Black BoxGet the HUD
FeaturesGuidesFor sim ownersAboutGet the HUD

In-world setup

How to set up the in-world side of Black Box, from auth keys and the Delivery Server to doors, containers, nodes, the radar and the ban server, and what to check when an object doesn't respond.

For staff

Black Box’s in-world objects talk to your sim’s server: the Delivery Server that hands out the HUD, doors, containers, the radar and more. This guide covers setting each one up and what to check when one goes quiet. Do it once your game content is in place, before you open.

What every scripted object needs

Most objects have two settings at the top of their script:

  • siteUrl: your server’s address. It is usually your web-url followed by Backend/api.php.
  • authKey: one of the keys from Server › Auth Keys.

Registered objects keep their server ID in the object’s description, so leave it alone. Picked up and rezzed again, an object keeps its identity. To make it a new object, clear the description and reset the script.

Auth keys

An auth key is a password your scripts send with every call to the server. Make one per kind of script, so you can switch one kind off without touching the rest. You need the Super Admin or Admin role, or the authkey_edit permission.

Make a key

  1. Go to Server › Auth Keys.
  2. Press New key and, in What it’s for, name the script that uses it, such as Doors.
  3. Press Make it. The new key is shown.
  4. Press Copy, paste it into the script’s authKey line, and save the script.

Keys stay hidden until you press Show. Keep them out of chat and shared notecards.

Key checking

The Key checking switch on the same page sets system-authTokens:

Setting Value What happens to a wrong, missing or switched-off key
Off 0 Keys aren’t checked. Any script can call the server.
Warn only 2 The call goes through and is written to the server’s error log.
On 1 The call is refused.

When a call is refused, the HUD gets no answer at all. Other objects tell their owner “Authentication failed: Invalid or disabled auth key”, and some show SERVER ERROR over themselves. The object does nothing.

To stop a key without deleting it, flip its On switch off. Scripts using it are refused while checking is on.

Tip: Run Warn only for a few days before you switch checking On. Under Server › Debug, switch on the api_auth_failure category. It records each in-world call with a bad key, with the object’s name, owner and region, so you can find the objects with old keys.

If the page says the system-authTokens setting is missing, add it on Server › Settings with the value 0, 1 or 2.

The Delivery Server

The Delivery Server is a prim holding the boxed items the system hands out, such as the HUD. The server tells it what to give to whom.

Set it up

  1. Rez a prim and put each boxed item in its contents.
  2. Add the delivery server script, with authKey and siteUrl set.
  3. The script names the prim Delivery Server, shows that over it and registers.
  4. Open Staff › Sim › Assets & delivery. The top of the page shows the region it’s in and when it last checked in.

It checks in when it starts: when you rez it, reset its script, or the region restarts. If the page says it hasn’t checked in for a while, reset its script. Keep only one Delivery Server rezzed, so nobody gets two copies.

Assets

Each item it hands out is an asset on Assets & delivery. Changing assets needs the sim_settings permission. Press Add an asset or Edit, then set:

  • Name.
  • Box name in the Delivery Server: exactly the name of the box in the prim’s contents.
  • Version: a number such as 43 or 3.10.
  • On or Off. Off stops kiosks handing it out. Staff can still send it.
  • Vendors and kiosks only give it to people with an approved character sheet.

The HUD is asset 1, marked HUD - updates at login.

How players get the HUD

Put out a kiosk running the request item script, with authKey and siteUrl set and the asset’s number in its description. It shows Touch to request item. A touch asks the Delivery Server to give that asset to the person who touched it.

Releasing a HUD update

  1. Put the new box in the Delivery Server and take the old one out.
  2. Edit the asset: set the new box name, press Next version, and save.
  3. Each HUD on an older version says “Hud outdated, sending update.” at its next login and gets the new copy.
  4. To send it now, use Deliver now, pick the asset and Everyone online. Deliveries need the sim_delivery permission.

Other objects

Object What to set On the website
Titler Nothing. It is worn. When it attaches, the HUD fills it in.
NPC titler authKey, siteUrl. Rez it, touch it and pick Set NPC. Game Design › Quests & NPCs › NPCs
Doors authKey, siteUrl, and the door’s type number (type or doorTypeId). World Building › Objects
Lights, switches, power panels, generators authKey, siteUrl, deviceTypeId and deviceKind. World Building › Objects, Power grid
Alarms authKey, siteUrl, alarmTypeId. Name every alarm in a zone the same. Storytellers › Alarms
Crafting tables authKey, siteUrl. World Building › Objects
Containers siteUrl, and the container’s number in the description. Staff › Sim › Containers
Gathering nodes authKey, siteUrl, and the node’s number in the description. Game Design › Crafting & loot › Loot nodes
Quest props authKey, siteUrl, and quest: plus its number in the description. Game Design › Quests & NPCs › Quest NPCs & objects
Radar authKey, siteUrl. One per region. Moderation › Radar
Ban server authKey, siteUrl. Moderation › Bans
Name server authKey, siteUrl. Moderation › Radar, Add to radar

Doors and other registered objects

Doors, lights, switches, power sources, alarms and crafting tables register themselves. They show REGISTERING…, then READY and their ID in green, and appear under World Building › Objects. Set their zone, access list and power source on the object’s page. Copies of a registered object notice they share an ID, show ID CONFLICT - RESETTING and register again with new IDs.

Alarms

Alarms are fired from Storytellers › Alarms through a relay prim named Alarm Server. On the Zones tab, each zone’s In-world object name must match the name of that zone’s alarm objects exactly. Zone-wide commands for other objects go through a second relay prim named Env Server. Name each relay prim before you start its script, because it registers under that name.

Stations, containers, nodes and quest props

  • A crafting station is a place, set on Game Design › Crafting & loot › Crafting stations with Region, Position and Must be within (metres). A crafting table object is optional. To have power cut a station, put an object’s key in Powered by (env object key).
  • Keep containers further apart than sim-containerDist metres. Otherwise players get “More than one container in range.” The container script sends no auth key, so check your containers still open after you switch key checking On.
  • A node hides after it is gathered and comes back after a while. A moving node goes to its next location.
  • Players open a quest prop’s talk by touching it within 2 metres, wearing the HUD.

Ban server and name server

Rez the ban server as someone who can manage the estate’s ban list, and accept the permission it asks for. It carries out bans, unbans and kicks from Moderation. The name server looks up a person’s name when you use Add to radar.

Pieces inside the HUD and NPC titlers

The HUD rezzes small helper objects during fights: the AoE Placer for area attacks and the Radius Range Template movement ring. Each NPC titler needs both in its contents too, under exactly those names.

The region experience

If you switch it on: list your region names in experience-sims on Server › Settings, such as ["My Region"]. In those regions a HUD built with an experience asks each player to accept it. If they decline, it says the region requires experience permissions and detaches.

Check: Test it with an account that hasn’t accepted the experience before you rely on it.

Keeping scripts up to date

When you get a new version of a script:

  1. Open the object’s contents and replace the script.
  2. Set authKey, siteUrl and any type number again.
  3. Save. Leave the description as it is, so it keeps its identity.

The script resets and checks in again.

When an object doesn’t respond

What you see What to check
AUTH KEY MISSING, “Auth key not configured!” Put a key in authKey.
SERVER ERROR, “Authentication failed” The key is wrong or switched off. Copy it again from Server › Auth Keys.
HTTP ERROR and a number siteUrl is wrong, or the server is down.
Nothing at all Check the script is running, then reset it.
Not under World Building › Objects Read its floating text and its owner’s chat for an error, fix it, and reset the script.
Listed, but out of date Filter Last check-in to Over a day ago and reset those scripts.
Doesn’t change when you change it on the website On the object’s page, press Resync object.
“No container in range.” The player is too far away, or the container hasn’t checked in.

Also check the panic switches. While Turn the server off is on, the HUD and chat commands stop for players. While Pause the economy is on, nodes give nothing.