Server-selector NPCs

Start

Turn the module on

NPCs are off until you switch them on, under Modules → NPCs on the dashboard. Choose whether every group renders them or only the ones you pick — a selector belongs in a lobby, not in the middle of a match.

Switching the module off hides every NPC without deleting one, so turning it back on restores exactly what you had. Enabling it with selected groups and no groups chosen is refused rather than saved: that combination looks configured and does nothing.

Editing any of this needs the npcs.manage permission on your Atlas role. That is separate from the in-game permission below — one governs the person on the dashboard, the other the person standing in the world.

# The dashboard does this for you; the API is here
# if you would rather script it.
curl -X PUT https://dashboard.atlasgg.com/v1/networks/$NETWORK/modules/npcs \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "target_mode": "selected",
    "target_groups": ["lobby", "au-lobby"]
  }'

Start

Place one in game

Placing is a command, not a form. A coordinate typed by somebody who cannot see the world is a coordinate inside a wall, so /atlasnpc create uses where you are standing and which way you are facing.

The command needs the Minecraft permission atlas.npc.manage, which defaults to operators.

# Stand where it should go, face the way it should face.
/atlasnpc create &aSkyblock

# Every NPC in this group, with its id.
/atlasnpc list

# Editing by id. Tab-completion fills the ids in.
/atlasnpc name       <id> &bThe Hub
/atlasnpc skin       <id> Notch
/atlasnpc item       <id> DIAMOND_SWORD
/atlasnpc look       <id> true
/atlasnpc leftclick  <id> connect
/atlasnpc rightclick <id> gui

# Moves it to where you are standing now.
/atlasnpc move   <id>
/atlasnpc remove <id>

Start

Name, skin and clicks

Everything except placing and moving can also be edited on the dashboard, on the same page you enabled the module.

• display_nameDrawn just above the NPC. Colour codes and placeholders both work.
• skin_owner_nameAny Minecraft username. The skin is that account’s.
• item_in_handA Bukkit material name, or AIR for empty-handed.
• look_at_playerTurns its head to follow whoever is nearby.
• info_linesHologram lines above the NPC. Colour codes and placeholders both work.
• imitate_playerWear the viewer’s own skin instead of the configured one.
• left_click_actionNOTHING, DIRECT_CONNECT, or OPEN_GUI.
• right_click_actionThe same three, set independently.

Skins are resolved once, centrally, and stored with the NPC. Twenty lobbies rendering the same character would otherwise be twenty requests to a rate-limited Mojang endpoint for one answer. A username nobody owns is refused by name; Mojang being unreachable places the NPC with the default skin rather than losing your work.

curl -X PUT https://dashboard.atlasgg.com/v1/networks/$NETWORK/npcs/$NPC \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "&aSkyblock &7(%group_players:skyblock%)",
    "skin_owner_name": "Notch",
    "item_in_hand": "GRASS_BLOCK",
    "look_at_player": true,
    "right_click_action": "DIRECT_CONNECT",
    "routing": {
      "rules": [],
      "default": { "strategy": "lowest", "group": "skyblock" }
    }
  }'

Routing

The routing document

Every NPC carries one. The dashboard writes the simple case for you from the Destination dropdown; the text area underneath is the same document, for everything the dropdown cannot express.

Two keys

• rulesChecked in order. The first whose condition matches wins.
• defaultUsed when no rule matched. May be null.

One condition

when.from_group_in lists proxy group names, and matches when the proxy that accepted this player’s connection is in the list. It is how one NPC behaves differently for players who arrived on different regional proxies. Naming a game group here is allowed but can never match.

{
  "rules": [
    {
      "when": { "from_group_in": ["au-proxy", "nz-proxy"] },
      "send_to": { "strategy": "lowest", "group": "au-smp" }
    },
    {
      "when": { "from_group_in": ["eu-proxy"] },
      "send_to": { "strategy": "lowest", "group": "eu-smp" }
    }
  ],
  "default": { "strategy": "lowest", "group": "na-smp" }
}

Routing

Worked examples

One destination for everybody

What the dashboard dropdown writes. Use it for a hub NPC that always leads to the same place.

Send a returning player back

The one people ask for. A network with au-smp, na-smp and eu-smp wants one NPC in the lobby that returns you to whichever you were playing — and puts a brand-new player on the one nearest the proxy they arrived on.

