There are plenty of complexities involved with writing a game that has online multiplayer. Even if you solve all the challenges to keep the game state in sync between all your players, there is one problem left: how do the players connect in the first place?

Usually we begin by using direct IPs. Many older games actually worked this way, as it is something that doesn't need somebody to negotiate the connection. Using IPs doesn't really scale well, though. It only works if you already have a friend to play with, they are technical enough to find their IP, make sure their router forwards to their local machine, and disable the firewall on that specific port. This is hardly release-worthy in the era where in most games, connecting is as simple as right-clicking a name in your friends list to join them.

We can avoid all this complexity by only ever having a single endpoint we need to talk to. If we could have a server that manages everything for us, we'd be good.

There are two models here: dedicated servers, and master servers. On a dedicated server, the game simulation actually runs on a server we control, and just receives the inputs from and sends the results to the players. This is a model often used by games where cheating is important to prevent, or where there is no clear lobby owner.

Master servers only negotiate connections between clients. Once the connection is made, they back out and let the clients figure it out themselves. The actual game simulation usually ends up being done using a host-client model (where the host simulates everything), or a peer-to-peer model (where each client simulates their own things). Today, we are only going to look at how a master server works.

Master servers

Let me try to explain master servers using a metaphor. Connections are like a piece of rope connected to two metal cans through which you can talk to each other. In a direct connection, you try to throw over the can to your buddy to talk directly, but you have to know where they are, and the firewall has to be out of the way. In the master server model, you throw your can to the master server instead, which often has an obvious position (e.g. a web address or an IP coded into the game logic) and a firewall open to these connections.

Once the connection with the master server is initiated, a host can tell the master server that is has a lobby. The master server will then keep track of that locally. If clients ask for open lobbies, the master server can respond. When the client decides to join a certain lobby, the interesting part happens: since the two sides of the connection have initiated a connection already, there's an exact address on each side, and a hole through the firewall to let messages through. The master server sends one can on each end of the rope to each of the peers through the existing connection, and a direct connection is established. From then onwards, the peers communicate directly, and the master server can drop the connections itself. This makes master servers especially relevant for games that can't afford to maintain dedicated servers, since the computational power needed is very limited.

This process is often called the NAT punchthrough or a hole punch.

The protocol

The first step in implementing a master server is to decide on a protocol with which your clients will talk to the master server. You could use text, JSON files, or some binary format you come up with. For Bearded.TD, a tower defence game I am currently working on, I decided to go with Google's protocol buffers, which are a protocol for sending serialized messages, with converters for many languages out there, (including C#). This would give me the freedom to work with other languages in the future if needed.

The implementation

For the implementation, we will be using Lidgren.Network. If you need an introduction to how it works, I recommend this blogpost on GameDev.

The first step is to initialize the NetPeer so we are available for connections.

public void Run() {
    var config = new NetPeerConfiguration(options.ApplicationName) {
        Port = options.Port
    };
    config.EnableMessageType(NetIncomingMessageType.UnconnectedData);
    peer = new NetPeer(config);
    peer.Start();

    // Do stuff here
}

Note that we enable UnconnectedData as a message type. This allows us to receive payloads without having to set up a permanent connection.

We could set the master server up to respond only when it receives a message using an event-based system, but I haven't been able to get it set up so that we receive an event from Lidgren whenever a network message comes in. Instead, we will just use a small loop. The added advantage this gives us, is that it allows us to regularly check if the registered lobbies are still active.

public void Run() {
    // Set up code here

    while (true) {
        while (peer.ReadMessage(out var msg)) {
            handleIncomingMessage(msg);
        }

        updateLobbies();

        Thread.Sleep(100);
    }
}

Now the only thing left to do is to handle incoming messages, and update the lobbies. Let's start with the incoming messages: we are going to need some boilerplate to deal with all the different message types Lidgren sends, and the request types we set up ourselves in the protocol file.

private void handleIncomingMessage(NetIncomingMessage msg) {
    switch (msg.MessageType) {
        case NetIncomingMessageType.UnconnectedData:
            var request = Proto.MasterServerMessage.Parser.ParseFrom(
                msg.ReadBytes(msg.LengthBytes));
            handleIncomingRequest(request, msg.SenderEndPoint);
            break;

        // Other message types
    }
}

Based on the type of the message that comes in, we may need to do different things. For example, we want to add the lobbies to a central database of lobbies (I use a dictionary for that), and we will also need a way to return a list of all current lobbies.

Let's take a look at a registerLobby method:

private void registerLobby(
        Proto.RegisterLobbyRequest request, IPEndPoint endpoint) {
    var lobby = new Lobby(
        request.Lobby,
        new IPEndPoint(
            new IPAddress(
                request.Address.ToByteArray()), request.Port), // internal
        endpoint // external
    );

    lobbiesById.Add(request.Lobby.Id, lobby);
}

You can see we keep track of the lobbies in a dictionary by their ID. This allows us to keep track of which lobby is which. It is important that active lobbies keep pinging the master server, since that allows us to get rid of lobbies that weren't active for some time.

The interesting part here is the IP endpoints we keep track of. This is needed for the hole punching later. The endpoint Lidgren gives us for this message is the external IP. We will also need the IP endpoint as the client sees it (the internal IP), so we actually have the clients send that information as part of the request. This is how the client code will send the necessary information to the master server:

var request = new Proto.RegisterLobbyRequest {
    Lobby = lobbyInfo,
    Address = ByteString.CopyFrom(
        NetUtility.GetMyAddress(out _).GetAddressBytes()),
    Port = 24680 /* can be any free port */
};

It is worth mentioning that we never actually set up a persistent connection with the master server. All data is sent without that, which is why we needed to support the UnconnectedData message type earlier.

peer.SendUnconnectedMessage(msg, masterServerEndPoint);

For sending the lobbies to the clients from the master server, the setup is very similar. The client sends a request to the master server that it wants to receive the lobbies, and the master server starts writing them to the endpoint that requested it.

The interesting part comes when we want to actually initiate a connection, i.e. do the hole punch. To initiate a connection, the client that wants to connect to a lobby sends its own endpoints, but it also sends a connection token. It doesn't matter much what the token is, so you could hardcode it.

Now that we have both endpoints, we can do the actual NAT punchthrough in the master server. Luckily, Lidgren.Network actually has built-in NAT punchthrough capabilities. It can be done using the Introduce method in the master server.

private void introduceToLobby(Proto.IntroduceToLobbyRequest request, IPEndPoint endpoint)
{
    if (lobbiesById.TryGetValue(request.LobbyId, out var lobby))
    {
        var clientInternal = new IPEndPoint(
            new IPAddress(request.Address.ToByteArray()), request.Port);
        peer.Introduce(
            lobby.InternalEndPoint,
            lobby.ExternalEndPoint,
            clientInternal,
            endpoint,
            request.Token);
    }
    else
    {
        // Deal with lobby not found
    }
}

When this is successful, the client will get a network message of type NatIntroductionSuccess (so make sure you enable this message type on the NetPeer!). When receiving that message, the client can initiate a normal Connect, for which it should use the endpoint from the message it just got, since that allows it to use the hole the introduction made.

Conclusion

This was a really quick run-through on how to build your own master server. To keep this post to a reasonable length, I had to cut out a lot of details. If anything is still unclear, I recommend you take a look at the full implementation of the Bearded.TD master server. You can find the logic that lives in the actual game here, and the master server itself here.

A challenge

Before I get to the meat of this post, I have a challenge for you. I highly recommend you trying it before reading the rest of this post. The challenge is meant for a pair, but you can do it by yourself by assuming both roles - it will not be as powerful a lesson.

Pick a simple problem. Something like the Conway's Game of Life works well, but any problem of similar complexity will do. In your pair, pick one person who will write the tests; the other person will write the implementation. The process is as follows:

• The tester writes a small test that makes the code go red.
• The implementer writes the easiest possible code to make the code go green again.

Note that the easiest path to green code isn't necessarily the correct implementation. Let me give an example of a hypothetical fixed size list class:

[Fact]
public void Count_ReturnsCorrectSize() {
    var list = new FixedSizeList(10); // make a list with size 10

    Assert.Equal(list.Count, 10);
}

