After some tests of the community, we found that many instances of monsters on a map will cause a lot of memory usage. As I found out, the root of the cause was how we do the pathfinding for the monsters. Because of that, I took this as a challenge to optimize memory and cpu usage.

Reducing memory usage (1)

The major flaw was using one instance of a pathfinder per monster. Every instance of a pathfinder had one instance of a "GridNetwork", which had an array of 65536 possible nodes. These nodes were created by demand, but kept in memory to be reused, until the server closed.

So, the first thing I did was pooling these pathfinder objects per map. A handful of them could easily handle all monsters of a map, because a monster would only search for a path every few seconds, and only if a player is around. This has probably already solved the intial issue, but I wanted more.

Reducing CPU usage

I observed that the preparing of the path finder between each request was pretty inefficient. It still had to reset all the nodes - up to 65k as mentioned above. Additionally, searching for a path in some maps could take longer than expected. Take the Lost Tower map as example. There you have a lot of walls, where the monster would see a player in their range, but could never find a path in a reasonable number of steps. For example, the limit for the walking network packet is 16 steps. The line of sight distance limit of a walk target (MonsterDefinition.ViewRange), is much lower than that (at most: 10).

So, I had the idea of limiting the search of the path to a small segment of the map. To accomplish that, I implemented a "ScopedGridNetwork", which would use a dynamically sized segment, of 8x8 or 16x16 coordinates. To define the segment, we calculate the point in the middle of the start and end coordinates and then check if both coordinates fit into a 8x8 or 16x16 segment.

The smaller segment means less work to do: First, we don't have to prepare up to 65k nodes anymore. Second, we are not dedicating a lot of computation to hopeless requests anymore - we fail much earlier.

Reducing memory usage (2)

So, because we're now using map segments, we can reduce the size of the node array in the network to at most 256 (16x16) elements, instead of 65k.

Now, because the CPU usage was greatly reduced, why not handle all monsters of all maps with a handful of pooled Pathfinding objects? Well, I implemented this as well, of course :-)

Summary

Thanks to this changes, we have now a very efficient pathfinding implementation in OpenMU. To give you an idea: One pathfinding request takes an average of 0.025 ms on my machine (Ryzen 9 5900X). That means, it can handle about 40k pathfinding requests per second, per cpu core.

I want to show a nice powerful feature of the OpenMU Project - the Attribute System.

First, I want to describe some terms:

• Attribute Definition: Describes the attribute itself. For example, we have definitions for each possible attribute, such as Strength, Agility, Character Level.
• Stat Attribute: It's an attribute which is saved individually for a character. A stat attribute can be increasable by the player (e.g. Strength, Agility, etc.) or just increasable by the program code (e.g. Level, Current Health, etc.).
• Attribute (Value): The value of an attribute of a game object, e.g. Character A has '50 Strength'. Values are all handled as 32 bit floats.
• Attribute Relationship: It's possible to define relationships between attributes. For example, "1 Strength -> +0.25 Maximum Damage".
• Attribute System: An object which holds and manages all attributes of a game object (e.g. Player, Monster). Every game object which attacks or can be attacked has an Attribute System object.
• Item Option: An item option holds a so-called "PowerUpDefinition" which defines which target attribute is increased by which value. The value can consist of a constant value and/or attribute relationships. For example, you could define an option which increases the base damage by the character level.
• (Passive) Skills: The master skill system of MU Online has some skills which give some power-ups when they're learned. These power-ups are also described with a "PowerUpDefinition", just like item options.
• Attribute Requirements: It's possible to define attribute requirements for Items, Skills and Maps. E.g. 'Sword X needs 100 Strength to be equipped' or 'Skill Y uses 20 Mana' or 'Map Icarus requires the attribute "CanFly" greater than 0' (which is given by Wings or a Dinorant).

The attribute definitions, relationships, base values, requirements and item options are all defined as data in the database. So, as you can see, the system as a whole allows you to tune every tiny bit of your in-game formulas and to customize a lot without changing a line of code.

How to use

Attribute Relationships

One of the most important things are the attribute relationships. You can find these in the CharacterClass configurations of each character class. In the example above, 1 Strength is multiplied with 0.25 to get the additional value for the maximum damage.

Instead of multiplying, there are other operators available, too. You can do simple additions or even exponentiate the source attribute with a value. There is one limitation for attribute relationships, though: Stat Attributes can not be defined as targets. For Strength, etc. there are two attributes: BaseStrength (stat attribute) and TotalStrength (can be a target); There is actually a relationship which adds the BaseStrength to the TotalStrength.

