Glossary

The words used in the architecture walkthrough, Why Elixir & OTP and the rest of the Workshop, in two groups: the language and its platform, then WildStar and Bezgelor. Within each group the terms are in alphabetical order.

Elixir, Erlang and OTP

Application

In Elixir, a component that can be started and stopped as a unit, usually with its own supervision tree. Each of Bezgelor's umbrella apps is an application; BezgelorWorld.Application starts the world server.

BEAM

The virtual machine that runs Erlang and Elixir programs. It runs huge numbers of lightweight processes, spreads them across the computer's cores, and switches between them so none can hog a core. Bezgelor runs as one BEAM node: one running copy of the virtual machine holding every part of the server.

Behaviour

A list of functions a module promises to provide, like an interface in other languages. Packet modules implement the Readable or Writable behaviour; handlers implement BezgelorProtocol.Handler.

Binary pattern matching

Pattern matching on raw bytes or bits: the shape of the data is written as a picture, such as <<size::little-32, opcode::little-16>>, and the language takes it apart. Used to read packets. See Why Elixir & OTP.

Call and cast

The two ways to ask a GenServer something. A call waits for the answer, with a time limit; a cast drops the message in the mailbox and carries on. A player entering a zone is a call; moving and casting spells are casts.

DynamicSupervisor

A supervisor whose children are started while the system runs rather than listed in advance. Zone.InstanceSupervisor and each world's Zone.WorldSupervisor are dynamic supervisors: zones come and go.

Ecto

Elixir's database library: schemas that describe tables, changesets that check changes, queries, and migrations that create and change the tables. bezgelor_db is built on it.

Elixir

The programming language Bezgelor is written in. It runs on the BEAM, uses OTP, and first appeared in 2012. See Why Elixir & OTP.

Erlang

The older language the BEAM was built for, created at Ericsson for telephone exchanges. Elixir can use any Erlang library; Ranch and the cryptography Bezgelor relies on come from Erlang.

ETS

Erlang Term Storage: in-memory tables that any process can read directly, without sending a message. Bezgelor keeps the game's static data in about two hundred ETS tables (BezgelorData.Store), and a few fast-changing lookups too, such as which connections can see which creature (BezgelorWorld.CreatureViewers).

GenServer

"Generic server": OTP's standard shape for a process that holds some state and answers messages (calls and casts) one at a time. A zone instance, a player's connection and the data store are all GenServers.

Hot code loading

Loading a new version of a module into the running system, so processes use the new code from their next call and keep their state. Bezgelor uses it to deliver logic-only fixes and improvements to the running server while players stay connected (a "hot deploy"; see Why Elixir & OTP), and to reload zone and boss scripts from the admin pages (BezgelorWorld.Script.Registry.reload/0).

iex

Elixir's interactive console. The server is started inside one (iex -S mix phx.server), so a developer can inspect and change the running system.

LiveView

Part of Phoenix: web pages whose content is kept on the server and updated in the browser over a connection as things change, without writing JavaScript for it. Bezgelor's account and admin pages are LiveViews.

Message

Data one process sends to another. It goes into the receiver's mailbox and waits there until the receiver takes it. Messages are the only way processes affect each other.

Mix

Elixir's build tool: it compiles the project, fetches dependencies and runs tasks such as mix test and mix ecto.migrate.

Module

A named group of functions, the unit Elixir code is organised in. BezgelorWorld.Zone.Instance is a module; its name also tells you its file, apps/bezgelor_world/lib/bezgelor_world/zone/instance.ex.

Monitor

A one-way watch from one process on another: when the watched process ends, for whatever reason, the watcher gets a message saying so. A zone instance monitors each player's connection, so it can remove a player whose client vanished.

OTP

The Open Telecom Platform: the libraries and conventions that come with Erlang for building systems that run for a long time and survive failures. GenServers, supervisors and applications are OTP.

Pattern matching

Describing the shape of data you expect and binding its parts to names in one step. If the data doesn't have that shape, the match fails, and a function with several versions picks the one whose pattern matches.

persistent_term

A BEAM store for values that are read very often and changed very rarely; reading is faster than ETS. Bezgelor keeps the packet handler table, the script bindings and the GUID counter there.

Phoenix

Elixir's web framework. bezgelor_portal, the website and its admin pages, is a Phoenix application.

Process

The BEAM's unit of concurrency: a lightweight, isolated piece of running code with its own memory and a mailbox. Not an operating-system process or thread; a server can run millions. In Bezgelor each player's connection and each running zone is a process. See Why Elixir & OTP.

Ranch

An Erlang library that listens on a network port and starts one process for every connection. Bezgelor's login, realm and world servers all use it.

Registry

A lookup from a name to a process. BezgelorWorld.ZoneRegistry finds the zone instance process for a {world id, instance id}.

Struct

A map with a fixed set of named fields, defined in a module. Every packet is a struct, such as %ClientItemSplit{guid: ..., location: ..., count: ...}.

Supervisor

A process whose job is to start other processes, watch them and restart them when they fail. Supervisors are arranged in a supervision tree. This is what makes "let it crash" work. See Why Elixir & OTP.

Telemetry

A small library for emitting measurements (:telemetry.execute) that any part of the system can subscribe to. Bezgelor's metrics, alerts and live dashboard are built on it, and every game event is also a telemetry event.

Umbrella app

One of several applications kept in a single Elixir project and built together. Bezgelor's live in apps/: bezgelor_world, bezgelor_protocol, bezgelor_portal and the rest. See the architecture overview.