A very straightforward test. There is also a very straightforward implementation:

class FixedSizeList {
    public int Count = 10;

    public FixedSizeList(int _) {}
}

Is this bad code? Yeah. Does it pass the tests? Yeah, and that's really what matters in this exercise.

Now it is up to the tester to write tests in such a way that the easiest possible way to make the code green is to actually implement the correct solution. Repeat until you've had enough, or until the correct implementation exists. For an added challenge, the tester could choose not to look at the implementation at all, and rely on the tests only to create a correct solution.

Once you're ready to see what you can learn from this challenge, read on!

The lazy evil programmer

The exercise above is one of the exercises I do with the candidates of code retreats that I host, and I tend to call the session "lazy evil programmer". Almost without failure, people have a lot of fun with this exercise. For myself, doing this the first time changed my perception on tests forever.

At the end of the session, look at the ratio of test code to production code. In the most likely case, you test code will be anywhere from three to five times as big as the production code, if not more than that. This is often much more than people write in usual setups. Why is that?

Under normal circumstances, we believe we'll do a pretty good job at implementing the correct solution. Going back to the example above: if we test that our FixedSizeList works for size 10, we can reasonably assume it works for other numbers as well, right? Sure, we'll maybe cover 0, a negative number, and if we're feeling particularly scrutinizing, int.MaxValue as well, but after that we move on. Can we really assure our test works with all inputs though?

In the exercise outlined above, the implementing programmer is actually an antagonist, and we can't trust them to do the right thing. If I had written the code myself, in an attempt to make the correct implementation, it would be pretty easy to take the tests as enough evidence of the correctness of my code. This is where the big assumption comes in: I trust my own capabilities in writing the correct code.

Most of the time, programmers write the correct code. However, to err is human, and mistakes will slip in from time to time. Many people agree that if we cannot prove the code is not correct through testing, it may as well not exist (something that the language Vigil tries to solve). Tests often only sample some parts of our code. This comic summarises it pretty well. So why are we satisfied with only some tests, and covering the rest by magic trust in ourselves, often misplaced? As programmers, we are not actively trying to be lazy or evil, but I still believe tests should be written with that assumption. Unintentially, we may be making mistakes or shortcuts, and tests catch those.

What tests to write

This section discusses some strategies for testing, so if you want to try the exercise at the start of this blog post for yourself, this is your final warning to avoid some spoilers.

We can't write a unit test for each possible input. If you tried the challenge above, you may have found that simple unit tests tend to not quite cut it after some time. Especially when the methods become more complex, trying to find a set of covering cases is extremely difficult. This is where we have to turn towards other testing methods.

Unit tests tend to have a fairly standard format: arrange input, act on the test subject, assert that the actual output matches the expected output. To make sure that we don't build code that works only for some inputs (namely the tested ones), but all possible inputs, we can randomly sample all the possible inputs by generating random inputs. The challenge many people run into here is that if you start making the input randomised, the test also doesn't know what the expected outcome is. A common anti-pattern here is to implement the entire solution again in the tests and compare the outputs, but who's to say the test implementation doesn't contain the same bug as the actual implementation (especially since they are usually written by the same person)? What works better in these cases is to verify that certain properties on the output hold.

As an example, let's assume our hypothetical FixedSizeList can be sorted. If we generate a random set of numbers for in the list, we wouldn't want to compare the output to an exact other list, since we don't have a way to generate that (putting aside our trust in Array.Sort). However, a sorted list has one property that is very easy to check: each number is larger than or equal than the previous.

[Fact]
public void Sorted_ReturnsSortedList()
{
    var size = random.NextInt(0, int.MaxValue);
    var list = new FixedSizeList(size);
    for (var i = 0; i < size; i++) {
        list.Add(random.NextInt());
    }

    var sortedList = list.Sorted();

    for (int i = 0; i < size - 1; i++) {
        Assert.True(sortedList[i] <= sortedList[i + 1]);
    }
}

The test is relatively simple to write, and all of a sudden it is really unlikely that the Sorted function is implemented wrongly.

A second way to test beyond unit tests is to focus on system tests. In Conway's Game of Life for example, there is a repeating pattern called a glider. This is a set of alive cells that after four iterations repeats itself, but is moved one tile to the right and one tile to the bottom. This is a very fragile pattern, and any bug in your Game of Life implementation will most likely break this pattern. Yet the outcome is incredibly predictable, so it'd be easy to write a test that takes the glider as input, does 400 iterations, and matches the expected output (which is the same glider, just moved 100 tiles). It is likely to cover all your code branches.

Finally, the challenge posed above itself can provide a good solution to the problem as well: don't write your own tests. If you forget a boundary condition in your code, you are likely to also forget to test for that boundary condition. Because you know what you are testing for, you know exactly what code you do and don't have to write, or vice versa if you are writing the implementation before tests. By having a different person write the tests, you lose all preconceptions about what is and isn't correct about the code, and have a larger chance of catching actual bugs.

What about coverage tools?

One final note before we move on to the conclusion. One tool that has been created to give us programmers more trust in tests, is test coverage. Test coverage is represented as the percentage of lines of code that are executed as part of your tests. While this is an incredibly powerful - and generally under-used - tool, like any tool, we need to be careful about how we use it too. A test running a certain line of code doesn't mean that the correctness of that line is tested as well. This is the danger of coverage tools: if we blindly trust them, we may stop thinking critically, and we're back at being lazy and evil.

Conclusion

Once we stop being able to trust ourselves to write the right code, we realise that we actually need to write many more tests than we usually do to guarantee the correctness of our implementation. This shows that a large part of the evidence of our code's correctness is missing. The only way to truly be certain our code works is to assume to worst, and put maximum effort into making sure that every single bit of code is covered by tests. Randomized testing using property tests, system testing, and having a different person write your tests are among some of the solutions that can help catch more bugs in your code. In the end, code that isn't tested can't be trusted, whether it be written by a lazy evil programmer, or just a lazy one.

User feedback is an important part of any software development. Software is only successful if it is used, and people will only use software if it does what the user wants. Very few (successful) tech companies will have built their product without talking to their users first. Especially with the internet connecting everybody online, it's never been easier to get in contact with your users, whether that is through feedback forms or reading rants on Reddit. With all these extra avenues for users to let themselves be heard, there has also grown an expectation that developers listen to that feedback and act on it. Is that really always the right thing to do for a developer though?

Software exists to fill a user's need. It takes a certain skillset and mindset - both of which can be learned and practised - to understand those needs, and build a solution that addresses them. What I have often seen in online examples of "user feedback" is users sitting on the expert's chair and explaining their problem in the form of a solution. Should we, as developers, adopt those solutions? Not blindly. As a metaphor: a person may complain about having a headache, but the headache is merely a symptom for something else. The same holds for user feedback: if a user is annoyed with some part of your program, that may be because there is a larger underlying problem with it. A good designer knows how to look for these root causes, or at least how to ask the right questions to get closer. This is why user feedback is often gathered from directed surveys or interviews, rather than sourced from social media, as this allows more of a deep-dive into the root causes of users' frustrations.

I wanted to specifically talk about games. On the surface, games are just another piece of software: they are written with code, and they have a purpose (generally to entertain). However, in many ways games are the antithesis to software. Game development, and game design in particular, is an inherently creative process. You can't really quantify fun, if fun is even the primary purpose of a game. Games are a form of expression, not too dissimilar from any other form of art.

Games still rely on feedback for success. In almost any case, we want our games to be played by as many people as possible, and so we want to build something that appeals to our audience. Throughout the entire development process, one question will always come up: how much of our own creative vision are we willing to sacrifice to address player feedback? Often compromises have to be found, or some freedom is given to players to let them enjoy the game how they want, while leaving open the option to play the game as the developer intended it.

When done well, I consider player feedback a privilege. People caring enough about your game to have an opinion, to want to help to improve it, is a reward in its own. When done poorly though, player feedback can be a deprevation of the creative process. In particular when player feedback is forced upon the designer from a publisher or somebody in a similar role.