Example 'Dynamical experience rate'

By dynamical, I mean calculating the rate based on some other attribute, such as the character level. Usually, game servers are configured with a fixed experience rate, for example 1x or 1000x which is applied in the same way to every character.

Since the 'experience rate' is an attribute of a character, it's possible to adjust it by defining additional relationships. The default attribute value here is 1. However, what about defining something like 'Add the square root of the character level to the experience rate'. For example, a level 9 character would be given an additional rate of 3, whereas an level 225 will get an additional rate of 15.

With the available exponentiate operator we can also calculate square roots, when we choose 1/2 as the operand.

To actually configure this, we need to navigate to the character class configuration in the Admin Panel:

• First, navigate to the Game Configuration
• Then, scroll a bit down to the Character Classes, expand them and click the edit button for one of them, e.g. Dark Knight:

• At the character class page, you'll find the list of attribute relationships (called AttributeCombinations) a 'Create' button when expanded. When you have opened the creation dialog, fill in the following:

Hit Submit, Save and it's done. Well, a server restart is still required - I'm working on that ;)

More use-case ideas

So, if you not already identified some more practical use-cases I want to give you some ideas:

• Modify or add new item options
• Giving new attributes to Items, Monsters, Character classes
• Defining attribute requirements for Items, Maps
• Modifying the damage calculations by changing the relationships in the character classes
• Adding new attribute definitions and relationships to the game which you may use further to restrict Map access or give some new powers.

I want to give a short status update on the OpenMU project.

Recap of 2019

As you may remember, I set some goals for 2020.

Stabilizing and getting the Network-NuGet out

I put some effort in solving some edge cases in the network code - primarily related to error handling and detecting disconnections. There have been some usages of obsolete System.IO.Pipeline functions, which I resolved.

Additionally, I improved the API of the network & packets API. There are now simple extension methods for IConnection to send specific packets. They're automatically generated by the packet definition XML files, too.

Last but not least, I released nuget packages on nuget.org, so that other applications can make use of this API.

Release of an updated Network Analyzer

TODO

Completion of the Quest System

I completed the first part of it. The old quest system with the level 150, 220, 380 and 400 quests was implemented and tested. I hope that I can implement the other quest system without much changes to the logic, but only by adding its data. Time will tell.

Getting other game features done

I started solving some gameplay issues and missing features:

• Implement usage of ammunition (Arrows, Bolts) for Bows/Crossbows
• Automatic Health Regeneration in the Safezone
• Weather System
• Drop Level for Event Items
• Ancient Sets
• Chaos Machine Combinations (in progress, about 30% done)
• Fruit consumption

From the community, I received some nice contributions of chat commands. Thanks for that!

Simplifying/Modularization of the server -> Public API

I implemented a basic public API. However, further modularizing the whole server architecture will take some more time and has not a high priority at the moment.

I think of implementing the "servers" as IHostedService which would run on a Generic Host. It would give us some nice built-in goodies, such as logging and dependency injection.

Other improvements

Blazor

One big change was the technological switch of the AdminPanel from React/Redux to server-side Blazor. The reasons for the change were:

• Keeping most of the code in C#
• Less and simpler code. React/Redux involves alot of boilerplate code which is sometimes hard to follow.
• Being more productive. If I compare how much time I spent on react/redux and on blazor, I can say that I got more features done in blazor in less time.

One big improvement is now the ability to edit the server configuration and account data on the admin panel. Not only small parts of it, but every tiny bit. The user interface is dynamically generated by reflection. Not the fastest way, but you would be surprised how fast it is anyway. If performance of that is ever a problem, there are still ways to improve that.

There is still a lot of things to do in the AdminPanel:

• General polishing, adding user-friendly field names and descriptions
• Adding some kind of editors, also graphical ones (e.g. for gates of maps)
• Adding authentication
• Better error handling on generic edit pages which tells the user what went wrong.

Documentation generation

I implemented the automatic generation of packet documentation with a XSL transformation which takes the packet definition XMLs and transforms them to markdown files.

Additionally to that, I set up GitHub Pages with Jekyll, which takes these all documentation of the git repo folder docs and spits out html files. You can see a link to the documentation at the menu of this page.

For a test of the new nuget packages of MUnique.OpenMU.Network.Packets I wrote a small demo client.