WildStar and Bezgelor

Aura

A lasting effect on a unit from a spell: a stun, a slow, a damage-over-time, a stat bonus. Auras are applied and timed by the zone instance from the actions the Caster returns.

Caster

BezgelorWorld.Spell.Caster: the pure functions that decide everything about a spell cast and return the actions for the zone to carry out. See Fighting.

Client

The original WildStar game program, build 16042 (the final live version), unchanged. Everything Bezgelor does is to make the client behave as it did when the official servers ran.

Client oracle

Our test tool that runs the real client's own packet-reading code (inside a CPU emulator) on the bytes our server produces, to check every server packet. See The wire and the client oracle guide.

Connection (process)

The process that owns one player's network connection to the realm or world server: BezgelorProtocol.Connection. It reads and decrypts packets, runs their handlers, and sends packets back.

Context

In bezgelor_db, a module that is the only way to read and change one area of the database, with functions named for what they do: BezgelorDb.Characters, BezgelorDb.Inventory, BezgelorDb.Guilds.

Creature2

The client table that defines every creature: its name, model, level range, difficulty and faction. Spawned creatures on the server are built from its rows.

Entity

Anything in a zone that the client can see or target: a player, creature, object, vehicle or corpse (BezgelorCore.Entity). Each has a GUID.

Event

A record of something that happened in the game (a login, a kill, a quest completed, an admin action), emitted with Bezgelor.Events.emit and stored in the game_events table. See Behind the scenes.

Frame

One message on the wire: a 4-byte size, a 2-byte opcode and the payload.

Game token

The single-use ticket the login server gives the client after a successful login. The client hands it to the realm server, which accepts it once, within a couple of minutes.

GM command

A chat command for game masters and testers, such as !teleport or !item add, handled by the world server.

GUID

A unit's id on the wire, a 32-bit number. Its top bits say what kind of entity it is: players are 0x2000_0000 plus their character id (BezgelorCore.EntityId).

Handler

The module that deals with one kind of client message. It reads the packet, does the work and says what to send back. Handlers run inside the player's connection process.

Instance

A separate copy of a map. Open-world zones have one; dungeons, adventures, expeditions and raids get a copy per group or player, with its own creatures and progress (BezgelorWorld.Instances).

Leash

How far a creature will chase before it gives up and walks back to where the fight started. In Bezgelor, 40 units unless the creature says otherwise.

Map entry

The burst of packets that moves a player onto a map: ServerChangeWorld and everything the client needs to draw the player. Built by BezgelorProtocol.MapEntry, for logins and teleports alike.

NexusForever

The open-source WildStar server written in C#. Bezgelor began as a port of it, and its protocol work and data are the foundation much of Bezgelor stands on.

Opcode

The 16-bit number at the start of every message that says which message it is, for example 0x0244 for ClientEncrypted. BezgelorProtocol.Opcode gives each one a name.

Packet

One message between client and server, with its fields packed bit by bit. In Bezgelor each packet is a module with a read or write function under apps/bezgelor_protocol/lib/bezgelor_protocol/packets/.

PacketCrypt

WildStar's own packet cipher (BezgelorCrypto.PacketCrypt), which encrypts nearly all realm and world traffic.

Provenance

How sure we are of a piece of data, and why: reference (straight from a retail source such as the client's tables), derived (worked out from them by a rule) or guess (designed by us). See Where we differ.

Realm

A game world as players choose it at the realm-select screen. The realm server (bezgelor_realm, port 23115) checks the game token and sends the client on to the world server.

Session key

The random key the realm server makes for each login. The client presents it to the world server, and the world server's packet encryption is keyed from it.

Spatial grid

A grid laid over a zone (cells of 50 units) so that "who is near this point?" only looks at nearby cells (BezgelorCore.SpatialGrid).

Spell effect

One thing a spell does, such as damage, a heal, a stun or a teleport: a row of the client's Spell4Effects table. A spell has one or more.

Spell4

The client table that defines every spell: cast time, cooldown, costs and targeting. What a spell does and the shapes it draws are in companion tables (Spell4Effects, Spell4Telegraph). Bezgelor's spells are their rows.

SRP6

The password protocol the login server uses. Client and server prove to each other that they know the password, without it ever crossing the network, and end up sharing a secret key.

STS

The login protocol and server the client talks to first (port 6600). Its messages look like web requests with XML bodies. Bezgelor's is bezgelor_auth.

Telegraph

The shape drawn on the ground to show where an ability will hit: a circle, cone, ring, rectangle and so on. WildStar's combat is built around moving out of them. BezgelorCore.Telegraph decides who is inside.

TestClient

A headless player for tests (BezgelorWorld.TestClient): it logs in through the real protocol, plays scripted steps and checks every packet it receives with the client oracle.

Threat

How much a creature wants to attack each player, raised mostly by damage. A creature attacks the player at the top of its threat table.

Tick

The zone instance's regular heartbeat, every 250 milliseconds: creature AI, auras, regeneration and scripts run on it.

World server

bezgelor_world, on port 24000: the character screens and the whole game world. See Into the world.

Workshop

These pages: how Bezgelor is built and tested, open to everyone.

Zone

A map of the game world, such as Northern Wilds or Thayd. On the wire it is identified by a world id.

Zone instance

The process that runs one copy of a zone: BezgelorWorld.Zone.Instance, one per {world id, instance id}. It owns the players and creatures in it and runs the tick. See Into the world.