I want to take a recent example that actually inspired this post: the introduction of so-called Player Agency Groups for the game RuneScape. A representative out of the player community was put on the payroll to work with the developer to address some of the game's pain points. While working together with players on a game can be very rewarding, I cannot help but imagine how I would feel if I were paired up with a player and told to work with them to make the game better. This would be a player without design experience, which comes back to my earlier point that finding actual problems often comes with experience. Not only would I have to deal with that, but there is also the point that making games is a creative process: there is often more than one solution, and sometimes what a player sees as a problem, is actually an important part of the game. A common knowledge in game development is that players don't know what they really want. If you asked them if they wanted to get gold or experience or what have you ten times as fast, they'd probably say yes. However, these values have to be carefully chosen and adjusted to find the right balance of engagement. Players will often also want their particular playstyle be advantageous over others. Designing a good game is finding the balance between all these problems, which is often more of an art than a science.

The best example of player feedback that I have experienced is discussing the difficulty of Roche Fusion. From the get-go, it was meant to be a hard game. While more accessible than an average bullet hell, we definitely wanted to stay true to its legacy that the games are challenging at least. A lot of players struggled with that, and asked for the game to be made easier. We added an easy difficulty mode in the end. To this day, people believe that the normal difficulty mode should be called hard, and the easy difficulty normal, but in this case we decided to stay true to how we think the game was meant to be designed.

Player feedback, and user feedback in general, is a complex topic. It is probably best summarised as "can't live with it, can't live without it". I do believe that a certain level of entitlement has developed among players who expect to be heard, and it is up to developers to find the right balance between listening to that feedback, and trusting both their own creative vision and experience as a designer to make the right decisions. However, it is in our collective interests to realise that - while we are all entitled to opinions - making games is both a craft and a creative process, and we should respect a designer's skills and vision.

Recently I noticed that in a codebase I worked on, the canonical way to format money had changed from a global formatMoney function to an extension method on money: money.format. A special formatter, formatMoneyWithoutCurrency, suffered an equal fate. Almost immediately, something felt off. The Money class was up to that point purely functional, but this extension method started adding methods to the class' public interface that were rendering based.

There is nothing fundamentally wrong with having a format method on a class, but it does expand a class' responsibilities beyond its original scope of being a functional type. In most languages, formatting is generally done by creating an instance of some sort of formatter, and giving the value you want to format as input. The formatter's responsibility is exactly to turn a value into a string, whereas the original class' responsibility is to just do whatever it actually does (being money in the example above).

The global formatMoney method is in fact a helper method. If we got rid of the abstraction, we would get something similar to MoneyFormat.forLocale(currentLocale).format(money) instead. However, for performance reasons we want to cache the creation of the formatter, and for consistency reasons, we want to make sure every instance of the formatting uses the same basic formatting configuration, hence the helper method.

The abstraction to a global method makes sense, though I would argue in hindsight that having the money formatter be a global getter moneyFormatForLocale instead would make the formatting much more explicit. It is also in line with, say, Numberformat.percentage.format(num). One can always discuss what is the best way to do it, and there is no single right answer, but I hope we can all agree on one thing: there already is a workable solution without extension methods for formatting money that reveals intent (it is clear what it is trying to do with the money), is extensible (I could easily have a completely different formatter for my money if I want), and avoids unnecessary repetition of code (I only need to specify the format I want). So where did the extension method come in?

What are extension methods good for?

Let's take a step back and look at when it actually does make sense to use extension methods. Extension methods are probably most commonly known to be part of C#. Older versions of C# noteworthily does not have the ability to add behaviour to interfaces. This is still something that makes sense to do in some circumstances. LINQ for example is a query language that can be used on all IEnumerable instances in C#, and is completely built with extension methods. This avoids situations such as on the equivalent of LINQ in Java - streams - where you need to specifically call a stream() method on your collection to enter "query mode", and in the end turn it back into a collection to pass it further.

Extension methods can also be used to expand types (not just interfaces) for which the source isn't necessarily under your control, without having to create a subclass for that type. Subclasses allow you to add functionality too, but you don't get the functionality unless you wrap the parent class instances, which may be returned to you from the same library that defines it, and you can't inherit from structs.

Extension methods have allowed for libraries in C# that significantly increase code readability and developer velocity, such as for example the aforementioned System.Linq, and FluentAssertions. Their usefulness has made it so that other relatively modern languages such as Kotlin and Dart have also adopted them. Is it always necessarily a good thing to use extension methods though?

A final use case that extension methods can be used for, is to add domain-specific behaviour to a generic class. It is basically adding a bit of extra flavour to an existing helper class. For example, we may have something that helps us create notifications, a NotificationFactory. This type is widely useful, but within a certain domain we maybe want to build a notification with a very specific style very often. Having a notificationFactory.createForDomain() method, exposing only a subset of parameters, could be incredibly helpful. A solution without extension methods would be to use inheritance, or - even better - composition. An extension method takes away that need, as we don't really need to store additional state. That probably summarises what extension methods are: a substitute for inheritance or composition where no additional state is needed.

What are extension methods NOT good for?

While an extension method is not defined within the type that the extension method is defined on, it is important to remember that the extension method will still be part of its public interface to some extent. That is why one should still consider whether an extension method actually makes sense there. Extension methods shouldn't increase the responsibilities or alter the purpose of the type. If you need a type to behave differently, a new type is more appropriate.

Extension methods should also not be used for behaviour that is not unique defined for the type the method is on. To come back to my format example: formatting a price is not a single, uniquely defined behaviour. Not only is it locale-dependent, it is also context-dependent. The fact that a formatWithoutCurrencyCode also exists already exposes this problem. While using a formatter class using the type as input is more verbose, it is also more explicit, and leaves programmers open to implement other formatting methods if so required. Compare a formatting method to for example a reversed extension method on a list. Reversing a list is well defined, and make sense as part of the public interface of a list.

Should we still use extension methods?

Extension methods are a useful part of the languages. They make it possible to quickly add new methods to a type's public interface. Because we don't actually open the file the type is in, we may be less primed to critically think about whether the type is really the right place to put a new method on. We should scrutinise the addition of an extension method as much as a normal method: does it fall within the responsibilities of the type, and is the method well defined?

Another class of extension methods that exists is the type that makes code read more like natural language. FluentAssertions allows you to write test assertions of the form actual.Should().Be(expected), which reads nicely, but one could argue that Should is hardly part of the class's responsibility (nor perhaps a well-defined behaviour). Based on the arguments presented above, I believe Google's Truth framework in Java does it slightly better with syntax as assertThat(actual).equals(expected).

All in all, when to use or not use extension methods comes down to personal preference, much like any code pattern. That doesn't mean it is not important to blindly add new methods to a type because it's an extension method. At the very least, extension methods should not add ambiguous behaviour, such as formatting, to a type. As with everything: extension methods provide great power to the programmer, and with great power comes great responsibility.

In the previous post, we saw how to do the math to get velocities and positions along an elliptical orbit. To translate this into game code though, there is still one problem we have to solve. So far we have spoken about apoapsis and periapsis as determining the shape of the ellipse that describes the orbit, but it doesn't uniquely identify the orbit itself. As you can see in the image below, the rendered orbits have the same periapsis and apoapsis, but they still do not coincide. The orbit has been rotated around the primary, as it were.

To uniquely identify orbits, we need one more parameter, namely where the orbit reaches periapsis. We talk about the longitude of periapsis $\varpi$ with respect to some reference direction. For our code, we will assume the positive x-axis as our reference direction.

We assume that the satellite is at periapsis at some instant $t_{0}$, and we now know that the relative angle with the x-axis at periapsis is $\varpi$. This means we have our starting point, and from there we can use Kepler's equations to calculate the rest.

Current position in elliptical orbit

In the previous post, we showed how to get the current true anomaly based on the elapsed time, the eccentricity, and mean anomaly of the orbit. As a reminder, the mean anomaly is the average change in the direction of the satellite around the primary, so it is just $2\pi$ (a full rotation) divided by the period. To find the period of an elliptical orbit, we look at our good old friend Kepler again. In particular, Kepler's Third Law says:

$$T = 2\pi \sqrt{\frac{a^3}{GM}}.$$