You can find the source code here: https://github.com/sven-n/MuConsoleTestClient

It encapsulates most of the packet creation and parsing for you, so you don't have to mess around with bits and bytes yourself. Recently, I also added some automatically generated extension methods to make sending packets easier than ever.

Have fun :)

Hey folks, in this post I want to recap what was accomplished in 2019 and what will come next in 2020.

All the way to .net core

We managed to migrate the whole project to .NET Core 3 and also 3.1. This enabled some new opportunities, simplifications and optimizations in the code base.    

Docker

With the help of some people of the community we managed to provide a Dockerfile and a publish images on DockerHub. Additionally, there is a docker-compose configuration to deploy a server including the postgres database with one simple command. You can find the required information in the QuickStart-Guide.

Packet Structures

In the previous posts I talked about how ref structs can be used to parse and write data into a Span<byte> and how these structs can be generated from some data on compile time. I managed to set up a XSL transformation to make that happen, changed almost all of the affected code to make use of these structs.

The first tool which benefits the most of this yet is the NetworkAnalyzer. There is no new release with it yet, however if you can compile it yourself, you‘ll be surprised how well it extracts all the available data out of the network data.

I plan to release a NuGet-Package of the Network-Assembly to make it easier to develop other network based tools for the game, too.

Plugin System

Another great addition this year was the introduction of a plugin system. It allows us to select the right plugins for each connected client separately, depending on the game client version. For the outgoing messages, I basically broke up all the „Views“  (interfaces with a lot of methods) into smaller "ViewPlugIns" which mostly only have one method and send one message. On the incoming side of data, I made a "PacketHandlerPlugIn" out of every existing "PacketHandler".

This enabled new possibilities to support other game clients than only season 6. However, the main focus is still season 6. Anyone is free to add their own plugins to support newer or older clients, though. It’s even possible to connect to the same game server and join the same game world using two different game client versions. I managed to do that with Season 6 and one of the oldest MU Online versions which you  can find - 0.75. At the moment, I have no more interest in extending the 0.75 stuff, because this client is buggy as hell - nobody would ever want to play it in this state. However, in the future I also want to add support for 0.97d where more stable clients are available.

Of course, there are other use cases for plugins as well. In the code you can find several plugin extension points where custom code can be plugged into.

Ancient SimpleModulus

In order to make the server compatible with a game client of version 0.75, I also had to make the network encryption work. It turned out that this version used the very first variant of the SimpleModulus algorithm. After banging my head on the keyboard a few times I managed to find out that this variant uses a much bigger block size than the newer variant. With some luck, I managed to decrypt the client side encryption keys and calculated the server side ones after I adapted the key generator.

This all also helped me to better understand the algorithm, so I implemented some minor improvements to support longer keys with the same code base, too.

Quest System - In progress

To get some game features done, I started to begin implementing the quest system. It’s currently still incomplete. The first thing which was done is defining all the required network message structures and implementing the corresponding View- and PacketHandler-Plugins. Then I went further and tried to make some sense out of packets I captured a decade ago on the original Global MU Online server and implemented some of the game logic.

Now, what’s missing is the initialization data for all the available quests and a lot of testing ;)

Outlook for 2020 and beyond

Disclaimer: I have a lot of ideas for the future, but unfortunately I lack of time. This will probably even get worse because I got a new job starting with this year which will need my full focus. I still hope to get something nice done this year.

My goals for this year are:

• Stabilizing and getting the Network-NuGet out
• Release of an updated Network Analyzer
• Completion of the Quest System
• Getting other game features done which are lurking around in the GitHub issues
• Simplifying/Modularization of the server -> Public API

In my previous post I have presented my new idea of handling network packets using ref structs. In this post I want to explain how I'm planning to use them in OpenMU and how this fits into the big picture.

Packet structures as data

The first thing to do is building up something like a database of message struct definitions. I want to save the following stuff for each packet:

• Struct Name
• Descriptions ('sent when?', 'caused reactions?')
• Header type (C1 etc.)
• Code and SubCode, if applicable
• Direction
• Expected length, if known
• Fields, for each field:
  • Index of the field in the struct
  • Size
  • Type (Integer, String, Enum etc.)
  • Byte order (endianness)
  • Name
  • Description
• Enum Types, for each with their possible values, including names and descriptions. If an enum is used by more than one packet, an external definition should be possible.