Read the second example as: if you came in on the Australian proxy, send you to the most recent of these three SMPs; if you have played none of them, send you to au-smp. Anyone else gets the shared smp.

Spread or concentrate

random spreads arrivals evenly across interchangeable groups; highest does the opposite, sending people to the busiest so a quiet evening concentrates into one populated server instead of four lonely ones. lowest over a list is the middle ground.

Different lobbies, different NPCs

You do not have to solve everything in one document. NPCs are per group, so an au-lobby NPC can carry the Australian rules and a eu-lobby NPC its own — often clearer than one document with six rules in it.

// 1. One destination for everybody.
{
  "rules": [],
  "default": { "strategy": "lowest", "group": "skyblock" }
}

// 2. Return an Australian player to the SMP they last
//    played; a new one starts on au-smp.
{
  "rules": [{
    "when": { "from_group_in": ["au-proxy"] },
    "send_to": {
      "strategy": "last_of",
      "groups": ["au-smp", "na-smp", "eu-smp"],
      "fallback": { "strategy": "lowest", "group": "au-smp" }
    }
  }],
  "default": { "strategy": "lowest", "group": "smp" }
}

// 3. Everyone goes back where they were, wherever they
//    connected from: no condition, just a default.
{
  "rules": [],
  "default": {
    "strategy": "last_of",
    "groups": ["au-smp", "na-smp", "eu-smp"],
    "fallback": { "strategy": "lowest", "group": "na-smp" }
  }
}

// 4. Spread arrivals evenly across four identical
//    minigame groups, whatever their populations.
{
  "rules": [],
  "default": {
    "strategy": "random",
    "groups": ["bedwars-1", "bedwars-2",
               "bedwars-3", "bedwars-4"]
  }
}

// 5. Send people where the game already is, so a quiet
//    evening concentrates instead of scattering.
{
  "rules": [],
  "default": {
    "strategy": "highest",
    "groups": ["au-smp", "na-smp", "eu-smp"]
  }
}

// 6. Regional split, with the returning-player rule kept
//    for the region that actually has three SMPs.
{
  "rules": [
    {
      "when": { "from_group_in": ["eu-proxy"] },
      "send_to": { "strategy": "lowest", "group": "eu-smp" }
    },
    {
      "when": { "from_group_in": ["au-proxy", "nz-proxy"] },
      "send_to": {
        "strategy": "last_of",
        "groups": ["au-smp", "na-smp"],
        "fallback": { "strategy": "lowest", "group": "au-smp" }
      }
    }
  ],
  "default": { "strategy": "lowest", "group": "na-smp" }
}

Reference

When routing fails

A click that cannot be honoured tells the player so in chat, prefixed with Could not send you there. The rest of the message says which half failed.

• no usable destinationThe document produced no group. Nothing matched and there is no default; or a rule matched and its target resolved to nothing; or a strategy name is one Atlas does not implement.
• a capacity failureThe group was chosen but is full. Routing worked; there was nowhere to put them.
• temporarily unavailableThe control plane could not read the player’s history. Retrying is reasonable.

// Atlas routes NPC clicks itself. This is only for a
// plugin doing its own routing — a custom menu, say.
atlas.resolveNpcRoute(player.getUniqueId(), routingJson)
    .thenCompose(group ->
        atlas.player(player.getUniqueId()).transfer(group))
    .whenComplete((ignored, error) -> {
        if (error != null) {
            // Callback is off the tick thread.
            Bukkit.getScheduler().runTask(plugin, () ->
                player.sendMessage("Nowhere to send you."));
        }
    });

Reference

The selector menu

A click set to OPEN_GUI opens a menu of the individual servers behind the NPC’s destinations, with live player counts. Clicking one goes to that exact server.

This is the one thing routing deliberately cannot express. Routing picks a group and lets Atlas place the player inside it, which is what you want for a click that should just work — and not what you want for somebody trying to land on the same lobby as a friend.

• What it listsEvery routable server in every group the routing document names, condition groups excluded.
• What it showsServer name, its group, players against capacity, and the game status if the server set one.
• What a click doesGoes straight to that server, re-checked at the moment of the click.

# Right click opens the menu, left click connects
# straight away. They are independent.
/atlasnpc rightclick <id> gui
/atlasnpc leftclick  <id> connect

# The menu lists the servers of whatever groups the
# routing document names, so a document sending people
# to three SMPs produces a menu of all three SMPs'
# servers. Narrow the menu by narrowing the routing.