$T$ is the period in seconds, $a$ is the semi-major axis of our orbit as before, and $GM$ the gravitational constant multiplied with the mass of the primary. As with circular orbits before, as a game developer you have the option to choose these however you want to make things look as you want to. The mean anomaly is thus:

$$\mu = \frac{2\pi}{T} = \frac{2\pi}{2\pi \sqrt{\frac{a^3}{GM}}} = \frac{1}{\sqrt{\frac{a^3}{GM}}}$$

We now have a plan: whenever we create a new orbit in our game, with a primary, periapsis, apoapsis, $t_0$, and longitude of periapsis, we first need to calculate a few derivative properties: the eccentricity, the semi-major and semi-minor axes, the centre of the ellipse, and the mean anomaly. These values don't change. From that point onward, we use Kepler's equation to calculate the position ever frame.

The full code can be found below.

static class Constants {
    public const double G = 1;
}

sealed class Body {
    public Vector2 Position { get; }
    public double Mass { get; }
}

sealed class Orbit {
    private readonly Body primary;
    private readonly double tPer;
    private readonly double eccentricity;
    private readonly double semiMajorAxis;
    private readonly double semiMinorAxis;
    private readonly Vector2 ellipseCenterOffset;
    private readonly double meanAnomaly;
    private readonly Matrix2 longitudeTransform;

    public Orbit(
            Body primary, double periapsis, double apoapsis, double tPer, double longitudePer) {
        this.primary = primary;
        this.tPer = tPer;

        eccentricity = (apoapsis - periapsis) / (apoapsis + periapsis);
        semiMajorAxis = 0.5 * (periapsis + apoapsis);
        semiMinorAxis = semiMajorAxis * Math.Sqrt(1 - eccentricity * eccentricity);
        ellipseCenterOffset = (periapsis - semiMajorAxis) * Vector2.UnitX;
        meanAnomaly = 1 / Math.Sqrt(
            semiMajorAxis * semiMajorAxis * semiMajorAxis / (Constants.G * primary.Mass));
        longitudeTransform = Matrix2.CreateRotation(longitudePer);
    }

    public Vector2 PositionAtTime(double currentTime)
    {
        // Calculate the true anomaly using Kepler's equation.
        var trueAnomaly = trueAnomalyAtTime(currentTime);

        // We calculate the distance vector from the primary to the satellite
        // under the assumption that longitude of periapsis is 0.
        var preRotatedOffset = ellipseCenterOffset + new Vector2(
            semiMajorAxis * Math.Cos(trueAnomaly),
            semiMinorAxis * Math.Sin(trueAnomaly));

        // We then rotate the point around based on the longitude of periapsis.
        var rotatedOffset = longitudeTransform.Transform(preRotatedOffset);

        // Finally, we translate this offset to be in the space of the primary.
        return primary.Position + rotatedOffset;
    }

    private double trueAnomalyAtTime(double currentTime)
    {
        const numIterations = 30; // Change depending on expected eccentricities.
        
        // Pre-calculate the current mean motion because it doesn't change.
        var M = (currentTime - tPer) * meanAnomaly;
        // Make an initial guess based on the eccentricity of the orbit.
        var E = eccentricity > 0.8 ? Math.PI : M;

        for (int i = 0; i < numIterations; i++)
        {
            var numerator = eccentricity * Math.Sin(E) + M - E;
            var denominator = eccentricity * Math.Cos(E) - 1;
            E = E - numerator / denominator;
        }

        return E;
    }
}

That is a lot of code, but it is all derived directly from the equations we've seen over the past few posts. There is one new trick I have applied to deal with the longitude of periapsis though. Calculating offsets is hard when your ellipse is not axis-aligned. That is why for all the calculations, I just pretend our primary is the origin, and the periapsis lies along the positive x-axis. When we calculated the difference vector from the primary to the satellite in this normalized space, we transform it by first rotating around the origin, and then calculating the final position by adding the rotated difference vector to the primary's position.

The third dimension

We spent five posts getting to the point of being able to describe an elliptical orbit in code. Surely, doing this in three dimensions will be much harder! Nothing less would be the case. All the equations still hold up in three dimensions. As a matter of fact, we have assumed that the physical rules of a 3D world hold up, and that we are merely working in a two-dimensional projection of the 3D world. This is also exactly why the step from 2D to 3D is relatively straightforward: we just have to put our code to work in a specific plane in that 3D world.

In orbital mechanics, we don't only have a reference for the longitude of periapsis, we also have a reference plane. In games we could easily pick the xy-plane, in the real world it is often the plane that is set out by the primary's equator. Our orbit will either coincide with the plane, or it will pass the plane through two points. The angle the orbit makes with the reference plane is called the inclination. The points in which the satellite passes through the reference plane are called the ascending node (when the orbit goes from below the plane to above it) and descending node (when the orbit goes in the other direction).

Earlier we used the longitude of periapsis to determine the orientation of the orbit, but in practice, we don't actually use that parameter. Instead, we use something called the longitude of the ascending node $\Omega$. Instead of measuring the angle between the reference direction and the periapsis, we measure the angle between the reference direction and the ascending node. To then fix where the periapsis is, we express the position of the periapsis as the argument of periapsis $\omega$ (yes they're both omegas, I didn't choose the symbols). The argument of periapsis is the angle between the ascending node and the periapsis measured in the orbital plane. The reason it is chosen this way is that with third dimensions, the periapsis no longer necessarily lies in the reference plane, meaning that calculating the angle between a reference direction and the periapsis becomes an undefined problem.

To implement the longitude of periapsis in our code, we used a transformation that kept the math simple by moving the primary to the origin, and the periapsis on the positive x-axis. We can do the same thing for inclination. Remember that transformations are always applied "backwards" or right to left, so the steps in the code become:

• Rotate rotatedOffset around the z-axis (so it rotates in the reference plane xy) by the argument of periapsis. Our orbit now represents how the orbit looks with the orbital plane as reference plane, and the ascending node at the positive x-axis.
• Rotate rotatedOffset around the x-axis by the inclination. We now have our actual orbit, but the ascending node is not yet in the right position.
• Rotate rotatedOffset around the z-axis, since the xy-plane now the actual reference plane, by the longitude of the ascending node.

Since these three rotations never change, we can precalculate the resulting matrix, and just translate our result once. That makes our final code:

static class Constants {
    public const double G = 1;
}

sealed class Body {
    public Vector2 Position { get; }
    public double Mass { get; }
}

sealed class Orbit {
    private readonly Body primary;
    private readonly double tPer;
    private readonly double eccentricity;
    private readonly double semiMajorAxis;
    private readonly double semiMinorAxis;
    private readonly Vector2 ellipseCenterOffset;
    private readonly double meanAnomaly;
    private readonly Matrix2 orbitTransform;

    public Orbit(
            Body primary, double periapsis, double apoapsis,
            double tPer, double inclination, double longitudeAscNode, double argPeriapsis) {
        this.primary = primary;
        this.tPer = tPer;

        eccentricity = (apoapsis - periapsis) / (apoapsis + periapsis);
        semiMajorAxis = 0.5 * (periapsis + apoapsis);
        semiMinorAxis = semiMajorAxis * Math.Sqrt(1 - eccentricity * eccentricity);
        ellipseCenterOffset = (periapsis - semiMajorAxis) * Vector2.UnitX;
        meanAnomaly = 1 / Math.Sqrt(
            semiMajorAxis * semiMajorAxis * semiMajorAxis / (Constants.G * primary.Mass));
        orbitTransform = createOrbitalTransformMatrix(
            inclination, longitudeAscNode, argPeriapsis);
    }

    private Matrix3 createOrbitalTransformMatrix(
            double inclination, double longitudeAscNode, double argPeriapsis) {
        // Rotate the periapsis in position assuming the ascending node is the
        // positive x-axis.
        var periapsisTransform = Matrix3.CreateAxisRotation(Vector3.UnitZ, argPeriapsis);
        // Rotate the orbit around the x-axis to give it its inclination.
        // We use the negative rotation here to make sure the x-axis is the
        // ascending node.
        var inclinationTransform = Matrix3.CreateAxisRotation(Vector3.UnitX, -inclination)
        // Finally, rotate the orbit so that the ascending node is in the right
        // position as well.
        var ascNodeTransform = Matrix3.CreateAxisRotation(Vector3.UnitZ, longitudeAscNode);

        // Transformations are applied right to left, so make sure we multiply
        // them in that order.
        return ascNodeTransform * inclinationTransform * periapsisTransform;
    }