As you see, I want to define more than just what's required to generate some struct code. I also want to be able to generate a documentation of all message structs. This also means, whenever a message gets extended or needs to be handled by the server, the corresponding data must be extended beforehand.

A similar, but incomplete collection of this data is already contained within the Network Analyzer project in some XML files. These files could be replaced with the new approach, once it's complete. How the new data is stored, isn't clear yet. I have some ideas, but it's too early to talk about it.

Generating and Compiling

The next step is generating the code out of the available information. The generated code could look like this:

/// <summary>
/// Is sent when:
///   The client opened an quest NPC dialog and decided to start an available quests.
/// Causes the following actions on the server side: 
///   The server decides if the character can start the quest. A character can run
///   up to 3 concurrent quests at a time.
/// </summary>
[SentWhen("The client opened an quest NPC dialog and decided to start an available quests.")]
[ReactionsOnServer("The server decides if the character can start the quest. A character can run up to 3 concurrent quests at a time.")]
[Direction(PacketDirection.ToServer)]
[Length(9)]
public ref struct QuestInitializationRequest
{
    public static byte Type => 0xC1;

    public static byte Length => 9;
    
    public static byte Code => 0xF6;
    
    public static byte SubCode => 0x0A;
    
    private static readonly byte QuestNumberIndex = 4;
    
    private static readonly byte QuestGroupIndex = 6;
    
    private static readonly byte UnknownFieldIndex = 8;

    private Span<byte> data;

    private QuestInitializationRequest(Span<byte> data)
    {
        if (data.Length < Length)
        {
            throw new ArgumentException($"Expected a span which is at least {Length} bytes long");
        }
        
        this.data = data;
        
        var header = this.Header;
        if (header.Type != Type)
        {
            throw new ArgumentException($"Wrong header type. Expected: {Type}, Actual: {header.Type});
        }
        if (header.Code != Code)
        {
            throw new ArgumentException($"Wrong header code. Expected: {Code}, Actual: {header.Code});
        }
        
        if (header.SubCode != SubCode)
        {
            throw new ArgumentException($"Wrong header sub code. Expected: {SubCode}, Actual: {header.SubCode});
        }
    }
    
    /// <summary>
    /// Gets or sets the header of this message.
    /// </summary>
    public C1HeaderWithSubCode Header
    {
        get => new C1HeaderWithSubCode(this.data); // this could be another ref struct
    }

    /// <summary>
    /// Gets or sets the number of the quest which should be initialized.
    /// </summary>
    [FieldDescription("The number of the quest which should be initialized.")
    [BigEndian]
    public ushort QuestNumber
    {
        get => this.data.GetWordBigEndian(QuestNumberIndex);
        set => this.data.SetWordBigEndian(QuestNumberIndex, value);
    }

    /// <summary>
    /// Gets or sets the group of the quest which should be initialized.
    /// </summary>
    [FieldDescription("The group of the quest which should be initialized.")
    [BigEndian]
    public ushort QuestGroup
    {
        get => this.data.GetWordBigEndian(QuestGroupIndex);
        set => this.data.SetWordBigEndian(QuestGroupIndex, value);
    }

    /// <summary>
    /// Gets or sets an unknown field.
    /// </summary>
    [FieldDescription("An unknown field")
    public byte UnknownField
    {
        get => this.data[UnknownFieldIndex];
        set => this.data[UnknownFieldIndex] = value;
    }

    /// <summary>
    /// Performs an implicit conversion from a Span of bytes to a <see cref="QuestInitializationRequest" />.
    /// </summary>
    /// <param name="packet">The packet.</param>
    /// <returns>
    /// The result of the conversion.
    /// </returns>
    public static implicit operator QuestInitializationRequest(Span<byte> packet) => new QuestInitializationRequest(packet);

    /// <summary>
    /// Performs an implicit conversion from <see cref="QuestInitializationRequest" /> to a span of bytes.
    /// </summary>
    /// <param name="packet">The packet.</param>
    /// <returns>
    /// The result of the conversion.
    /// </returns>
    public static implicit operator Span<byte>(QuestInitializationRequest packet) => packet.data;
    
    public static ThreadSafeWriter StartSafeWriting(IConnection connection, out QuestInitializationRequest message)
    {
        var writer = new ThreadSafeWriter(connection, Type, Length);
        var span = writer.Span;
        span[2] = Code
        span[3] = SubCode;
        message = span;
        return writer;
    }
}

Once this is compiled, we could push this to a NuGet repository. This could also be done automatically by the continuous integration build.

Workflow

So, when adding a new field or message we first have to get an updated NuGet package. The workflow would be as follows:

1. Extend the data, push to Git
2. CI will build and push it to the NuGet package repository
3. Wait some minutes...
4. Update the NuGet package reference in the consuming project (e.g. GameServer, Network.Analyzer)
5. You're ready to use the new message structures

Usage

So, now we have a NuGet package which can be referenced by the GameServer and used in all of the packet handler and view plugins. I want to give a short example about how to use them.

Reading messages

public class QuestInitializationRequestHandler
{
    public void HandlePacket(RemotePlayer player, Span<byte> packet)
    {
        QuestInitializationRequest request = packet;

        // now you can work with the fields of the request:
        Console.WriteLine(request.QuestNumber);
    }
}

Writing messages

public class SomeClass
{
    public void SendRequest(IConnection connection)
    {
        using (var writer = QuestInitializationRequest.StartSafeWriting(connection, out var message))
        {
            message.QuestNumber = 1234;
            message.QuestGroup = 42;
            writer.Commit();
        }
    }
}

Why?

You might ask, why should I do that? Well, I see the following benefits:

• A precise and consistent documentation is enforced, can be automatically generated and is even available in code.
• Less errors when parsing and serializing messages, assuming the data is correct
• We get a reusable message library (e.g. network analyzer, client simulator)
• Writing code which writes code is always fun ;-)

The downsides are obviously:

• Additional work. However, if we want a complete documentation about all message types, this kind of work is required anyway.
• Additional build step. Because we'll reference a NuGet package for the messages, whenever we extend the messages we have to wait for the build to complete and for the published NuGet package update.

All in all, I think it would be worth the effort.

Versioning

As you might know, the OpenMU game server supports network protocols of multiple game client versions since a few weeks. The idea would be to create one struct definition per variant, like we also use different packet handler and view plugins in the game server.

As you may know, parsing and serializing network packets in .NET in a safe, performant and elegant way can be quite tricky. There are several ways of doing it, but none really satisfied me in all of these aspects.

Recently, I stumbled across ref structs which got introduced with C# 7.2. As you might know, OpenMU already handles incoming data packets as Span<byte>, because it never allocates data on the heap for each packet and therefore reduces stress at the garbage collector. It's basically a reference to a piece of memory, e.g. a part of a buffer array which might be part of an array pool. A Span<byte> is a ref struct as well. I don't want to go into details here, but these ref structs have some constraints, such as you can't hold them in a field of a class or a regular struct. However, you can hold it in a field of another ref struct - that's what I'm trying to do.

This allows to define ref structs like this:

    public ref struct SomeMessage
    {
        private Span<byte> data;

        private SomeMessage(Span<byte> data)
        {
            // You could add length/header type checks here :)
            this.data = data;
        }

        public byte SomeField
        {
            get => this.data[2];
            set => this.data[2] = value;
        }

        public static implicit operator SomeMessage(Span<byte> packet)
        {
            return new SomeMessage(packet);
        }
    }

I think you know what I have in mind, don't you? ;-) Basically, this message struct encapsulates the underlying Span<byte> and offers a simpler access to fields. Additionally, you can now implicitly cast a Span<byte> into a message structure like this:

void HandlePacket(Span<byte> data)
{
    SomeMessage message = data;
    Console.WriteLine(message.SomeField);
}

So, the packet handling code doesn't have to mess around with indexes anymore and isn't allocating memory on the heap. Of course, now the struct has to know all the field indexes, how these fields are aligned and how bytes are ordered. To solve this, I have another idea which I'll describe in another blog post.

react and redux are basically independent libraries. You can use react without redux and redux without react. What glues both together is the react-redux library. I don't want to write a full blown tutorial about react and redux, so I'll keep it short.

Disclaimer: I'm not an expert. My explanations could be naïve ;)

react

react is obviously the library which renders the components to the DOM.

redux

redux offers mechanisms to handle the state of your application.

react-redux

react-redux is used to "connect" your React components to the store.
It has the 'Provider' component which makes your store available in its contained components (your app). It offers the "connect" method which has knowledge of this provided store. In your components you basically define all of your application state and actions in your props and don't access the store directly.

presentational and container components

In React it's usually a good pattern to separate your components into Presentational- and Container-Components - this can be achieved easily with Redux.
Your presentational component defines as props just what it's showing and not the source for a data aggregation.
An example would be the LogNotifier component:

interface LogNotifierProps {
    showError: boolean;
    subscribe: (subscriber: any) => void;
    unsubscribe: (subscriber: any) => void;
}

class LogNotifier extends React.Component<LogNotifierProps, {}> { … }

As you can see, the component itself doesn't define all log entries in the props to be able to figure out itself, if it should show a sign or not. Instead, it just defines showError. The mapStateToProps function which is used by the connect function of Redux, determines showError.

const mapStateToProps = (state: ApplicationState) => {
    return {
        showError: anyEntry(state.logTableState, "ERROR"),
    };
}

const mapDispatchToProps = (dispatch: any) => {
    return {
        subscribe: (subscriber: any) => dispatch(logSubscribe(subscriber)),
        unsubscribe: (subscriber: any) => dispatch(logUnsubscribe(subscriber)),
    };
}

const anyEntry = (state: LogTableState, logLevel: string): boolean => {
    for (var i = state.entries.length - 1; i >= 0; i--) {
        var entry = state.entries[i];

        if (logLevel.localeCompare(entry.Level.Name) === 0) {
            return true;
        }
    }

    return false;
}

export default connect(mapStateToProps, mapDispatchToProps)(LogNotifier);

I finally finished the migration of the AdminPanel from JS/JSX to TS/TSX and fluxxor to Redux. I want to show you a short summary of pitfalls which I encountered and how I solved them.

Not using npm

When working with JavaScript you almost can't get around using npm. However, I'm not a fan of including too many dependencies in the code and the npm makes it too easy to introduce them.
My workflow of adding a new library is therefore a bit different.
One thing to note is, that the TypeScript compiler uses the module system of SystemJS by default. The syntax is basically a new standard which will be implemented by future browsers so that the SystemJS lib will not be required anymore.

Disclaimer: This post only includes a small part of the libraries which I had to include. For the full code, better look at the GitHub repository.

TypeScript Configuration

To be able to use aliases in imports, like import Redux from "redux"; instead of defining the path of the library in every ts/tsx file, I have to add them manually at the tsconfig.json in the paths:

  "compilerOptions": {
        "paths": {
          "*": [ "*" ],
          "react": [ "Scripts/react/index" ],
          "redux": [ "Scripts/redux/index" ],
          ...
        }
   }

Running the code

To use the code at runtime, so that the browser is able to resolve and run, I had to add SystemJS and the generated code as scripts in the index.(ss)html:

<script src="@Path['~/content/js/system-production.js']"></script>
<script src="@Path['~/content/js/app.js']"></script>

The app.js was generated by the TypeScript compiler and is actually registering the modules/components at SystemJS, example:

// generated code at app.js:
System.register("components/App", ["react", "react-dom", "react-redux", "components/Layout", "stores/store"], function (exports_37, context_37) {…}

This raises the question how SystemJS should know what "redux" or "react" means? We have to "map" them manually:

<script>
            System.config({
              map: {
                'react': '@Path['~/content/js/react.js']',
                'redux': '@Path['~/content/js/redux.js']'
              }
            });
</script>

• To run the app, I'm calling System.import on the App-Component:

System.import("components/App")
                .then(m => console.log('App module resolved'))
                .catch(err => console.error(err));

This component directly calls ReactDOM.render:

// components/App.tsx:
import React from "react";
import ReactDOM from "react-dom";
import { Provider } from "react-redux";
import { Layout } from "./Layout";

import configureStore from "../stores/store";

const store = configureStore(…);

// This here is our entry point
ReactDOM.render(
    <Provider store={store}>
        <Layout />
    </Provider>, document.getElementById("content")
);

Voilà, the app renders :)

Conclusion

All in all, the setup was a bit tedious, because I had to read through all possible documentations. I found no "boilerplate" example of setting up an environment like mine (React & Redux & TypeScript in a VS project without npm). However, I think it was worth it. I'm now very productive at extending the AdminPanel. Using types makes refactoring easier and obvious bugs are found faster by the compiler without running the code in the browser.
When selecting new libraries I now have to look after TypeScript definition files, which is a bit tedious... another point which prevents me to add new dependencies without explicitly thinking about the consequences.

What's next

It seems like bootstrap is already 'old-school' and material-ui is the new 'standard' for React based web-apps. It looks great, but I'll have to see if it makes sense for the project.

Maybe I'll add some unit tests for the TypeScript code, too. As I read in some tutorials this seems to be easy :)

Problem

With an extension of initialization data, where I added definitions of NPCs and Monsters and their spawn points to about 10 game maps, I noticed that the time to start the server went up dramatically - from ~13 seconds to over 1 minute. The reason was, that my strategy to load the whole game configuration at the start at the server led to almost 2000 SQL queries. As the configuration data is not yet complete, you can already guess that if nothing had been changed, the loading time would ramp up further, probably to 10 minutes or more.

Idea

I had created a GitHub issue and came up with a nice approach. The idea is to load the whole object graph of the GameConfiguration with just one query. PostgreSQL has functions to build JSON for the query result, even very complex ones with deeply nested subqueries. So I got the idea that I could build queries based on the entity framework meta model of the GameConfiguration class. The result of the query can then get de-serialized to a GameConfiguration object and if possible, added to the change tracker of the entity framework. EntityFrameworkCore supports adding objects (and their child objects) to it's context from the outside. And we could also tell the context that it should treat this data as 'unchanged' - so we could still do changes to the object and EF Core would figure out what needs to be changed on the database to save them. Best of both worlds, if all goes well :)

Implementation

SQL Query Building

To create the query, I pass a IEntityType (meta data about the entity type) of GameConfiguration to the JsonQueryBuilder. It will programmatically build up a complex SQL query which uses PostgreSQL JSON functions. The resulting query has a size of about 18 KB, so it's too big to show it in this blog post. It looks like this:

select result."Id" "$id", result."Id", row_to_json(result) as GameConfiguration
from (
    select a."Id", a.*, (
       -- additional subqueries which return json of collections and other navigation properties
    )
    from config."GameConfiguration" a
) result;

The process to create this query is actually pretty fast (~10 ms) and we could cache the result as the query would never change after the program has been started.
The result of the query is currently a JSON string which is about 21 MB in size. I suspect there is some garbage in it, but at the moment it's fast enough - room for improvement, however. The query returns the data in a little bit under 2 seconds on my system.

De-serializing

I'm using Newtonsoft.Json in version 9 to de-serialize the JSON back to an object. One de-serialize call takes about ~600 ms, which is also not so bad if you look at this amount of data. However, we need two calls to get the final result, to resolve all references.

Byte Arrays

I needed to write a custom JsonConverter to de-serialize byte arrays. Newtonsoft.Json expects a base64-encoded string. However, PostgreSQL gives us the data in a hexadecimal encoded string.

Reference resolving

To prevent that every object is serialized over and over again, I use $ref-objects to reference these objects by their id (GUID). To resolve these objects, there is a resolver. Whenever Newtonsoft.Json finds an object with "$id" as first property, it adds it to the resolver. However, it reads the JSON just one time in forward direction, so a reference to an object which was not yet added to the resolver yet, can't be resolved. The object model of GameConfiguration contains some circular references, so this is actually happening. The current solution is, that we de-serialize the JSON two times - this leads to other problems as you will see below.

Remaining problems

Change Tracker

We need to de-serialize the JSON of the GameConfiguration twice, because the document contains circular references which can't be resolved otherwise. The first run is just there to pick up all objects. In the second run these objects are used in the IdReferenceResolver to resolve the $ref-objects.
So in the end the resulting GameConfiguration might contain objects with the same id but being a different object instance. However, the change tracker of EF Core can only keep a look at one instance per id. As a result, an exception is thrown when you try to add two different instances with the same id.
So for now, the DbContext to load the game server configuration doesn't track changes anymore. That's not so much of a problem at the moment, as we don't modify it.

One solution could be to replace all instances of the first run, which still sit in the GameConfiguration object, by the "new" one which has been created in the second run.

Newtonsoft.Json is pretty limited in this particular case. It would be nice to be able to postpone reference resolving until the whole document has been read.

Serialization of back references

See also Issue #11 - when we fix this, we can expect further performance gains and we'll be able to use it to load Account objects. These are candidates for getting very complex, too.

Summary

The JSON functions of PostgreSQL are a great way to load complex object graphs with just one roundtrip to the database. We have some minor issues left, but I'm sure we can solve them. Additionally, there is still a lot of performance to gain because the query retrieves obviously too much data.
If we manage to optimize that, we keep all benefits of a relational database and still only need one roundtrip to load complex data - so we have no reason to switch to a document database, yet :)