Owners

How the owners work as built, and why: one thread over one queue per side of the game, the two owners the first stage built, and how they reach the gateway and the database. The facts to look up are on Owners base, Owners account and Owners realm; what's still to build, the map owners among it, is on Owners design.

How it fits together

The shape

flowchart TD
    GW["Gateway connections"] -->|"tokens, keys"| AO["Account owner"]
    GW -->|"character select"| RO["Realm owner"]
    CMD["Command layer"] -->|"create, suspend, lift"| AO
    AO & RO -->|"work"| WB["Write-behind queue"]
    WB -->|"completion message"| AO & RO

Loading

An owner is one thread over one queue. It holds one side of the game, and only its own handler touches that state, so the state needs no locks. Everything else talks to it by posting a message, and a reply travels back in the message itself, completed by the owner and carried on outside its thread (Owners base).

No owner waits on the database. Anything that needs it goes to the write-behind queue as work and comes back as a completion message (Persistence). So an owner's thread only ever runs the game.

The account owner decides who may play. Sign-on hands it an account's credentials as they were read at login, and it issues and redeems the game tokens and session keys that carry a client from sign-on to the world (Owners account). The command layer's account changes reach it the same way, as messages.

The realm owner answers character select. It keeps each account's characters while its session is on character select, and every answer that depends on a write waits for its commit, so the client never hears about a character that isn't saved (Owners realm).

A watchdog watches every owner. It reports one that has messages waiting and stops handling them, and in the test harness that stall fails the scenario. It only reports.

Why it's built this way

The client already splits the game three ways: most of its messages travel under one of three routing tags, fixed per opcode, which we read as the account, the realm and the world. An owner per side follows that split, and one thread per owner makes each side's rules easy to reason about, because only one message changes its state at a time.

Idea	What killed it
An actor framework for the owners	None of them has a tick boundary, and the map tick is the unit everything else is timed against

Knobs

Setting	Default	Sets
Account:TokenLifetime	60 s	How long a game token and a session key last; above zero
Realm:Id	1	The realm's id, 0 to 16,383
Realm:Name	NexusTomorrow	The realm's name; required
Realm:Flags, Realm:PvpType, Realm:NoteTextId	0	What the realm hands the client about itself; the PvP type is 0 or 1
Realm:MaxCharactersPerAccount	12	Characters per account, 1 to 50
Realm:StartLocations	none	Per faction: world, zone and position for a new character
Content:ClientDataPath	none	The folder holding your extracted tables, for the creation options

Vocabulary

Term	Means here
Owner	A class that holds one side of the game and changes it only on its own thread, from its own queue
Game token	What sign-on hands the client for the login server: one use, about a minute's life
Session key	What the login server hands the client for the world connection: 16 bytes, one use
Echo	A value the login server hands the client and the world connection checks it sends back

Known edges

• Selecting a character is always refused until step 3's second stage hands it to a map.
• Every login refusal sends the client's general result until the numbered ones are verified.
• The watchdog can't see a handler stuck with an empty queue behind it.

Where the code lives

Piece	Path
The owner base, the watchdog and the session interface	Source/NexusTomorrow.Owners/
The account owner	Source/NexusTomorrow.Owners/Account/
The realm owner, names and creation options	Source/NexusTomorrow.Owners/Realm/
Their wiring and the watchdog's timer	Source/NexusTomorrow.Server/CoreServices.cs, Source/NexusTomorrow.Server/OwnerWatchdogService.cs
Tests	Tests/NexusTomorrow.Owners.Tests/