    public Vector2 PositionAtTime(double currentTime)
    {
        // Calculate the true anomaly using Kepler's equation.
        var trueAnomaly = trueAnomalyAtTime(currentTime);

        // We calculate the distance vector from the primary to the satellite
        // under the assumption that longitude of periapsis is 0.
        // Note that the z-coordinate is 0, since the orbit is in the xy-plane.
        var preRotatedOffset = ellipseCenterOffset + new Vector3(
            semiMajorAxis * Math.Cos(trueAnomaly),
            semiMinorAxis * Math.Sin(trueAnomaly),
            0);

        // We then rotate the point in 3D space to apply inclination and the
        // correct orientation of the periapsis and ascending node.
        var rotatedOffset = orbitTransform.Transform(preRotatedOffset);

        // Finally, we translate this offset to be in the space of the primary.
        return primary.Position + rotatedOffset;
    }

    private double trueAnomalyAtTime(double currentTime)
    {
        const numIterations = 30; // Change depending on expected eccentricities.
        
        // Pre-calculate the current mean motion because it doesn't change.
        var M = (currentTime - tPer) * meanAnomaly;
        // Make an initial guess based on the eccentricity of the orbit.
        var E = eccentricity > 0.8 ? Math.PI : M;

        for (int i = 0; i < numIterations; i++)
        {
            var numerator = eccentricity * Math.Sin(E) + M - E;
            var denominator = eccentricity * Math.Cos(E) - 1;
            E = E - numerator / denominator;
        }

        return E;
    }
}

For bonus points, since all the transformations are rotations, you could switch to using a quaternion instead to speed up that step, but that part is left as an exercise to the reader.

Retrograde orbits

For the last few posts, we've been silently assuming that the orbits move counter-clockwise. If our primary also rotates around its axis counter-clockwise, we call these prograde orbits (i.e. the direction of the rotation of the primary matches the direction of the orbit). Prograde orbits are much more common than orbits in the opposite direction: retrograde orbits (i.e. orbits that move in the opposite direction as that of rotation of the primary). However, now that we have inclinations, retrograde orbits are a breeze to implement. To make an orbit traverse backwards, we just rotate the entire orbit by 180 degrees around some point.

Conclusion

It took us several blog posts to get to this point, but we are now able to implement orbits using a somewhat analytical approach. We started out by seeing how integration methods can cause our orbital bodies to drift, and eventually just fly off the screen due to accumulated error. While recalculating the position of a satellite every frame is more work, starting from scratch each frame means we don't carry over our previous errors. The satellite may still not be in exactly the right position, but at least the error will not increase in magnitude as our simulation runs longer.

This solution is great, and maybe even necessary, for games that rely on stable orbits, but the solution doesn't scale. Moving from a two-body orbital system to a three- or even n-body orbital system is nearly impossible, and it is likely you will need to fall back on the physical simulation by frame method in those cases.

In case you want to read any of the past posts on this topic, below is a list of all posts in this series.

• Errors in your game physics math
• Implementing circular orbits analytically
• The math behind elliptical orbits
• Solving Kepler's equation for elliptical orbits in games

Introduction

Last time, we looked at how we can express elliptical orbits analytically. The problem is that to get the velocity on any point of the elliptical orbit, we need to solve an equation - Kepler's equation - which has no closed form solution.

While Kepler's equation doesn't have a nice direct solution, it does have a different nice property: numerical attacks work pretty well for it. That means we can use some of our knowledge about dealing with hard analytical problems on this single equation.

Fixed point iteration

Let's look at Kepler's Equation again:

$$E - e \sin{E} = (t - t_\text{per}) \cdot n.$$

We can rearrange this slightly to turn it into a more common form:

$$E = e \sin{E} + (t - t_\text{per}) \cdot n.$$

Remember that $E$ is the value we're trying to solve for. If only we knew the value of $e \sin{E}$ we could solve this equation!

The first thing we can try is falling back on the most rudimentary of solving methods: guessing. If we have a guess for $E$, we can try filling it in on the right-hand side of the equation. This gives us a new value for $E$ on the left which is a better guess than our previous one. For example, let's start by guessing $0$. The next guess will be $E_1$ and is given by:

$$E_1 = (t - t_\text{per}) \cdot n.$$

Choosing $0$ as first guess causes the first term to be eliminated from the equation, leaving a pretty straightforward thing to calculate. If your eccentricity $e$ is close to zero - that is, if your orbit is near circular - the first part of the equation will not dominate the result either way. That makes sense, because with just some slight changes in notation, the equation above is just the equation for angle with the periapsis over time in a circular orbit:

$$\theta(t) = (t - t_\text{per}) \cdot \omega.$$

Since we're trying to solve our equation for actual elliptical orbits, we're not done yet. We can take our initial guess and fill it into Kepler's equation to get a better guess. In general:

$$E_{n+1} = e \sin{E_n} + (t - t_\text{per}) \cdot n.$$

Given enough iterations, this will converge to the actual solution for $E$. The number of iterations you need depend on your eccentricity $e$. For high eccentricities, you will need many iterations to find a close enough solution. This is the original solution Kepler used in the 17th century.

The code for this is relatively straight-forward:

double SolveKeplerThroughIteration(double e, double t, double tPer, double n)
{
    const numIterations = 30; // Change depending on expected eccentricities.

    // Pre-calculate the current mean motion because it doesn't change.
    var M = (t - tPer) * n;
    var E = 0;

    for (int i = 0; i < numIterations; i++)
    {
        E = e * Math.Sin(E) + M;
    }

    return E;
}

Instead of using a fixed number of iterations, you could also consider iterating until you find the difference between $E_n$ and $E_{n+1}$ to be small enough to live with. However, note that this potentially introduces a variable cost in your game update loop, so bounding the number of iterations is always a good idea.

Newton's method

The fixed point iteration method is easy to implement and generally returns accurate results relatively quickly. It is a pretty dumb way to iterate though. This is something that is solved in Newton's method. It still starts with a guess that we will use to get closer to the final answer, but the choice of the next guess is done differently.

We could rearrange Kepler's equation once again.

$$e \sin{E} + (t - t_\text{per}) \cdot n - E = 0.$$

The left part could be considered a function $f(E)$. The values $E$ for which a function $f(E)$ is zero are called the roots of the function. In this case, finding the root of $f(E)$ gives us a solution for Kepler's equation.

The reason we're taking this roundabout approach to solving Kepler's equation, is because finding roots for functions is a problem mathematicians have been trying to solve for a long time, and there are ways to do that in a smarter way than trying out arbitrary values. One of these methods, and probably the most famous of these approaches, is Newton's method. This method also works with an iterative approach, but the different iterations $E_n$ are defined in a different way.

Assuming an initial guess $E_0$, the following guesses are given by

