Contributing code patterns - rebaserHEAD/NexusForever GitHub Wiki

The structural habits of upstream's world-side code: which project a thing goes in, how it's registered, and the shape each kind of class takes. The step-by-step path for one per-character feature is on Adding a player feature; this page is the rulebook behind it. Where an old and a new pattern sit side by side, the tables say which one new code follows. Line-level style is on Contributing code style.

Project references run one way, from pure data up to the host. Content scripts sit beside Game, seeing only Game.Abstract and Script.

flowchart TD
  S[Game.Static: enums] --> D[GameTable, Network.World, Database.*]
  D --> A[Game.Abstract: interfaces]
  A --> G[Game and Script]
  G --> W[WorldServer: host]

Game.Abstract is a contract layer, but not a pure one: its interfaces extend the database save interfaces, and some of them return message models.

Package versions live in Source/Directory.Packages.props, and a project file names a package without a version. The maintainer updates them in batches.

Every folder with services has its own ServiceCollectionExtensions.cs holding one method, Add<Project><Folder>(this IServiceCollection sc), called from its parent folder's. AddGameMatchingMatch lives in Game/Matching/Match/ and is called from AddGameMatching.

MatchManager, ChatFormatManager and PublicEventTemplateManager are the new shape of a global manager. CurrencyManager and GuildManager are the new shape of a per-character one.

A global manager is wired into WorldServer/Service/HostedService.cs in up to three places: its Initialise in the start-up list, which is ordered and says so in comments where it matters; its Update in the tick; and its save on shutdown.

GameMessageOpcode, in Network/Message/, holds every opcode for both the auth and the world server. Values are four hex digits, sorted, with the = aligned. An opcode nobody has identified yet is named after its value, such as Server0635.

Upstream doesn't require a handler to hand its work to a manager, and some carry real logic. A thin handler that calls a manager on session.Player is still the easier review.

Broker handlers are a separate path: IHandleMessages<T>, registered with AddRebusHandler and subscribed in NetworkInternalHandlerHostedService. Leaving out either one still compiles.

Socket threads queue each packet, and the world update drains every session's queue in order, so message handlers run on the update. Maps update in parallel by default; MapConfig.SynchronousUpdate turns that off. Broker handlers run on the broker's threads.

Title.Save is the model for the create and update paths, stock comments included:

1. Nothing changed: return.
2. Create: context.Add the whole model.
3. Delete, where the class supports it: a model holding only the key, with its state set to EntityState.Deleted.
4. Otherwise: context.Attach a key-only model, then set IsModified on each column whose bit is set.
5. Reset the mask.

The interfaces are IDatabaseCharacter, with Save(CharacterContext), and IDatabaseAuth, with Save(AuthContext). IDatabaseState adds PendingCreate and PendingDelete. Saves on the world side run without an explicit transaction.

Which database owns what, and how tables and columns are named, is on Databases. Migrations are EF Core code-first, generated by the tools and named yyyyMMddHHmmss_PascalName. A new database's first migration is HelloWorld.

How tables load is on Game tables.

A new permission also needs its row in the auth database (Adding a player feature).

Patterns in the code not to copy:

• A few services are registered twice, and the second registration wins.
• Three folders under Game/Entity spell their file ServiceCollectionExtentions.cs.
• Some handlers kept their old name when their message was renamed.