$$E_{n+1} = E_n - \frac{f(E_n)}{f'(E_n)}.$$

Newton's method uses the rate of change, given by the derivative, to make more educated guesses as to where the function is going. For our version of Kepler's equation, we get the following expression for $E_{n+1}$:

$$E_{n+1} = E_n - \frac{e \sin{E} + (t - t_\text{per}) \cdot n - E}{e \cos{E} - 1}.$$

For most eccentricities $e < 0.8$, $E_0 = t - t_\text{per}$ is a good starting point. If your eccentricities go beyond $0.8$, you can use $E_0 = \pi$.

Translating this into code doesn't look too different from the code above.

double SolveKeplerThroughNewtonIteration(double e, double t, double tPer, double n)
{
    const numIterations = 30; // Change depending on expected eccentricities.
    
    // Pre-calculate the current mean motion because it doesn't change.
    var M = (t - tPer) * n;
    // Make an initial guess based on the eccentricity of the orbit.
    var E = e > 0.8 ? Math.PI : M;

    for (int i = 0; i < numIterations; i++)
    {
        var numerator = e * Math.Sin(E) + M - E;
        var denominator = e * Math.Cos(E) - 1;
        E = E - numerator / denominator;
    }

    return E;
}

Another advantage of this approach is that you are trying to get a function as close to $0$ as possible, which makes it easy to change the exit condition of your loop based on the current output. Just fill in your current $E_n$ in $f$ and check if it's smaller than your desired difference.

Back to the physical world

Now that we have ways to solve for $E$, we can turn back to our physical world and attempt to turn this into a position we can use to update and/or draw our game world. In the previous post, we established that the position on an ellipse is given by

$$\begin{pmatrix}x \ y\end{pmatrix} = \begin{pmatrix}a \cos E \ b \sin E\end{pmatrix}.$$

This position is relative to the centre of the ellipse, which is not the same as the position of our primary, which is located in one of the foci of our ellipse.

In the next post I'll show how the math can be made to work out, and we'll also introduce a third dimension to talk about inclined orbits.

Closing words

In this post we looked at two ways to solve Kepler's equation, which is needed to keep track of orbits in an analytical way. The reason we started with the analytical approach was to avoid numerical errors, so falling back on a numeric approach for elliptical orbits seems to to defeat the point. However, for orbits we tried avoiding the numerical approaches for a very particular reason: they make stable orbits deviate and either diverge or converge over time. This is because the outcome of our numerical approach is used in the following frame, so our error adds up. For elliptical orbits on the other hand, we use numerical approaches to turn our source truth variables into something we can display, but the errors that slip in don't propagate to following frames.

There may still be floating point imprecision errors in keeping track of the current time, but the only problem that will introduce is that our satellite may not quite move at the right velocities around the orbit any longer. It will still be in one of the positions on the correct orbit though, and this orbit will never deteriorate. For many games, keeping the orbits constant is important, and this solution solves that problem.

Introduction

Coincidences rarely happen in physics, and perfectly circular orbits statistically don't exist.

The centripetal force will either be larger or smaller than the gravitational force at any given point in the orbit. This is what leads to elliptical orbits. When the centripetal force is larger, the satellite will start moving away from the primary. As the satellite does so, the velocity vector will no longer be orthogonal to the gravitational acceleration. Consequently, the satellite starts losing speed and the centripetal force gets less. Since the satellite is moving further away, the gravitational force also becomes less. If the satellite has too much energy, the gravitational force may never be enough to outweigh the centripetal force, which causes a hyperbolic trajectory. However, if the satellite lose enough energy for the gravitational force to become the strongest, the satellite will start falling back to the primary. This is when the opposite process happens, as gravity causes the satellite's velocity to increase, and the process repeats. We have our elliptical orbit.

The point where the satellite is closest to the primary is called the periapsis. This is the point where the satellite has the most energy. The point in the orbit where the satellite is furthest from the primary is called the apoapsis, and this is where the energy of the satellite is the lowest. You may have heard terms such as apohelion and perigee before. Most known bodies have there own suffixes for the highest and lowest points of orbits around them. Apogee and perigee are the highest and lowest points in an orbit around Earth, apohelion and perihelion the highest and lowest points in an orbit around the Sun.

Ellipses

It is no surprise that the equations for elliptical orbits are more complex than the orbital ones. As you may have guessed, an elliptical orbit is an ellipse where the primary is one of the foci. To understand elliptical orbits, we need to understand ellipses first.

Just as the circular orbits are described by a circle around its center, elliptical orbits are described by an ellipse around two foci. In a circle each point has the same distance to the center; in an ellipse each point yields the same result if you add up the distances to the two foci (sg. focus). The line through the two foci is called the semi-major axis, and the line through the center of the ellipse orthogonal to the semi-major axis is the semi-minor axis. The distance from the center to the ellipse along the semi-major and semi-minor axis are denoted by $a$ and $b$ respectively. See the following image for a representation of these concepts:

The distance from the center to one of the foci $c$ is called the linear eccentricity. If you divide this by the distance $a$, you get the eccentricity of the ellipse, which describes how stretched the ellipse is. Eccentricity is a commonly used term to describe orbits. As the orbit approaches a circular orbit more and more, the focus will come closer to the center of the ellipse, and the eccentricity will tend towards 0.

For orbits, we are often not given the values $a$ and $b$, but the apoapsis and periapsis heights. However, as you can see, if you add up apoapsis and periapsis heights, you should get exactly $2a$. We also know the centre of the ellipse (it's exactly between apoapsis and periapsis), and thus we can calculate the distance between the centre and the primary to obtain $c$. We now have $a$ and $c$ which together allow us to calculate the eccentricity $e$, and now we have all we need to start expressing this orbit using the power of math!

Position

Remember that for circular orbits, we were able to determine the position over the parameter $\theta$ as:

$$\begin{pmatrix}x \ y\end{pmatrix} = r \begin{pmatrix}\cos \theta \ \sin \theta\end{pmatrix}.$$

For elliptical orbits, we can do something very similar:

$$\begin{pmatrix}x \ y\end{pmatrix} = \begin{pmatrix}a \cos E \ b \sin E\end{pmatrix}.$$

Instead of using a single radius $r$, we use $a$ and $b$ instead to represent that the ellipse has a different size horizontally as vertically. I also replaced the parameter $\theta$ with $E$. As opposed to what you may think, $E$ is not actually the angle between the semi-major axis and the line through the center of the ellipse and the point on the ellipse.

Since circles are easier to reason about, we use a circle to help us with ellipses. We create a circle which shares a centre with the ellipse, and has radius $a$ so it touches the ellipse in its two furthest points.

The angle $E$ we are talking about is the angle between the center of the ellipse and the vertical projection of the point on the ellipse to this circle (blue in the image above), and is called the eccentric anomaly. The actual angle between the point on the ellipse and the semi-major axis (red in the image above) is called the true anomaly and often denoted by $\nu$.

Velocity

We can now draw an orbit, but we still haven't figured out the velocity of the satellite at any point in the orbit. Unlike circular orbits, the orbital speed of the satellite will change over time. This is where it gets a bit tricky. In circular orbits, the satellite moves at a constant rate, so we can increase $\theta$ at a constant rate, but for elliptical orbits we need to do more work to express $E$ as a function of time passed.

We can find the velocity $v$ of an object at any point in the orbit given $E$, but this isn't enough to give us the rate of change of $E$. We could use this to approximate the rate of change of $E$ by dividing among the radius of the auxilary circle to get the angular velocity. This may be a close enough approximation for a lot of applications.

For the velocity we have the following equation:

$$\tan{\frac{v}{2}} = \sqrt{\frac{1 + e}{1 - e}}\tan{\frac{E}{2}}.$$

For an approximate velocity of $E$, we'd find:

$$\tan{(\pi a \dot{E})} \approx \sqrt{\frac{1 + e}{1 - e}}\tan{\frac{E}{2}}.$$

Or in a direct expression:

$$\dot{E} \approx \frac{\arctan{\left(\sqrt{\frac{1 + e}{1 - e}}\tan{\frac{E}{2}}\right)}}{2 \pi a}.$$

Here all variables are as before, and $e$ is the eccentricity of the ellipse.

Of course as this is an approximation it is prone to artefacts. For relatively small $e$ and most use cases in, say, games, this may be acceptable if the update steps are small. If we want to make sure that the orbit takes the correct amount of time though, we have to go a step further and introduce the concept of mean motion $n$. The mean motion is simply the average change of $E$ over time. This is simply $2 \pi$ divided by the period of the orbit.

Now we have all the concepts to build Kepler's equation:

$$E - e \sin{E} = (t - t_\text{per}) \cdot n.$$

In this equation, $t_\text{per}$ is the time at which the satellite passes through the periapsis of the orbit.

There we have it. For any given point in time $t$ we can find the eccentric anomaly $E$, convert that into the position, and we're done. Sadly, solving Kepler's equation isn't a thing we can easily do, as there isn't a so-called closed-form solution, which would mean we could express $E$ as some expression as we did with the approximation earlier. There are several ways around that, which we will explore in the next post, where we will also be looking at how to go about writing the code for elliptical orbits.

In my last post I discussed different integration methods using a body orbiting its parent as an example. In this post, I want to shift to focus to how orbits actually work, and give you a look into how you might implement orbits analytically.

In this series of posts, we will exclusively look at two-body systems. That means we have a larger body (the primary) with a smaller body (the satellite) orbiting around it. This is already a gross simplification of reality: a satellite orbits a primary because of the gravity the primary exerts on the satellite. The satellite is generally much smaller, but it does also exert gravity on the primary. When two bodies are in orbit, they are in fact both rotating around a central point, their shared center of mass.

The bigger the ratio between the masses of the bodies, the smaller the effect on the primary. In the case of the Earth-Moon system for example, Earth is so much more heavy than the Moon, that the center of mass of the Earth-Moon system is very close to the center of mass of Earth itself. We can thus approximate the orbit of the Moon around Earth by assuming the Moon does not contribute to the center of mass of the system.

For these posts, we won't be going as far as detangling Einstein's laws of relativity, and so we will be looking at Newtonian graphics. We will always express the position of the satellite assuming the primary is in the origin of our coordinate system.

Circular orbit

In the simplest case, the satellite moves in a perfect circle around the primary at a distance $r$.

If we wanted to represent the position of the satellite over time, we could make use of the sine and cosine functions.

$$\begin{pmatrix}x \\ y\end{pmatrix} = r \begin{pmatrix}\cos \theta \\ \sin \theta\end{pmatrix}.$$

Here $\theta$ is the angle of the satellite with the x axis of our coordinate system at any point in time. What remains is determining how this angle changes over time.

In the case of a perfectly circular orbit, the force pulling the satellite towards the primary (gravity $F_G$) is equal to the force trying to push the satellite away from it (centripetal force $F_c$). By putting the functions for both these forces on either side of the equals sign, we can derive the orbital velocity at a certain distance $r$:

$$F_G = \frac{G \cdot M_{s} \cdot M_{p}}{r^2} = \frac{M_s \cdot v^2}{r} = F_c.$$

Here $G$ is the gravitational constant. The nice thing about writing games is that we can choose the gravitational constant to be anything we want, even 1. $M_s$ is the mass of the satellite, and $M_p$ the mass of the primary, which we'll start denoting with $M$ going forward, as $M_s$ cancels out on both sides of the equation. Again, when writing games, you can just choose these values to be whatever you want. Since functions will (almost) always have $GM$ as a single clause, it's not a bad idea to choose $G$ to be 1 to simplify some of your logic. Often, the term $GM$ is simplified and denoted as $\mu$.

Let's cross out the parts of the equations we can:

$$\frac{G \cdot M}{r} = v^2.$$

This leads us to the following function for the orbital velocity of a circular orbit.

$$v = \sqrt{ \frac{GM}{r} }.$$

We can transform the actual velocity into an angular velocity $\omega$ as well, which gives us the following function:

$$\omega = \sqrt{ \frac{GM}{r^3} }.$$

Finally, transforming this into code (assuming $G=1$) is straightforward:

void Init() {
    theta = 0;
    radius = (primary.Position - position).Length;
    angularVelocity = Math.Sqrt(primary.Mass / (radius * radius * radius))
}

void Update(float elapsedSeconds) {
    theta += elapsedSeconds * angularVelocity;
    position = radius * new Vector2(Math.Cos(theta), Math.Sin(theta));
}

Position as a function of time

The function and code above calculates our orbital position incrementally. We keep track of our current angle, and each frame increment that. Another way to represent orbits though is as a function over time. For circular orbits, we know that our angular velocity over time is a constant function:

$$\omega(t) = \sqrt{ \frac{GM}{r^3} }.$$

Our angle over time is our angular velocity multiplied by the total time that has passed:

$$\theta(t) = t \cdot \omega(t).$$

Since we know how to transform $\theta$ into an actual position, we now have a function that gives the position at any given time:

$$\begin{pmatrix}x \\ y\end{pmatrix}(t) = r \begin{pmatrix}\cos ( \theta(t) ) \\ \sin ( \theta(t) )\end{pmatrix}.$$

Translating this into code is left as an exercise to the reader.

Conclusion

As you can see, the math for circular orbits works out pretty nicely. This is not the case when we start pulling in a third dimension, or if orbits stop to be perfectly circular. We'll be looking at those in future posts.

It is not uncommon for games to contain some form of game physics. The most common - and probably most intuitive - of those, is gravity. In a simplified situation where we ignore air resistance, gravity applies a constant acceleration to an object (no matter its mass), which increases its downward velocity.

Gravity can also occur over longer distances: between orbiting bodies. I want to take orbits as an example today, since they lend themselves to some nice simplifications. When we talk about orbits, we often talk about a small body (the satellite) orbiting a static large body (the primary).

The principle of an orbit is the same as normal gravity, but we need to be a bit more careful about the direction of our vectors. The primary pulls on the satellite, causing an acceleration that's orthogonal to the satellite's current velocity. The satellite's velocity is therefore altered so its trajectory curves towards the primary, but never enough to fall down.

The problem

In games, we generally don't simulate constant acceleration. Instead, we update the state of our universe in fixed time steps. The code for updating the satellite could look something like this:

void Update(float elapsedSeconds) {
    velocity += acceleration * elapsedSeconds;
    position += velocity * elapsedSeconds;
}

The exact orbiting speed depends on the distance, the bodies' masses and the gravitational constant, which we can ignore. Instead we just choose an orbiting speed. In fact, we can just always assume that the current velocity vector is the orthogonal of the vector pointing from the satellite to the primary. In 2D, that makes our code:

void Update(float elapsedSeconds) {
    toPrimary = (primary.Position - position).Normalized();
    // We use the clockwise orthogonal as velocity direction,
    // causing a counter-clockwise orbit.
    velocity = speed * new Vector2(toPrimary.Y, -toPrimary.X);
    position += velocity * elapsedSeconds;
}

The exact velocity calculation does not matter for our topic today, in so far as that it is the derivative of the position as a function in time. This means that we can express the calculation above as mathematical equation too:

$$p(t_0 + \epsilon) = p(t_0) + \epsilon \cdot \dot p (t_0).$$

The position at some time $t_0 + \epsilon$ for the elapsed time $\epsilon > 0$ is the position at $t_0$ plus the velocity at $t_0$ multiplied by the elapsed time.

What we have actually done here is applying the Euler method to use a differential equation. In each step, we approximate the movement of the satellite that happened in the period between last frame and the current. We do this by using a constant velocity during this time period. However, in reality, the velocity constantly changes to arc the object towards the primary. We end up changing the position of the satellite slightly further away from the primary than the expected order.

In most cases, this may not matter than much. However, if your game expects orbits for example to be stable, you'll find that if you leave the game running long enough, satellites will slowly move away further and further from their primary. You can see this in the image below:

In the animation above, the speeds and time steps have been exaggerated to highlight the error. In normal circumstances the error will be much less egregious, but it is there nonetheless. Let's look into a few ways we can fix this.

Smaller steps

When we talk about the speed of a game, we usually quickly arrive at talking about FPS - frames per second. FPS is inherently a graphics concept, and talks about how often we can render the game to the screen per second. Often FPS is linked to the numbers of updates per second - UPS. It is not uncommon for games to render more frames per second than the refresh rate of the monitor can handle, especially in games that are fast-paced, to reduce the input lag for its players.

If we have a game where our rendering takes significantly slower than our updating, it doesn't make much sense to link those two together. In general, the major bottleneck of the rendering is the GPU, while the updating is mostly limited by the CPU resource. By separating the update loop from the rendering loop, we can try to squeeze as many update cycles as possible out of the CPU. That way we reduce the time steps, and the error over time.

Sometimes it's not possible or practical to separate the actual loops, but that doesn't prevent us from doing more update cycles than rendering cycles. When we have a game running at 60 FPS, we can always decide to split the time per frame in two, and do two update cycles with half the time step every frame. This means we are effectively updating at 120 UPS. This has the drawback that if the update cycle takes too long, we can't keep up the 60 FPS, and we'll slow down the rendering as well.

Reducing the time deltas will reduce the error build-up over time. This makes sense, since mathematically taking the limit of the time delta approaching 0 gives us the actual result we want. However, getting a small delta is not always possible, especially if we keep in mind that less powerful machines may have less UPS than a massive gaming rig. Let's look at some mathematical tricks that we may use instead.

Midpoint method

The source of the error in the Euler method is that we look at the derivative of the position (which is the velocity) at $t_0$. The velocity changes over time, and this is not accounted for. Instead of looking at the derivative at $t_0$, we can look at the derivative at $t_0 + \epsilon / 2$. The idea is that instead of assuming that our velocity over time can be approximated by a constant velocity, we assume that our acceleration (the change in velocity) can be approximated by a constant acceleration instead. By looking at the velocity at $t_0 + \epsilon / 2$, the intuition is that we take the average velocity over our time delta, which gives a closer approximation. In a mathematical expression, this is expressed as:

$$p(t_0 + \epsilon) = p(t_0) + \epsilon \cdot \dot p (t_0 + \frac{\epsilon}{2}).$$

The problem is that we don't know the value of $\dot p (t_0 + \epsilon/2)$. However, we can always use our original trick of using the Euler method to find $p (t_0 + \epsilon/2)$ and calculate the derivative in that point.

This method is named the midpoint method after the fact that we are looking at the midpoint of our time segment to get the derivative to use. Let's take a quick look at how this could look in code:

void Update(float elapsedSeconds) {
    var velocityAtCurrent = velocityAt(position);
    var midpoint = position + velocityAtCurrent * elapsedSeconds * .5f;
    var velocityAtMidpoint = velocityAt(midpoint);
    position += velocityAtMidpoint * elapsedSeconds;
}

Vector2 velocityAt(Vector2 pos) {
    toPrimary = (primary.Position - pos).Normalized();
    return speed * new Vector2(toPrimary.Y, -toPrimary.X);
}

We see that we need to do roughly double the calculations, but we get more precision in return.

Heun's method

We have looked at the velocity at $t_0$ and $t_0 + \epsilon / 2$, but what about the velocity at $t_0 + \epsilon$? If we use the velocity at $t_0$, we get a result (this is the Euler method), and if we use $t_0 + \epsilon$ we get a different result. It is very likely that our actual result is somewhere between these two. Heun's method is based on this. It uses the Euler method to calculate a first approximation. Then we calculate the velocity at this new point, and use it to make another approximation. We average our two approximation and use that as a final solution. This is a bit easier to express in code than in math, so let's start there:

void Update(float elapsedSeconds) {
    var velocityAtCurrent = velocityAt(position);
    var eulerPosition = position + velocityAtCurrent * elapsedSeconds;
    var velocityAtEulerPos = velocityAt(eulerPosition);
    var heunPosition = position + velocityAtEulerPos * elapsedSeconds;

    position = .5f * (eulerPosition + heunPosition);
}

Vector2 velocityAt(Vector2 pos) {
    toPrimary = (primary.Position - pos).Normalized();
    return speed * new Vector2(toPrimary.Y, -toPrimary.X);
}

Below is an attempt to describe this mathematically:

$$
\begin{aligned}
p_{\text{Euler}}(t_0 + \epsilon) & = p(t_0) + \epsilon \cdot \dot p (t_0) , \
p_{\text{Heun}}(t_0 + \epsilon) & = p(t_0) + \epsilon \cdot \dot p_{\text{Euler}} (t_0 + \epsilon) , \
p(t_0 + \epsilon) & = \frac{p_{\text{Euler}}(t_0 + \epsilon) + p_{\text{Heun}}(t_0 + \epsilon)}{2} .
\end{aligned}
$$

Analytical

We can also take a different approach entirely. Instead of approximating our physics, we could use the exact analytical solution as well. For a circular orbit, we just need to be able to describe a point moving along a circle, which is fairly straightforward. For eccentric orbits things get a bit more complicated, and we'll discuss this in a follow-up post.

In general, analytical solutions are impractical. While we may be able to calculate simple systems (two body orbital systems, a single falling object), it becomes impractical for larger problems.

Closing words

Integration methods have the problem that they accumulate errors. The small error we introduce in one frame will live on in all future frames of our simulation. In orbital mechanics, this often leads to drift, and causes stable orbits to eventually become unstable. In many practical cases, the physical simulations don't take long enough, or the effects aren't noticeable enough that we need to worry about it, but in some cases we need to do a bit of extra work to make things look right.

Orbits are a feeble thing, as they are easy to make unstable with an accumulated error. That's why we will spend the next few blog posts picking apart the math behind orbital mechanics, and try to build an implementation of orbits that can keep running for an indefinite amount of time.

Every game starts with an idea. Often, this idea represents the core mechanic in your game. Games often have a core game loop that represents the foundation of all the rest of the gameplay. Core game loops can be simple (e.g. match-3 in Candy Crush) or complex (e.g. drop > collect loot > kill others > survive in battle royale games such as PUBG or Fortnite). There is but one fundamental truth that is important though: if your core game loop isn't fun, your game won't be fun.

An example: Roche Fusion

Let's rewind a bit. Roche Fusion is an almost-casual space shoot'em mixed with roguelite elements such as full procedural generation and a unique upgrade path in each game. Below you can see screenshots both of the released version, and also a screenshot of one of the first prototypes.

The screenshots show that the final version is much more polished and visually appealing, but there is even more that the screenshots don't show: a full soundtrack, dozens of enemy types and behaviours, many different upgrades, eight playable ships with completely different playstyles, and more. Here comes the kicker though: I could fire up that early prototype, and still have fun. The graphics were simple, the enemies programmed to follow an exact predefined pattern of behaviours, and it was enough to prove to us that people would have fun playing this game.

Of course all the layers of juice, content, and other fanciness made Roche Fusion (or beardgame, as we called it back them) from something that was merely fun into a production-ready game. Yet, I cannot imagine that all the layers that we added would have made a successful game if our earliest prototype hadn't been so much fun to play already.

Game jams

It may be hard to believe this as a truth, but I think there is another phenomenon that makes this truth even more convincing: game jams. Game jams are contests where developers are giving a limited time (often 48 or 72 hours) to make a game from scratch. It comes as no surprise that in that time you don't have the time to add a whole lot of content or to build a graphics engine that will define games for the next decade. Game jams often have simple graphics, simple sounds (if you are lucky), and can usually not be considered as much more than a proof of concept. In other words, game jam games are often just the core game loop with a thin layer of fanciness to make the whole package presentable.

There is only one game jam game that I am really satisfied with. The game started out with a silly idea, and after a day of fun, it just didn't work when playing. I made the hard call to start over the second day, and ended up with something that was extremely simple but a lot of fun. Once the core game mechanic had been revised, everything just clicked in place.

The lesson

I think of all the lessons I have learned during my career as game developer, this truth has been one of the most important. It is also the most difficult to put in practice. Game design is a creative process after all, and inspiration comes and goes.

To make things even harder, you can't know for sure whether a game mechanic is fun or not without implementing it and trying it out. You could compare it to other creative processes, such as painting: in your mind a colour combination might work really well, but as soon as your paint it, it may not look as well as you intended. If you practice more and more, you'll build up an intuition for what works and what doesn't. There will still be times where you're wrong though, game design will never become more certain than a series of educated guesses.

Luckily there is a fairly easy fix for this: iteration. Build prototypes to see what works and what doesn't. Not only does this help you to find ideas that work, it's also good practice: it will help you build an intuition, but it will also make you more able to distinguish what separates a good idea from a bad one. Game design is as much about dropping ideas as it is about generating them. Participating in game jams is a great tool to force yourself to work on an idea that you can drop after just a couple of days.

My current project, simply called TD, started from just such a (self-imposed) game jam. We spent a weekend building a prototype for a tower defence in a hexagonal grid with some novel ideas. Afterwards we played the game, and despite there not being any graphics or more than a single type of tower, it was fun. We decided to keep the idea and we're now two years in. If the game had been dull, we'd have dropped it and tried something else.

So to summarise: games stand or fall based on their core mechanics. If the foundation of your game isn't fun, then no matter how much prettiness you add on top, you'll never turn the game into something great. Determining whether your core mechanics are fun can only be done by building them. One day you'll stumble upon a great idea you can actually invest time in making great, knowing that your game has got that Fun Factor.