making a simple shoot-em-up with FNA and MoonTools.ECS

20230925

if you find this tutorial valuable, i have a patreon and a ko-fi. your support is much appreciated.

NOTE: shortly after i wrote this, there was an update to MoonTools.ECS that breaks many parts of this tutorial. I am currently in the process of writing a new tutorial to address these changes. In the meantime, if you want to follow this tutorial, you’ll have to checkout MoonTools.ECS commit 4ef7cb4302262df0cfc2e8166bda1abd1a27f762, “Determinism Fixes,” the last change compatible with this tutorial.

this is a tutorial on how to make a simple scrolling shoot-em-up using FNA and MoonTools.ECS. it is aimed at a broad audience. some familiarity with programming, particularly C#, is helpful, but not required.

if you don’t know how to program at all, you might find this overwhelming at first, but i’ve written explanations with you in mind, so hopefully you can follow along still. i want this to be an extremely beginner friendly introduction for anyone who wants to learn how to make video games.

familiarity with computer graphics, game programming specifically, ECS, or custom engine techniques in general is NOT required.

if you’re new to programming, i highly recommend that you type out all the code rather than just copying and pasting it. this sounds dumb but it really does help you internalize it better.

this tutorial also contains a lot of detail. a lot of other tutorials will oversimiplify and promote bad programming practices for the sake of simplicity, but i’ve tried not to do that. i want to show you here techniques you can use to make real video games, not just toy projects that will mislead you when you try to make your own games. there’s no right way to do most things in programming, but there are certainly wrong ways, and i’ve tried to avoid them as much as possible.

and one more word before we get started: programming is hard. making video games is hard. everyone finds it hard. if you find anything confusing, don’t be afraid to ask for help, and don’t feel like you’re exceptionally stupid. we’re all stupid, here, together.

i. getting set up

we’re going to be using my FNAECSTemplate. if you know how development environments work, feel free to follow the instructions on that page. i use visual studio code and the template includes task files to let you automatically build with vscode, but it will also work with regular visual studio 2019 and other IDEs like jetbrains rider. all the important stuff is in the .csproj files.

take your time to poke around and read through the comments in the various example files that come with the template. it shouldn’t take too long, and you should walk away with a good idea of the basic terminology we’ll be using throughout this tutorial. if you want all the gory details about how i made this template, i wrote a whole separate article just about that.

i’ve called my project namespace ShmupTutorial throughout this tutorial. whenever you see that, or ProjectName, replace it with whatever you’ve called your project.

the last thing you’ll need is the assets i made. unzip this and put its contents in your Content folder.

ii. drawing to the screen

first, let’s figure out how to draw a sprite on the screen.

sprite sheets

i used cram to make a spritesheet of the sprites we’re going to use. it includes the sprites packed into a single png and a json file of metadata. if you want to use your own sprites, follow the instructions on the page for cram.

the first thing we need is a way to read the sprite sheet data. FNA has inherited from XNA a built-in content management system that reads files compressed to the XNB format, but even chief FNA maintaner ethan lee thinks it’s bad and you should not use it. it exists solely for backwards compatibility reasons and should be considered deprecated.

writing a content management system can be a little daunting and also quite boring. fortunately, i have written one for you. in the FNAECSTemplate lives a project called ContentImporter.

first, run

dotnet build .\ContentImporter\ContentImporter.csproj

from the command line in your project folder. now ContentImporter.exe should be built and ready to use at .\ContentImporter\bin\Debug\net7.0\ContentImporter.exe.

now you can run

.\ContentImporter\bin\Debug\net7.0\ContentImporter.exe .\ShmupTutorial\ShmupTutorial.csproj .\ShmupTutorial\Content\ .\ShmupTutorial\Content.cs

to import your content into a file called Content.cs. you’ll have to re-run that command every time you add new content to the game.

alternatively, if you’re using visual studio, you can open ContentImporter.csproj and build it with the GUI build buttons. it will get built in the same location and you can run it the same way.

if you take a look inside our new Content.cs, you may see something that is dissimilar to how you’re used to handling content in video games.

rather than storing content in some kind of data structure like a dictionary or adopting a complex serialization solution like Unity or Unreal, i’ve elected to build a system where all the content is stored in static readonly variables.

why do this? well typical solutions to content management are highly susceptible to runtime errors. if you’re referencing files by their names with strings, and you delete a file or rename it, you can cause a runtime error if you forget to update all the code that references that variable. here, all errors are either compile-time errors or they happen immediately upon running the game (in the case where you forget to re-run the ContentImporter).

you can also take better advantage of your IDE’s autocompletion functions with this method, because the language server knows about all the variable names. this solution also makes parallelizing content loading trivial.

the ContentImporter can handle sprite atlases, fonts, sound effects, and music. FNA also has support for video playback, but I haven’t added support for that yet because it’s a bit more complicated and I haven’t personally needed it yet.

internally, the ContentImporter iterates over every file in your designated Content folder and generates code to load it. have a look at the code if you want, it’s a bit messy but not too complicated.

the only thing other thing you have to remember to do is call AllContent.Initialize(Content); in your LoadContent method. the template includes a call to this method by default.

drawing components

let’s start thinking about some ECS stuff. what entites and components do we need for drawing?

our player is definitely going to be an entity. what properties does the player have? for the purposes of drawing, they have a position on the screen, a rotation, a scale, and a sprite.

find Components.cs in the components folder and replace its contents with the following:

using Microsoft.Xna.Framework;

namespace ShmupTutorial.Components;

public readonly record struct Sprite(Rectangle Rect, float Depth);
public readonly record struct Position(Vector2 Value);
public readonly record struct Rotation(float Value);
public readonly record struct Scale(Vector2 Value);

C# 10 introduced a new type of struct, the record struct. these are perfect for components in ECS. you can see a deep dive here but the upshot for us is: they turn component struct declarations into one-liners. because they’re one liners, it makes sense to put a bunch of component declarations in a single file.

we want our components to be readonly because even if they weren’t, they’re kind of not actually mutable. you have to call Set in order to update the component store, just modifying the struct won’t do that. we’ll get into that more later when we write our first system.

creating the player

in ProjectName.cs, replace the demo component creation logic with this:

var player = World.CreateEntity();
World.Set(player, new Sprite(Textures.Player, 0.0f));
World.Set(player, new Position(new Vector2(Window.ClientBounds.Width * 0.5f, Window.ClientBounds.Height * 0.5f)));

the player is an entity, and we Set two components on it: the Sprite and the Position.

at this point, you can also delete the ExampleSystem.cs and its references in ProjectName.cs, as well as ExampleRenderer.cs and its references.

actual drawing

create a new file in Renderers called SpriteRenderer.cs.

using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;
using MoonTools.ECS;
using ShmupTutorial.Components;
using System;

namespace ShmupTutorial.Renderers
{
    public class SpriteRenderer : Renderer
    {
        Filter SpriteFilter;
        SpriteBatch SpriteBatch;

        public SpriteRenderer(World world, SpriteBatch spriteBatch) : base(world)
        {
            SpriteBatch = spriteBatch;
            SpriteFilter = FilterBuilder
                .Include<Position>()
                .Include<Sprite>()
                .Build();
        }

        public void Draw()
        {
            SpriteBatch.Begin(
                SpriteSortMode.BackToFront,
                BlendState.AlphaBlend,
                SamplerState.PointClamp,
                DepthStencilState.None,
                RasterizerState.CullCounterClockwise
            );
            foreach (var entity in SpriteFilter.Entities)
            {
                var position = Get<Position>(entity).Value;
                var rotation = Has<Rotation>(entity) ? Get<Rotation>(entity).Value : 0.0f;
                var scale = Has<Scale>(entity) ? Get<Scale>(entity).Value : Vector2.One;
                var sprite = Get<Sprite>(entity);
                SpriteBatch.Draw(
                    Content.Textures.Sprites,
                    new Vector2((int)position.X, (int)position.Y),
                    sprite.Rect,
                    Color.White,
                    rotation,
                    new Vector2(MathF.Floor(sprite.Rect.Width * 0.5f), MathF.Floor(sprite.Rect.Height * 0.5f)),
                    scale,
                    SpriteEffects.None,
                    sprite.Depth
                );
            }
            SpriteBatch.End();
        }
    }
}

let’s go through this!

a Filter is an ECS construct which you can think of as a list of all the entities that fulfill certain criteria. we have Include, which means to include only entities who have these components, and we also have Exclude which means don’t include entities with this component. you may be used to operations like this in unity being very very slow, but because of the way an ECS stores components, this is a very fast operation and we can easily do it once per frame.

a SpriteBatch is how you draw to the screen with FNA. it takes all your sprites that you want to draw and packs them into a single vertex buffer so the GPU can draw them all with a single draw call. this is much more efficient than drawing each sprite one at a time. If you’re using the template, there’s code to create a SpriteBatch by default in LoadContent, which we dependency inject into our render via the constructor. dependency injection is a very common pattern with MoonTools.ECS.

always draw as many sprites as possible in a single sprite batch. if you need to use multiple sprite batches (for shader-related reasons), draw every single sprite that uses the same shader in a single batch instead of switching back and forth, and use the depth buffer if you need sprites using different shaders to occlude each other. this is not covered in this tutorial, but i will cover it at some point.

in our Draw method, we first have to Begin the sprite batch. we call this method with a bunch of options.

then, we have a foreach loop where we iterate over every sprite in our game using the filter. for each one, we get its transform and sprite. then, we call SpriteBatch.Draw with a bunch of parameters:

1. the sprite sheet texture we created earlier
2. the sprite’s position we just got, which we round to the nearest integer to avoid some visual glitches
3. the sprite rectangle we stored earlier
4. the sprite color (white for now, later we can add the ability to tint the sprite if we want)
5. the sprite’s rotation we also just got
6. the sprite origin. FNA by default has the origin in the top left corner, but we want it in the center of the sprite.
7. the sprite’s scale
8. the sprite effect
9. the layer depth

then, we call SpriteBatch.End once we’ve drawn all our sprites, which causes SpriteBatch to wrap up the batching process and actually draw everything to the screen.

finishing up

now, create the SpriteRenderer in ProjectName.cs and initialize it:

SpriteRenderer SpriteRenderer;

(Later, in LoadContent...)

/*
RENDERERS 
*/

SpriteRenderer = new SpriteRenderer(World, SpriteBatch);

protected override void Draw(GameTime gameTime)
{
	GraphicsDevice.Clear(Color.Black);
	SpriteRenderer.Draw();
	base.Draw(gameTime);
}

and run the game:

….huh.

that’s a little small, isn’t it? the problem is that our window is, if you left the template settings at default, 1024x768, and a little 13x15 sprite is just not very large compared to that.

this also subtly reveals an even bigger problem. if the user changes the game’s resolution, everything’s going to stay the same size! someone playing in full screen on a 4k monitor would see absolutely miniscule sprites if we made our game like this.

you could adjust the scale factor until it looks better, but that’s not going to be pixel-perfect and it’s hard to make that work for a wide variety of different screen sizes. what we need is a render target.

render targets

a render target is a texture that you can draw to instead of drawing to the screen. we can draw to a render target that’s the size of our desired rendering resolution, and then upscale it to the full window size.

first, let’s create some variables at the top of ProjectName.cs:

public static readonly int RenderWidth = 320;
public static readonly int RenderHeight = 240;
public static RenderTarget2D RenderTarget;

a modest 320x240, a good size for our game’s sprites. you can adjust this if you drew your own sprites earlier at a different resolution.

then, near the top of LoadContent:

RenderTarget = new RenderTarget2D(GraphicsDevice, RenderWidth, RenderHeight);

we have to adjust the player’s spawn position too:

World.Set(player, new Position(new Vector2(RenderWidth * 0.5f, RenderHeight * 0.5f)));

now replace your old Draw loop code with:

protected override void Draw(GameTime gameTime)
{
	GraphicsDevice.SetRenderTarget(RenderTarget);

	GraphicsDevice.Clear(Color.Black);
	SpriteRenderer.Draw();

	GraphicsDevice.SetRenderTarget(null);
	GraphicsDevice.Clear(Color.Black);
	SpriteBatch.Begin(
		SpriteSortMode.Deferred,
		BlendState.Opaque,
		SamplerState.PointClamp,
		DepthStencilState.None,
		RasterizerState.CullCounterClockwise,
	);
	SpriteBatch.Draw(
		RenderTarget,
		new Rectangle(
			0,
			0,
			Window.ClientBounds.Width,
			Window.ClientBounds.Height),
		null,
		Color.White
	);
	SpriteBatch.End();

	base.Draw(gameTime);
}

first we use SetRenderTarget to make the graphics device draw to our render target instead of the window, and use Clear to clear the render target. then we call our SpriteRenderer.Draw like before.

now we use SetRenderTarget(null) to start drawing to the window again, clear it, and use the SpriteBatch and SpriteBatch.Draw just like before, only now instead of the spritesheet we’re drawing the RenderTarget, and we’re using a new overload of SpriteBatch.Draw that allows us to specify a rectangular region of the target buffer to draw to. we specify the whole screen, and it will scale our RenderTarget to fit.

this is much better! but there’s a problem lurking. imagine if we changed the resolution to one that isn’t the same aspect ratio as our render target, say, 1280x720.

ye gods! my boy! he’s been stretched horizontally! that’s extremely bad.

we don’t want our render target to stretch to fill the whole window. we want it scaled up in a way that preserves aspect ratio, even if that means letterboxing. and for a pixel art game we may want to go further, specifying that we only want to scale to integer multiples of our render resolution so everything looks nice and crisp.

first, create another variable at the top of ProjectName.cs:

public static readonly float AspectRatio = (float)RenderWidth / RenderHeight;

now, in Draw, instead of using ClientBounds directly:

SpriteBatch.Begin(
                SpriteSortMode.Deferred,
                BlendState.Opaque,
                SamplerState.PointClamp,
                DepthStencilState.None,
                RasterizerState.CullCounterClockwise
            );

var height = Window.ClientBounds.Height;
height -= (height % RenderHeight);
var width = (int)MathF.Floor(height * AspectRatio);
var wDiff = Window.ClientBounds.Width - width;
var hDiff = Window.ClientBounds.Height - height;

SpriteBatch.Draw(
	RenderTarget,
	new Rectangle(
		(int)MathF.Floor(wDiff * 0.5f),
		(int)MathF.Floor(hDiff * 0.5f),
		width,
		height),
	null,
	Color.White
);

SpriteBatch.End();

get the height, and use the modulo operator to round it down to the nearest integer multiple of RenderHeight. leave this step out if you don’t care.

then, instead of getting the width of the window, calculate the correct width using the AspectRatio.

next, we need to get the difference between the window width and height and our calculated width and height. now we use those to calculate the X and Y offset for the render target so it draws centered, and we pass in the calculated width and height instead of the renderer width and height.

here’s the end result, shown at a resolution of 1600x900 with the background color set to CornflowerBlue so you can clearly see the letterboxing.

cool!

so now we have a nice rendering setup. i had to explain a lot so it took a while to get here, but i hope you’ll agree it wasn’t too bad. the whole renderer part is only ~50 lines of code.

if you compare this to the examples from other frameworks like love2d, however, this might seem extremely complicated. after all, love2d promises you can just do this:

function love.load()   
	whale = love.graphics.newImage("whale.png")
end   

function love.draw()   
	love.graphics.draw(whale, 300, 200) 
end

and you can do that, and it will work, but we haven’t just put a triangle (or a whale) on the screen. we’ve created an entire structure on which we can build the rest of our game. the love2d example doesn’t include sprite batching or texture atlasing, it isn’t set up to draw more than one sprite, and it isn’t ready to move the sprite around; the sprite just sits at one spot on the screen. you can do all of these things with love2d, but a robust system usable in a real game would look a lot like what we just did.

another massive benefit of this structure is how cleanly it separates rendering from game logic. speaking of which, let’s add some gameplay!

iii. movement

the first step to gameplay is to be able to push buttons and move the player around. this may seem straightforward, but there’s some considerations we have to make.

let’s take a look at the big picture of how some of our systems will connect:

the (M)ECS system architecture is almost like a tree. at the start is our input system. we need a whole separate system for this so that we can use it to drive both in-game elements (player movement) and out of game elements (the menus). the input system will primarily be responsible for taking the concrete stream of discrete input events coming from FNA and turning them into abstracted actions like “move left” or “shoot.” this will allow us to have multiple buttons bound to the same control, and in general is necessary for making controls rebindable by the player.

the player system takes these abstracted actions from the input system and turns them into instructions for the other systems: spawn a bullet, move the player entity by this much. the enemy system and bullet system are very similar, but instead of taking input they just make decisions on their own. having a separate bullet system allows us to do very shmup-like things of having bullets that change their velocity after being fired, for instance to move in a sinusoidal pattern.

the motion system takes input from everything that wants to move. it’s responsible not only for moving everything, but also for checking collision to make sure that a requested movement is possible, and adjusting the trajectories to keep colliders from overlapping.

when collisions do happen, the motion system sends a message to the collision system, which uses the information about which entities have collided to determine what to do next, and sends messages to the appropriate system.

here we only have the health system, which adjusts how much health entities have and destroys them if they run out. but you can imagine this collision system sending messages to a lot of other places:

when two objects collide, those two objects might deal damage to each other, spawn hit particles, shake the screen, cause a sound effect to play, cause the player to pick up an item or powerup, or any number of other things, and this is just considering what might happen in a shmup. here is a powerful rule of thumb:

action games are, in general, a complex set of rules for what happens when things touch other things.

getting this part right is very important because it’s the core of the gameplay.

let’s write some code

first, let’s handle the input. this is a rabbit hole of a subject. much like correct content importing, correct input handling is very dull and complicated.

so, just like with content, i have included with the FNAECSTemplate a default system for handling input. this is based on the real way i handle input in my game DREAM SLAYER.

this consists of two files: Input.cs and InputHelper.cs. InputHelper.cs is a file i generated using a python script. the goal of InputHelper.cs is to allow you to treat all three types of FNA input (gamepad, mouse, and keyboard) as just input, without having to worry about exactly what device produced the input.

to accomplish this, every input is represented as a value between 0 and 1 or between -1 and 1. this is because, for instance, in a first-person shooter, a player playing with mouse and keyboard will probably bind “shoot” to the left mouse button (a boolean input), while a player playing with a controller might bind shoot to the right trigger (an analog input). our generic inputs have to represent the most flexible input type.

the upshot is this: if you go into Input.cs, you should find an enum like this:

public enum Actions
{
	ExampleAction
}

we can replace this with the actions our game has:

public enum Actions
{
    MoveX, MoveY, Shoot
}

and then, a little further down in the ResetActions method, set default bindings for these actions:

public static void ResetActions()
{
	ActionBindings = new Dictionary<Actions, GenericAxis>()
	{
		{Actions.MoveX, new GenericAxis{
			Positive = new HashSet<GenericInputs>(){GenericInputs.Right, GenericInputs.D, GenericInputs.DPadRight, GenericInputs.LeftX},
			Negative = new HashSet<GenericInputs>(){GenericInputs.Left, GenericInputs.A, GenericInputs.DPadLeft}
		}},
		{Actions.MoveY, new GenericAxis{
			Negative = new HashSet<GenericInputs>(){GenericInputs.Up, GenericInputs.W, GenericInputs.DPadUp, GenericInputs.LeftY},
			Positive = new HashSet<GenericInputs>(){GenericInputs.Down, GenericInputs.S, GenericInputs.DPadDown}
		}},
		{Actions.Shoot, new GenericAxis{
			Positive = new HashSet<GenericInputs>(){GenericInputs.Space, GenericInputs.AButton}
		}}
	};
}

this system does not include a prefab way of rebinding controls, because that is dependent on your user interface system. however, this system makes it much easier to rebind controls than every other method i’ve tried. rebindable controls are important, and you should endeavor to allow players to rebind controls with as much freedom as possible in your game. i’ll probably write a separate tutorial just about how you might go about doing this.

anyway, when the Input system detects input for one of your actions, it sends an InputAction message. this message includes three pieces of information: the axis value, the action in question, and the action state (which, for these messages, will always be either pressed, held, or released).

the player

first, let’s go back to Components.cs and add a few more:

public readonly record struct CanBeControlled();
public readonly record struct CanMove(float Speed);

this is where i’m going to introduce a rule of thumb for components: think of them as things an entity can do. sometimes this naming scheme is a little cumbersome, but you could think of a Sprite as a CanBeDrawn component, for instance. MoonTools.ECS developer evan hemsley refers to this as the “fruits principle,” after matthew 7:16:

You will know them by their fruits. Are grapes gathered from thorns or figs from thistles?

(i just wanted to put that in there because i think it’s very funny to talk about the bible in a tutorial about programming.)

in ECS, we don’t care what an entity is. an entity by itself isn’t really anything! it’s just an ID number. we identify entities entirely by what components they have, using filters.

this may seem very abstract right now, but as we follow this principle it will hopefully become more clear. understanding this is key to writing good ECS code.

while we’re at it, update create a new message in Messages.cs:

using Microsoft.Xna.Framework;

namespace ShmupTutorial.Messages;

public readonly record struct Move(Vector2 Delta);

let’s put this into practice. create a new file in the Systems folder called Player.cs:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Messages;
using Microsoft.Xna.Framework;
using ShmupTutorial.Data;

namespace ShmupTutorial.Systems;

public class Player : MoonTools.ECS.System
{

    public Player(World world) : base(world)
    {
    }

    public override void Update(TimeSpan delta)
    {

    }
}

let’s fill in our update loop:

public override void Update(TimeSpan delta)
{
    if (!Some<CanBeControlled>())
        return;

    var player = GetSingletonEntity<CanBeControlled>();

	var movement = Vector2.Zero;

    foreach (var input in ReadMessages<InputAction>())
    {
        if (input.State == ActionState.Pressed || input.State == ActionState.Held)
        {
            switch (input.Action)
            {
                case Actions.MoveX:
                    movement += Vector2.UnitX * input.Value;
                    break;
                case Actions.MoveY:
                    movement += Vector2.UnitY * input.Value;
                    break;
                default:
                    break;
            }
        }
    }

    movement.Normalize();

    if (movement.LengthSquared() > 0.0f)
    {
        Send(player, new Move(movement));
    }
}

first, we have a little guard to make sure that if the player doesn’t exist, the Player system early returns and doesn’t run. this will obviously never be the case now, but in the future the player will be able to die, so we need to be sure.

the Some method is useful for more than just avoiding a runtime error. for instance, it’s common to implement pausing by just creating an entity with a Paused component, and having every system that needs to pause early return if that component exists.

there’s only ever one player, so we can just use the GetSingletonEntity method to get it without having to bother with a filter.

our player has four directional buttons they can press, but we can also move diagonally by pushing two buttons at once. we’ll store our movement delta in this variable called movement. also note that because we’re multiplying by the input value, this will smoothly handle analog movement on analog sticks (i.e. pressing the stick only partially in a direction).

we use ReadMessages<InputAction> to iterate over every action message. this method returns every message sent this frame before this Update loop was called. we check also to make sure that we only care about inputs that are Held or Pressed.

we use a switch statement on this enum to handle all the possible inputs. we don’t care about Shoot right now so we can just ignore it with the default case.

finally, we check if the player is trying to move this frame and if it is, send a Move message. we’re not concerned about speed or delta time correction here, we’ll do that in the Motion system.

also, while we’re here, let’s move the player spawning code into the player system. remove the spawning logic from ProjectName.cs and put it here, in Player.cs

public override void Update(TimeSpan delta)
{
	if (!Some<CanBeControlled>())
	{
		var entity = CreateEntity();
		Set(entity, new Sprite(Content.Textures.Player, 0.0f));
		Set(entity, new Position(new Vector2(ShmupTutorial.RenderWidth * 0.5f, ShmupTutorial.RenderHeight * 0.5f)));
		Set(entity, new CanBeControlled());
		Set(entity, new CanMove(128.0f));
	}

now if there’s no player, the player system will spawn one. we’ll change this as we go on.

bringing it all together: the motion system

create a new file called Motion.cs in the Systems folder.

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Messages;
using Microsoft.Xna.Framework;
using ShmupTutorial.Utility;

namespace ShmupTutorial.Systems;

public class Motion : MoonTools.ECS.System
{
    Filter MotionFilter;

    public Motion(World world) : base(world)
    {
        MotionFilter = 
        FilterBuilder
        .Include<CanMove>()
        .Include<Position>()
        .Build();
    }

    public override void Update(TimeSpan delta)
    {
    }
}

what entities does our Motion system care about? those that have positions and can move. so that’s our MotionFilter. now to fill in the update method:

public override void Update(TimeSpan delta)
{
	foreach (var entity in MotionFilter.Entities)
	{
		var moveDelta = Vector2.Zero;

		foreach (var move in ReadMessagesWithEntity<Move>(entity))
		{
			moveDelta += move.Delta;
		}

		if (moveDelta.LengthSquared() > 0.0f)
		{
			var speed = Get<CanMove>(entity).Speed;
			moveDelta *= speed * (float)delta.TotalSeconds;

			var position = Get<Position>(entity).Value;
			var newPosition = 
			position + moveDelta;

			Set(entity, 
				new Position(
					newPosition
			));
		}
	}
}

we iterate over our our entities from the filter, and use the ReadMessagesWithEntity method to get every message that wants this entity to move. right now there will only ever be one of these, but you could imagine there being multiple Move calls for a single entity on a single frame. doing it this way, looking up the messages associated with a single entity, means we don’t have to go over every single move message just to find the ones we care about, and we want to sum all the movements an entity experiences into a single vector because it will make collision detection easier in the next step.

again, we do the LengthSquared check to see if we need to move the entity at all. we get the speed from the CanMove component on the entity, and then multiply the direction we have with the speed and delta time.

we add our new total delta to the position, and then Set the Position component to use our new value.

bringing it all back home

we’ve gotta initialize these systems and run their update loops. create some new variables at the top of ProjectName.cs:

Input Input;
Player Player;
Motion Motion;

i put these between the variable declaration for the World and the variable declaration for the SpriteRenderer.

now, in LoadContent, where the ExampleSystem initializer used to be:

Input = new Input(World);
Player = new Player(World);
Motion = new Motion(World);

and then, in Update:

protected override void Update(GameTime gameTime)
{
	Input.Update(gameTime.ElapsedGameTime);
	Player.Update(gameTime.ElapsedGameTime);
	Motion.Update(gameTime.ElapsedGameTime);
	World.FinishUpdate();
	base.Update(gameTime);
}

order matters here. if Player.Update runs before Input.Update, it won’t ever be able to see the messages that Input.Update sends. if Motion.Update runs before Player.Update, it won’t be able to see the player’s Move messages. other ecs libraries sometimes have a lot of complex ways to specify the order in which systems run, but MoonTools.ECS doesn’t. those other strategies sound clever but they’re ultimately just annoying to grapple with when you could instead just run the systems in the order you want them to run.

now run the game…

cool! but there’s a problem… we can just go off the screen. we could clamp the player’s position so they can’t do that, but we’re going to need to solve this problem more robustly eventually. what we need is…

iv. collision detection

collision is one of the most profoundly misunderstood subjects in game development. because most big engines like unity and unreal come with these huge, complex rigidbody physics simulations, a lot of people assume that they’re going to need to implement that themselves if they want to make a custom engine. this is not true! not only do you not have to implement actual physics just to detect and respond to collision, for many styles of game you will get better results with simpler collision systems. physically realistic is not always best!

so let’s talk about collision in the abstract a little bit. what do we need?

first, we need some sort of collider shape, and a fast algorithm for determining collision. there are a lot of options here. in 2D, the most obvious choice is the axis-aligned bounding box (AABB). a bounding box is just a rectangle, and “axis aligned” means that it can’t be rotated relative to the world axes.

there’s also the orientable bounding box (OBB), which is a bounding box that can be rotated. if we wanted to go hog wild, we could even use a convex polygon as our bounding shape, and use GJK or the expanding polytope algorithm to determine collisions.

these options add additional complexity for very little benefit. especially in the world of shmups, it’s extremely common for everything to be represented by an axis-aligned bounding box no matter its shape. the error between a non-square object like our player and the bounding box is so small as to be ignored in the heat of gameplay, especially because shmups generally make the player’s hitbox much smaller than the player sprite.

for an example of how far AABBs can get you, look at this screenshot from street fighter with the hitboxes and hurtboxes highlighted:

ryu and guy are nowhere close to being shaped like AABBs, but the developers and designers at capcom were able to approximate their shapes using AABBs. look at how rough those approximations are! they’re not even close to pixel-perfect. and this isn’t just the case for this game, or street fighter, or old fighting games, this is how fighting games are made now, because it’s just better. AABBs offer huge performance improvements compared to other methods because the algorithm to check their collision is so cheap. on top of that, this way of designing hitboxes is better for designers. it’s much easier for designers to work with, it’s much easier to make tooling for, and it results in better gameplay.

enough talk, let’s code

we’re going to leverage another feature of MoonTools.ECS (and many other ECS libraries) here: entity relations. an entity relation is just like a component in that it contains only data, but instead of being tied to just one entity, it’s tied to two. we’re going to do this to build a collision system that will let us attach multiple colliders to one entity to create more complex colliders.

an important aspect of relations is that they are directional. that is to say, Relate(a, b, new Relation()) is different to Relate(b, a, new Relation()). the first one is a relationship “from a to b,” and the second is a relationship “from b to a.”

we can get a relation from a to b, on a’s end using the method OutRelation<Relation>(a), or on b’s end using the method InRelation<Relation>(b). this directionality is really useful. it allows us to easily express that it’s the player that has the collider, not the other way around, but we can still get the relation data from either end.

create a new relation in Relations.cs:

using Microsoft.Xna.Framework;

namespace ShmupTutorial.Relations;

public readonly record struct HasCollider();

add a new using ShmupTutorial.Relations; statement to the top of Player.cs and add to the player creation logic:

if (!Some<CanBeControlled>())
{
	var entity = CreateEntity();
	var sprite = Content.Textures.Player;

	var collider = CreateEntity();
	Set(collider, new AABB(0, 0, 8, 8));

	Set(entity, new Sprite(sprite, 0.0f));
	Set(entity, new Position(new Vector2(ShmupTutorial.RenderWidth * 0.5f, ShmupTutorial.RenderHeight * 0.5f)));
	Set(entity, new CanBeControlled());
	Set(entity, new CanMove(128.0f));
	Relate(entity, collider, new HasCollider());
}

so we create a second entity to store our collider, and then Relate them using the HasCollider relation we just created. the collider entity has just one component, the AABB.

you’ll see we’re using the AABB class i put in the Components directory of the FNAECSTemplate. you can have a look at the code if you want. it contains a definition of an AABB, as well as functions for checking if AABBs overlap (using the minkowski difference) and returns the penetration vector.

all we have to do is tweak our Motion system to use our new colliders.

first, we need a new filter to find all the colliders in the scene:

Filter ColliderFilter;

public Motion(World world) : base(world)
{
	MotionFilter = FilterBuilder.Include<CanMove>().Include<Position>().Build();
	ColliderFilter = FilterBuilder.Include<AABB>().Build();
}

now, we need a method to try out a movement we want to do and see if it will collide with anything, and adjust the trajectory to avoid the collision.

public (bool hit, Vector2 position, HashSet<Entity> hitEntities) CollisionTest(Entity entity, Vector2 delta)
{
	var colliders = OutRelations<HasCollider>(entity);
	var position = Get<Position>(entity).Value;
	var outPosition = position + delta;
	var hit = false;
	var hitEntities = new HashSet<Entity>();

	foreach (var collider in colliders)
	{
		foreach (var otherCollider in ColliderFilter.Entities)
		{
			var otherEntity = otherCollider;

			if (HasInRelation<HasCollider>(otherEntity))
				otherEntity = InRelationSingleton<HasCollider>(otherCollider);

			if (otherEntity != entity)
			{
				var rect = Get<AABB>(collider);
				rect = rect.ToWorld(outPosition);
				var otherRect = Get<AABB>(otherCollider);
				var otherPos = Has<Position>(otherEntity) ? Get<Position>(otherEntity).Value : Vector2.Zero;
				otherRect = otherRect.ToWorld(otherPos);

				var (vector, overlaps) = rect.Overlaps(otherRect);

				if (overlaps)
				{
					hit = true;
					outPosition -= vector;
					hitEntities.Add(otherEntity);
				}
			}
		}
	}

	return (hit, new Vector2(outPosition.X, outPosition.Y), hitEntities);
}

let’s break this down.

first, our function signature. this needs to return three pieces of information: whether or not there was a collision, the adjusted end position of our trajectory to avoid any collisions, and all the entities we hit. for this, we use a tuple.

we store all the hit entities in a HashSet, because we don’t care if we hit the same entity more than once.

our CollisionTest method takes the entity we’re testing, and its delta vector, i.e. how we want it to move this frame.

first, we get all the colliders this entity has. we set up colliders using relations so one entity can have more than one. we also the get the entity’s starting position, and create a new variable called outPosition to represent the target destination. we also create a variable called hit, which will store whether we’ve collided with anything, and a variable called hitEntities, which will store the entities we hit.

now, we test each collider independently. with each collider, we go through every other collider in the scene and get the entity it is attached to. we want to support both colliders that don’t have relations (for static objects like the level boundaries) and colliders that do have relations. if it has a relation, we treat the entity it’s related to as the source of the collision. otherwise we use the collider entity itself.

next, we check to make sure we never check self-collisions. this lets you create complex shapes by layering AABBs on top of each other and it avoid the obvious problem of checking to see if an AABB collides with itself.

for the check itself, we get the rects and use the ToWorld method with the entity positions to convert them from local space to world space. this makes specifying the location of AABBs much easier, since when we create entities we can specify their position relative to the entity’s origin and we don’t have to update the AABB position every time the entity moves.

then, we use Overlaps to check the collision. if there’s a collision, we set hit to true, adjust outPosition by the penetration vector, and add the entity we hit to the set of hit entities.

at the end of the method, we return all the information we’ve collected.

now, let’s adjust our Motion system’s update loop to use this new method:

if (moveDelta.LengthSquared() > 0.0f)
{
	var speed = Get<CanMove>(entity).Speed;
	moveDelta *= speed * (float)delta.TotalSeconds;

	var position = Get<Position>(entity).Value;
	var newPosition = position;

	if (HasOutRelation<HasCollider>(entity))
	{
		var deltaX = new Vector2(moveDelta.X, 0.0f);
		var deltaY = new Vector2(0.0f, moveDelta.Y);

		var outX = CollisionTest(entity, deltaX);
		var outY = CollisionTest(entity, deltaY);

		newPosition = new Vector2(outX.position.X, outY.position.Y);
	}
	else
	{
		newPosition += moveDelta;
	}

	Set(entity, new Position(newPosition));
}

now we have this if statement that checks if the entity we want to move has one or more colliders. if it doesn’t, we do what we did before. if it does, we check collision. we check the X and Y axes separately so that we can still move along one axis even if there’s a collision along the other.

finally we need to add something to collide with. in ProjectName.cs, where there used to be the player creation code, instead put:

var leftBounds = World.CreateEntity();
World.Set(leftBounds, new AABB(-4.0f, RenderHeight * 0.5f, 8.0f, RenderHeight));

var rightBounds = World.CreateEntity();
World.Set(rightBounds, new AABB(RenderWidth + 4.0f, RenderHeight * 0.5f, 8.0f, RenderHeight));

var topBounds = World.CreateEntity();
World.Set(topBounds, new AABB(RenderWidth * 0.5f, -4.0f, RenderWidth, 8.0f));

var bottomBounds = World.CreateEntity();
World.Set(bottomBounds, new AABB(RenderWidth * 0.5f, RenderHeight + 4.0f, RenderWidth, 8.0f));

now, if you run the game, you shouldn’t be able to leave the screen anymore:

a problem

there’s another problem that might come up in some games, including ours. imagine, as is easily possible in a shmup, there are 100 hitboxes on the screen: the player, all the bullets, and all the enemies. in order to detect every collision, we have to perform every possible combination, which in math is called “100 choose 2,” calculated as (100!)/(2! * 98!) = 4950. that’s a lot! if there’s 200 items on screen, which is still easily possible, it’s 19,900 comparisons.

most of these comparisons, though, are stupid. they’re comparing items that are nowhere near each other. if only there were some way to only compare items that are close enough to each other to possibly be colliding…

this is the problem a collision broadphase is supposed to solve. reading the problem, you might have thought of a simple one: just only check the collisions within a certain radius! unfortunately, this just moves the problem. to do this, we still have to do comparisons between every single pair of items every frame in order to compute their distances. what if we could figure out if two objects were close together without having to explicitly compute their distance?

it turns out there are lots of ways to do this. popular ones include quadtrees (in 2D) and octrees (in 3D), k-d trees, binary space partitioning, R-trees… you get the picture. because collision is such an important part of action games, considering what collision detection algorithm and broadphase you use is very important. sometimes you may not need a broadphase! in tyler glaiel’s excellent blog post about why and how to make your own game engine, he mentions that the end is nigh shipped without a collision broadphase, and this makes perfect sense: there are very few objects on the screen at once, and most of them don’t move.

we’re going to use one called a spatial hash. i like this one because it’s dead simple to implement and works great for a lot of different kinds of games. the idea behind a spatial hash is that you break up space into a grid, like this:

imagine that the colored squares are our colliders. each cell of the grid has an associated list of entities, sometimes called “bin” or “bucket.” we put each entity into all the buckets its collider touches. then, when we want to know what could possibly be colliding with an entity, we retrieve all the other entities that are in the buckets its collider touches.

in this example, the smaller blue square fits only in one cell. the larger red square fits in several cells, but we can know for sure that these two shapes can’t be colliding, because they aren’t in any of the same cells. the medium sized yellow square does share some cells with the large red square, so we have to check in the narrow phase to discover that they aren’t colliding. and finally, the green square is colliding with the red square, and we know to check it because they share several cells.

one important aspect of spatial hashes is you want to tune the cell size correctly. too small, and most objects will be in multiple cells, which means the insertion time will go up. too large, and most cells will contain too many objects, making the narrow phase collision checking slower. the sweet spot is usually somewhere around twice as large as a typical object in your game. our player hitbox is 8x8, so for us a good value might be 16x16.

if you’ve been paying attention, you might know what we can use to make this data structure: a Dictionary! inserting and looking up objects in a Dictionary is not free, but it’s much cheaper than thousands of pairwise comparisons.

let’s implement a spatial hash

first, at the top of Motion.cs, we need two more variables:

const int CellSize = 16;
const float CellReciprocal = 1.0f / CellSize;
Dictionary<(int, int), HashSet<Entity>> SpatialHash = new Dictionary<(int, int), HashSet<Entity>>();

first is the CellSize, or the size of our buckets for the spatial hash. here it’s 16. we also store the CellReciprocal: we’re going to be dividing by CellSize, and it’s faster for the CPU to multiply by the reciprocal instead.

finally we have the SpatialHash, which is a Dictionary between (int, int) tuples and a HashSet<Entity>. tuples in C# are value types so we can create as many of them as we want very cheaply.

to get those (int, int) tuples, let’s write a function to take a Vector2 and spit out the bucket it’s in:

    public (int x, int y) Bucket(Vector2 position)
    {
        return (
            (int)MathF.Floor(position.X * CellReciprocal),
            (int)MathF.Floor(position.Y * CellReciprocal)
        );
    }

now we need a method to insert colliders into the hash:

public void Insert(Entity e)
{
	var aabb = Get<AABB>(e);

	if (HasInRelation<HasCollider>(e))
	{
		var parent = InRelationSingleton<HasCollider>(e);
		aabb = aabb.ToWorld(Get<Position>(parent).Value);
	}

	var minBucket = Bucket(aabb.TopLeft);
	var maxBucket = Bucket(aabb.BottomRight);

	for (int x = minBucket.x; x <= maxBucket.x; x++)
	{
		for (int y = minBucket.y; y <= maxBucket.y; y++)
		{
			var key = (x, y);
			if (!SpatialHash.ContainsKey(key))
			{
				SpatialHash.Add(key, new HashSet<Entity>());
			}

			SpatialHash[key].Add(e);
		}
	}
}

we do the same “get the AABB and convert it to world space if necessary” dance that we did in the CollsionTest method. then we get the smallest and largest bucket coordinates and use a double for loop to iterate over every bucket this collider touches.

to insert the entity, we first create the HashSet if it doesn’t already exist, then add the entity to it.

the Retrieve method is almost the same but in reverse:

public HashSet<Entity> Retrieve(Entity e)
{
	var aabb = Get<AABB>(e);
	var entities = new HashSet<Entity>();

	if (HasInRelation<HasCollider>(e))
	{
		var parent = InRelationSingleton<HasCollider>(e);
		aabb = aabb.ToWorld(Get<Position>(parent).Value);
	}

	var minBucket = Bucket(aabb.TopLeft);
	var maxBucket = Bucket(aabb.BottomRight);

	for (int x = minBucket.x; x <= maxBucket.x; x++)
	{
		for (int y = minBucket.y; y <= maxBucket.y; y++)
		{
			var key = (x, y);
			if (SpatialHash.ContainsKey(key))
			{
				entities.UnionWith(SpatialHash[key]);
			}
		}
	}

	return entities;
}

instead of adding to the HashSet, we use UnionWith to add its contents to the main HashSet we’re going to return.

now, in CollisonTest, replace

foreach (var otherCollider in CollisionFilter.Entities)

with

foreach (var otherCollider in Retrieve(collider))

and put the following at the top of Update:

foreach (var key in SpatialHash.Keys)
{
	SpatialHash[key].Clear();
}

foreach (var entity in ColliderFilter.Entities)
{
	Insert(entity);
}

the first step clears all the buckets so they can be ready for the new frame. the second step inserts every collider into the hash set so we can retrieve them later.

we don’t just call SpatialHash.Clear because those HashSets are classes, allocated on the heap. we don’t want to destroy them every frame, that would cause a lot of garbage collection pressure. instead we just want to empty them out. speaking of which…

an optimiziation

reading that last paragraph, you may notice we’re creating a bunch of HashSets every frame. we could improve this and use the same spatial hash multiple times.

we need two, at the top of Motion.cs:

HashSet<Entity> HitEntities = new HashSet<Entity>();
HashSet<Entity> RetrievedEntities = new HashSet<Entity>();

our Retrieve function signature changes:

void Retrieve(Entity e)

and we can replace

var entities = new HashSet<Entity>();

with

RetrievedEntities.Clear();

update our UnionWith:

if (SpatialHash.ContainsKey(key))
{
	RetrievedEntities.UnionWith(SpatialHash[key]);
}

and get rid of the

return entities;

at the end.

similarly, our collision test becomes

(bool hit, Vector2 position) CollisionTest(Entity entity, Vector2 delta)

and remove

var hitEntities = new HashSet<Entity>();

and our for loop is a little different, instead of

foreach (var otherCollider in Retrieve(collider))

it becomes

Retrieve(collider);
foreach (var otherCollider in RetrievedEntities)

and

hitEntities.Add(otherEntity)

becomes

HitEntities.Add(otherEntity)

and don’t forget to modify the return:

return (hit, new Vector2(outPosition.X, outPosition.Y));

and when calling CollisionTest:

HitEntities.Clear();
var outX = CollisionTest(entity, deltaX);
var outY = CollisionTest(entity, deltaY);

this kind of optimization can make the code harder to understand, and it’s a bit of a pain in the ass, but the Motion system is the beating heart of this whole operation. every little optimization we can squeeze out really counts to improving the performance of the whole game.

at this point, if you run the game, it should work exactly the same as before we did any of the broadphase stuff. when you’ve done something right, people won’t know you’ve done anything at all.

we’re going to have to return to the land of collision detection in a moment, but let’s take a small break.

v. spawning

it wouldn’t be a shmup if we couldn’t shoot (’em up). let’s implement that.

first, we need some new components:

public readonly record struct Direction(Vector2 Value);
public readonly record struct CanDealDamage();

and a new message

public readonly record struct Shoot(Entity Source, Vector2 Direction, float Speed);

now, our Bullet system:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Data;
using ShmupTutorial.Messages;

namespace ShmupTutorial.Systems;

public class Bullet : MoonTools.ECS.System
{
    public Filter BulletFilter;

    public Bullet(World world) : base(world)
    {
        BulletFilter = FilterBuilder
                        .Include<Sprite>()
                        .Include<Position>()
                        .Include<Direction>()
                        .Include<CanMove>()
                        .Include<CanDealDamage>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var message in ReadMessages<Shoot>())
        {
            var position = Get<Position>(message.Source).Value;

            var entity = CreateEntity();
            Set(entity, new Sprite(Content.Textures.Bullet, 0.0f));
            Set(entity, new Position(position));
            Set(entity, new Direction(message.direction));
            Set(entity, new CanMove(message.Speed));
            Set(entity, new CanDealDamage());
        }
    }
}

you should at this point have a pretty good idea of what all this does, but let’s go through it.

the main thing that’s different here is the complexity of the filter. remember the fruits principle? we don’t need a separate Bullet component, we can identify what is and is not a bullet using components we already have. a bullet is something with a Sprite, Position, and Direction which CanMove and CanDealDamage.

in Update, we look for Shoot messages and spawn in the bullets. create an entity, give it components, you’ve seen this before.

don’t forget to initialize and update the system in ProjectName.cs:

Bullet Bullet;

(...)

Bullet = new Bullet(World);

(...)

protected override void Update(GameTime gameTime)
{
	Input.Update(gameTime.ElapsedGameTime);
	Player.Update(gameTime.ElapsedGameTime);
	Bullet.Update(gameTime.ElapsedGameTime);
	Motion.Update(gameTime.ElapsedGameTime);
	World.FinishUpdate();
	base.Update(gameTime);
}

also let’s add a bit to the Motion system to use this Direction information:

foreach (var entity in MotionFilter.Entities)
{
	var moveDelta = Vector2.Zero;

	foreach (var move in ReadMessagesWithEntity<Move>(entity))
	{
		moveDelta += move.Delta;
	}

	if (Has<Direction>(entity)) //NEW
		moveDelta += Get<Direction>(entity).Value; //NEW

now we need to send shoot messages from the Player. let’s update our input handler:

var shoot = false;

foreach (var input in ReadMessages<InputAction>())
{
    if (input.State == ActionState.Pressed || input.State == ActionState.Held)
    {
        switch (input.Action)
        {
            case Actions.MoveX:
                movement += Vector2.UnitX * input.Value;
                break;
            case Actions.MoveY:
                movement += Vector2.UnitY * input.Value;
                break;
            case Actions.Shoot:
                shoot = true;
                break;
            default:
                break;
        }
    }
}

and the shooting and movement messages:

if (shoot)
    Send(new Shoot(player, -Vector2.UnitY, 256.0f));

if (movement.LengthSquared() > 0.0f)
    Send(player, new Move(movement));

alright now let’s just launch the game and see —

holy crap! that’s a lot of bullets. it’s firing a bullet every frame. also, these bullets have no colliders and never get destroyed, so if you held down the button forever you’d slow the game to a crawl and then run out of memory.

let’s fix the first thing first. it might be tempting to go with a bespoke solution just for bullet delay, but let’s stop and think for a moment. delay and other timer-based mechanics are extremely common in video games. what if we could have a generic timer system that we could use to easily add new functions like that to our game?

create a new component:

public struct Timer
{
    public float Time { get; private set; }
    public float Max { get; }
    public float Remaining
    {
        get
        {
            return Time / Max;
        }
    }

    public Timer(float time)
    {
        Time = Max = time;
    }

    public Timer Update(float newTime)
    {
        Time = newTime;
        return this;
    }
}

this is a full struct instead of a one-liner because we want more features from our timer. we won’t use them right now, but later.

now, create a CanShoot component:

public readonly record struct CanShoot(float Delay);

and add it to the player:

if (!Some<CanBeControlled>())
{
	var entity = CreateEntity();
	var sprite = Content.Textures.Player;

	var collider = CreateEntity();
	Set(collider, new AABB(0, 0, 8, 8));

	Set(entity, new Sprite(sprite, 0.0f));
	Set(entity, new Position(new Vector2(ShmupTutorial.RenderWidth * 0.5f, ShmupTutorial.RenderHeight * 0.5f)));
	Set(entity, new CanBeControlled());
	Set(entity, new CanMove(128.0f));
    Set(entity, new CanShoot(0.1f));
	Relate(entity, collider, new HasCollider());
}

and then add a new relation:

public readonly record struct DisableShoot();

now let’s create a new system called Time.cs:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;

namespace ShmupTutorial.Systems;

public class Time : MoonTools.ECS.System
{
    public Filter TimerFilter;

    public Time(World world) : base(world)
    {
        TimerFilter = FilterBuilder
                        .Include<Timer>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var entity in TimerFilter.Entities)
        {
            var timer = Get<Timer>(entity);
            var t = timer.Time - (float)delta.TotalSeconds;

            if (t <= 0.0f)
                Destroy(entity);
            else
                Set(entity, timer.Update(t));
        }
    }
}

all this does is look for every timer in the scene, reduce the amount of time on it by the current delta time, and destroy the timer if it’s less than zero. when entities are destroyed, their relationships are destroyed with them. see where this is going?

we created this timer.Update method because we want to keep the original value of Max. if we used the constructor again, Max would get reset to the same value as Time.

don’t forget to initialize in ProjectName.cs:

Time Time;

(...)

Time = new Time(World);

(...)

protected override void Update(GameTime gameTime)
{
	Time.Update(gameTime.ElapsedGameTime);
	Input.Update(gameTime.ElapsedGameTime);
	Player.Update(gameTime.ElapsedGameTime);
	Bullet.Update(gameTime.ElapsedGameTime);
	Motion.Update(gameTime.ElapsedGameTime);
	World.FinishUpdate();
	base.Update(gameTime);
}

let’s change our Shoot logic in the Bullet system:

foreach (var message in ReadMessages<Shoot>())
{
	if (Has<CanShoot>(message.Source) && !HasInRelation<DisableShoot>(message.Source))
	{
		var position = Get<Position>(message.Source).Value;

		var entity = CreateEntity();
		Set(entity, new Sprite(Content.Textures.Bullet, 0.0f));
		Set(entity, new Position(position));
		Set(entity, new Direction(message.direction));
		Set(entity, new CanMove(message.Speed));
		Set(entity, new CanDealDamage());

		Send(entity, new Move(message.direction));

		var delay = Get<CanShoot>(message.Source).Delay;
		var timer = CreateEntity();
		Set(timer, new Timer(delay));
		Relate(timer, message.Source, new DisableShoot());
	}
}

mostly the same, but now there’s this check at the top for CanShootand this HasInRelation check for DisableShoot. when the entity shoots, it reads the Delay field from the CanShoot component and creates a timer of that length related to the shooter with a DisableShoot relation.

this is very powerful. now, not only the player will have an appropriate shooting delay, but all enemies will as well, since they’ll use this same shooting logic. on top of that, we have a generic system for disabling shooting based on a timer. want to disable shooting for a second when the player takes damage? want to disable shooting for a reloading mechanic? you can do that here. any system can add a timer with a DisableShoot relation to the player, there can be more than one of them, and as long as one of them is present, the player can’t shoot.

if we run this, it looks much better:

but our bullets are still sticking around forever. we may want them to be destroyed if they go off the screen, but if they’re destroyed immediately upon hitting the level bounds that would look pretty bad. also, sometimes shmups give you weapons with more limited range. we really want our bullets to be destroyed after they’ve traveled a certain distance.

create two new components:

public readonly record struct DestroyOnDistanceTraveled(float Max, float Traveled = 0.0f);
public readonly record struct MarkedForDestroy();

the DestroyOnDistanceTraveled is going to do what it says on the tin, keep track of the traveled distance and destroy the entity when it’s traveled too far. that’s where MarkedForDestroy comes in. we have two problems: one is that sometimes we’ll want to destroy an entity, but we may still need to use it before it’s destroyed. the other is that many of our entities have relations to colliders we also want to destroy, and we have to clean those up. rather than a repetitive pattern, let’s make a Destroyer system:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Relations;

namespace ShmupTutorial.Systems;

public class Destroyer : MoonTools.ECS.System
{
    public Filter DestroyFilter;

    public Destroyer(World world) : base(world)
    {
        DestroyFilter = FilterBuilder
                        .Include<MarkedForDestroy>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var entity in DestroyFilter.Entities)
        {
            foreach (var collider in OutRelations<HasCollider>(entity))
                Destroy(collider);

            Destroy(entity);
        }
    }
}

we won’t have to use this for every destruction, we can freely destroy objects that have no relations and are guaranteed to never be used by another system before the end of the frame with the regular Destroy method. for instance, we don’t have to use this to destroy Timers. but this will be very handy and allow us to all in one place run the checks and any cleanup logic that needs to happen whenever an entity gets destroyed.

don’t forget to update ProjectName.cs:

Destroyer Destroyer;

(...)

Destroyer = new Destroyer(World);

(...)

protected override void Update(GameTime gameTime)
{
    Destroyer.Update(gameTime.ElapsedGameTime);
	Time.Update(gameTime.ElapsedGameTime);
	Input.Update(gameTime.ElapsedGameTime);
	Player.Update(gameTime.ElapsedGameTime);
	Bullet.Update(gameTime.ElapsedGameTime);
	Motion.Update(gameTime.ElapsedGameTime);
	Collision.Update(gameTime.ElapsedGameTime);
	World.FinishUpdate();
	base.Update(gameTime);
}

Destroyer can really run at any time, since it’s reading components and not messages. i’m putting it first because we’re going to have it send a message to another system later.

now, after the collision checks, add the following to the Motion system:

if (HasOutRelation<HasCollider>(entity))
{
	var deltaX = new Vector2(moveDelta.X, 0.0f);
	var deltaY = new Vector2(0.0f, moveDelta.Y);

	HitEntities.Clear();

	var outX = CollisionTest(entity, deltaX);
	var outY = CollisionTest(entity, deltaY);

	newPosition = new Vector2(outX.position.X, outY.position.Y);
}
else
{
	newPosition += moveDelta;
}

//NEW!
if (Has<DestroyOnDistanceTraveled>(entity) && !Has<MarkedForDestroy>(entity))
{
	var dest = Get<DestroyOnDistanceTraveled>(entity);
	var distance = (newPosition - position).Length();
	var totalDist = dest.Traveled;
	totalDist += distance;
	Set(entity, new DestroyOnDistanceTraveled(dest.Max, totalDist));
	if (totalDist > dest.Max)
	{
		Set(entity, new MarkedForDestroy());
	}
}

Set(entity, new Position(newPosition));

get the actual distance traveled by subtracting the new position from the old position, check if that’s over the allowed max, and if it is, mark it for destruction. also update the total distance on the component so it keeps track. we also check in the if if it’s already marked for destruction, because there’s no point in running this check if the entity is just going to get destroyed for some other reason anyway.

now we can add it to our bullet spawning logic:

var entity = CreateEntity();
var sprite = Content.Textures.Bullet;
Set(entity, new Sprite(sprite, 1.0f));
Set(entity, new Position(position));
Set(entity, new Direction(message.Direction));
Set(entity, new CanMove(message.Speed));
Set(entity, new CanDealDamage());
Set(entity, new DestroyOnDistanceTraveled(ShmupTutorial.RenderHeight * 1.5f));

our range here is going to be a little more than the RenderHeight, so our bullets will always disappear offscreen. but you can set that number to anything. play around with it to get results like this:

(that’s with a max distance of 128.)

now that we have “shoot,” we still need an ’em to shoot up.

spawning enemies

our basic Enemy system is very simple:

using System;
using Microsoft.Xna.Framework;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Data;
using ShmupTutorial.Relations;
using ShmupTutorial.Utility;

namespace ShmupTutorial.Systems;

public class Enemy : MoonTools.ECS.System
{
    public Filter EnemyFilter;

    public Enemy(World world) : base(world)
    {
        EnemyFilter = FilterBuilder
                        .Include<Sprite>()
                        .Include<Position>()
                        .Include<CanMove>()
                        .Include<CanDealDamage>()
                        .Exclude<DestroyOnDistanceTraveled>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        if (EnemyFilter.Count == 0)
        {
            var enemy = CreateEntity();
            var sprite = Content.Textures.Enemy;
            Set(enemy, new Sprite(sprite, 0.5f));
            Set(enemy, new Position(new Vector2(Rando.Range(0, ShmupTutorial.RenderWidth), ShmupTutorial.RenderHeight * 0.2f)));
            Set(enemy, new CanMove(64.0f));
            Set(enemy, new CanDealDamage());

            var collider = CreateEntity();
            Set(collider, new AABB(0f, 0f, sprite.Width, sprite.Height));
            Relate(enemy, collider, new HasCollider());
        }
    }
}

and don’t forget to update ProjectName.cs:

Enemy Enemy;

(...)

Enemy = new Enemy(World);

(...)

protected override void Update(GameTime gameTime)
{
    Destroyer.Update(gameTime.ElapsedGameTime);
    Time.Update(gameTime.ElapsedGameTime);
    Input.Update(gameTime.ElapsedGameTime);
    Player.Update(gameTime.ElapsedGameTime);
    Enemy.Update(gameTime.ElapsedGameTime);
    Bullet.Update(gameTime.ElapsedGameTime);
    Motion.Update(gameTime.ElapsedGameTime);
    World.FinishUpdate();
    base.Update(gameTime);
}

we don’t even need any new components, we can express what an Enemy is for our purposes using exclusively components we already have: it’s something that has a Sprite and a Position, it CanMove and CanDealDamage, but it doesn’t DestroyOnDistanceTraveled. there’s a few other components we’ll add later to further differentiate an Enemy from a Bullet.

the spawning logic is exactly the same as for the Player, only with some of the values tweaked and no CanBeControlled component. we’re using the Rando random number generator class I include with the FNAECSTemplate to position the enemy somewhere randomly between the left and right edges of the screen.

if you run this and try to shoot the enemy, you’ll immediately see there’s a problem:

well THAT’S not supposed to happen.

vi. collision detection ii: cruise control

we have a few problems to solve.

1. bullets should disappear when they hit things.
2. bullets shouldn’t hit the entity that shot them. (this is why the bullets fire off-center)
3. bullets shouldn’t collide with each other.

let’s tackle this second problem first. again, like with the timer, we may be tempted to do a hacky solution to this, but let’s think about what we really want. we want to have control over which entities can collide with each other. we want collision layers.

collision layers are kind of exactly what they sound like. you can think of them like layers in photoshop if that’s familiar to you, or just like abstract categories or tags. things can only interact via collision if they share a layer, and unlike in photoshop, a single entity can be on multiple layers.

how do we implement this? we want these comparisons to be fast, and we want them to be easy for us to write. fortunately, there’s something for us: bitflags.

in C#, bitflags are a kind of enum. create a new enum in the Components file:

[Flags]
public enum CollisionLayer
{
    None = 0,
    Level = 1,
    Actor = 2,
    Player = 4,
    Enemy = 8,
    Bullet = 16,
    Pickup = 32,
    PlayerActor = Player | Actor | Level | Pickup,
    EnemyActor = Enemy | Actor,
    PlayerBullet = Enemy | Bullet,
    EnemyBullet = Player | Bullet
}

ok so this is a bit of a mess of notation. but let’s break it down. bitflags take advantage of two things: binary numbers and bitwise operations.

consider the number 32 (the highest number in our bitflag) written in binary:

100000

it’s a 1 in the highest place value, and then all zeroes. now imagine that instead of thinking about it as “32,” we thought of each digit as an on/off or true/false flag for one of our layers. so something with only the Level layer would look like:

000001

something with the Level layer and the Player layer would be:

000101

something with just the Enemy layer would be;

001000

and so on.

how do we check to see if two objects share a layer? with the bitwise and operator.

bitwise operators are called that because they work on each digit, or bit, individually.

the operators we are concerned with are & (and) and | (or). you’ll notice these look a lot like their boolean counterparts && and ||, but don’t confuse them.

the & operator goes bit by bit through its two operands and makes the bit in the output bit 1 if the corresponding bits in both operands is 1.

consider 000101 & 001000. this is easier to see when written vertically:

000101
AND
001000

000000 // result

the output here is zero because these two numbers don’t share any 1s. in contrast, consider:

000101
AND
001001

000001

we got a match! the result here is non-zero because the last place in both operands is 1, so the output is 1. this means we can easily check if two colliders share a layer with

LayerA & LayerB != 0

if this is true, they share a layer somewhere and should collide.

often, we’ll want colliders to be on multiple layers. this is where the | operator comes in. this makes the output bit 1 if either operand has a 1 in that position. an example:

000101
OR
001000

001101

we can use this to combine layers. LayerA | LayerB is a way of combining the two into a single number that has both. that’s what we’re saying with the

PlayerActor = Player | Actor | Level | Pickup,
EnemyActor = Enemy | Actor | Level,
PlayerBullet = Enemy | Bullet,
EnemyBullet = Player | Bullet

section of our bitflags. you can think of this as kind of like defining a “prefab” layer combination. when we use CollisionLayer.PlayerActor, it’s just like if we said CollisionLayer.Player | CollisionLayer.Actor | CollisionLayer.Level | CollisionLayer.Pickup, but way less verbose.

we have all these layers because we need some entities, like bullets and enemies, to avoid self-collision. i’ll show you as we build.

first, we need a new component:

public readonly record struct Layer(CollisionLayer Collide, CollisionLayer Exclude = 0);

so we can specify layers for collision, as well as layers we don’t want to collide with.

we can now change the player collider creation logic:

var collider = CreateEntity();
Set(collider, new AABB(0, 0, 8, 8));
Set(collider, new Layer(CollisionLayer.PlayerActor));

the enemy colllider creation logic:

var collider = CreateEntity();
Set(collider, new AABB(0f, 0f, sprite.Width, sprite.Height));
Set(collider, new Layer(CollisionLayer.EnemyActor, CollisionLayer.Enemy));
Relate(enemy, collider, new HasCollider());

the level boundaries creation logic:

var leftBounds = World.CreateEntity();
World.Set(leftBounds, new Layer(CollisionLayer.Level));
World.Set(leftBounds, new AABB(-4.0f, RenderHeight * 0.5f, 8.0f, RenderHeight));

var rightBounds = World.CreateEntity();
World.Set(rightBounds, new Layer(CollisionLayer.Level));
World.Set(rightBounds, new AABB(RenderWidth + 4.0f, RenderHeight * 0.5f, 8.0f, RenderHeight));

var topBounds = World.CreateEntity();
World.Set(topBounds, new Layer(CollisionLayer.Level));
World.Set(topBounds, new AABB(RenderWidth * 0.5f, -4.0f, RenderWidth, 8.0f));

var bottomBounds = World.CreateEntity();
World.Set(bottomBounds, new Layer(CollisionLayer.Level));
World.Set(bottomBounds, new AABB(RenderWidth * 0.5f, RenderHeight + 4.0f, RenderWidth, 8.0f));

and first update the Shoot message:

public readonly record struct Shoot(Entity Source, CollisionLayer Layer, Vector2 Direction, float Speed);

and its use in the Player system:

Send(new Shoot(player, CollisionLayer.PlayerBullet, -Vector2.UnitY, 256.0f));

then update the bullet collider creation logic:

var entity = CreateEntity();
var sprite = Content.Textures.Bullet;
Set(entity, new Sprite(sprite, 0.0f));

...

var collider = CreateEntity();
Set(collider, new AABB(0f, 0f, sprite.Width, sprite.Height));
Set(collider, new Layer(message.Layer, CollisionLayer.Bullet));
Relate(entity, collider, new HasCollider());

note how the bullet collider excludes all entities on the Bullet layer, so bullets will never self collide.

now we can update our Motion system. first, change the collider filter:

ColliderFilter = FilterBuilder
.Include<AABB>()
.Include<Layer>()
.Build();

and in the CollisionTest method, get the layers for the moving collider:

foreach (var collider in colliders)
{
	var layer = Get<Layer>(collider);

and the other collider:

foreach (var otherCollider in RetrievedEntities)
{
	var otherEntity = otherCollider;

	if (HasInRelation<HasCollider>(otherEntity))
		otherEntity = InRelationSingleton<HasCollider>(otherEntity);

	var otherLayer = Get<Layer>(otherCollider);

and use it in the if where we previously just checked for self-collision:

if (otherEntity != entity &&
	(layer.Collide & otherLayer.Collide) != 0 &&
	(layer.Exclude & otherLayer.Collide) == 0
	)

resolving collisions

ok, so we want something to happen when the bullets hit the level bounds. first, create a new component:

public readonly record struct DestroyOnHit();

and while we’re at it, attach it to the bullets:

var entity = CreateEntity();
var sprite = Content.Textures.Bullet;
Set(entity, new Sprite(sprite, 0.0f));
Set(entity, new Position(position));
Set(entity, new Direction(message.Direction));
Set(entity, new CanMove(message.Speed));
Set(entity, new CanDealDamage());
Set(entity, new DestroyOnHit());

you can also Include this in the Bullet filter:

BulletFilter = FilterBuilder
				.Include<Sprite>()
				.Include<Position>()
				.Include<Direction>()
				.Include<CanMove>()
				.Include<CanDealDamage>()
				.Include<DestroyOnHit>()
				.Include<DestroyOnDistanceTraveled>()
				.Build();

and Exclude it from the Enemy filter:

EnemyFilter = FilterBuilder
				.Include<Sprite>()
				.Include<Position>()
				.Include<CanMove>()
				.Include<CanDealDamage>()
				.Exclude<DestroyOnHit>()
				.Exclude<DestroyOnDistanceTraveled>()
				.Build();

and create a new message:

public readonly record struct Collide(Entity A, Entity B);

now create a new system, Collision.cs:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Messages;
using ShmupTutorial.Relations;

namespace ShmupTutorial.Systems;

public class Collision : MoonTools.ECS.System
{
    public Collision(World world) : base(world)
    {

    }

    public override void Update(TimeSpan delta)
    {
        foreach (var collision in ReadMessages<Collide>())
        {

            if (Has<DestroyOnHit>(collision.A))
                Set(collision.A, new MarkedForDestroy());


            if (Has<DestroyOnHit>(collision.B))
                Set(collision.B, new MarkedForDestroy());
        }
    }
}

this probably makes sense to you. read all the incoming Collide messages, check if either of the involved entities is destroyed on a collision, and if so, destroy it.

initialize in ProjectName.cs:

Collision Collision;

(...)

Collision = new Collision(World);

(...)

protected override void Update(GameTime gameTime)
{
	Time.Update(gameTime.ElapsedGameTime);
	Input.Update(gameTime.ElapsedGameTime);
	Player.Update(gameTime.ElapsedGameTime);
	Bullet.Update(gameTime.ElapsedGameTime);
	Motion.Update(gameTime.ElapsedGameTime);
	Collision.Update(gameTime.ElapsedGameTime);
	World.FinishUpdate();
	base.Update(gameTime);
}

to send these messages, go to our Motion system and update it:

var outX = CollisionTest(entity, deltaX);
var outY = CollisionTest(entity, deltaY);

foreach (var other in HitEntities)
{
    bool duplicate = false;
    foreach (var msg in ReadMessagesWithEntity<Collide>(other))
    {
        if (msg.B == entity)
        {
            duplicate = true;
            break;
        }
    }

    if (!duplicate)
        Send(entity, new Collide(entity, other));
}

we have to do a little bit of deduplication, because sometimes both entities motion will detect a collison, but we only want one message sent per pair of entities. we can leverage ReadMessagesWithEntity to make sure we never sent the same pair of entities twice.

much better!

but the bullets still don’t… do anything. you can shoot this guy forever and he won’t die.

viii. damage and health

we need a new component:

public readonly record struct CanTakeDamage(int HP);

and a new message:

public readonly record struct Damage();

now, in our Collision system:

foreach (var collision in ReadMessages<Collide>())
{
    if (Has<CanDealDamage>(collision.A) && Has<CanTakeDamage>(collision.B))
        Send(collision.B, new Damage());

    if (Has<CanDealDamage>(collision.B) && Has<CanTakeDamage>(collision.A))
        Send(collision.A, new Damage());

we need a new system to handle those Damage messages, so create a Health system:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Messages;

namespace ShmupTutorial.Systems;

public class Health : MoonTools.ECS.System
{
    public Filter DamageFilter;

    public Health(World world) : base(world)
    {
        DamageFilter = FilterBuilder
                        .Include<CanTakeDamage>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var entity in DamageFilter.Entities)
        {
            var hp = Get<CanTakeDamage>(entity).HP;
            foreach (var message in ReadMessagesWithEntity<Damage>(entity))
            {
                hp -= 1;
            }

            if (hp <= 0)
            {
                Set(entity, new MarkedForDestroy());
            }

            Set(entity, new CanTakeDamage(hp));
        }
    }
}

and meanwhile, in our Enemy system, add a new component to the spawning logic (and to the filter):

Set(enemy, new CanTakeDamage(5));

now we can destroy the squares! take that!

that was really fast. getting things started took a long time, but now that we have a scaffolding in place, it’s getting pretty quick to add new features.

ix. spawning ii: spawn harder

so this game isn’t very fun. the enemies don’t move around, and only one spawns at a time. also obviously they don’t do damage to the player.

first, let’s create a new component:

public readonly record struct DestroyWhenOffScreen();

we’ll need this so the enemies get cleaned up when they go offscreen.

let’s implement this in Motion, after the DestroyOnDistanceTraveled code:

if (Has<DestroyWhenOffScreen>(entity) && !Has<MarkedForDestroy>(entity))
{
	var pos = Get<Position>(entity).Value;
	var rect = new Rectangle((int)pos.X, (int)pos.Y, 1, 1);

	if (Has<Sprite>(entity))
	{
		var sprite = Get<Sprite>(entity).Rect;
		rect.Width = sprite.Width;
		rect.Height = sprite.Height;
		rect.X -= (int)(sprite.Width * 0.5f);
		rect.Y -= (int)(sprite.Height * 0.5f);
	}

	var screenRect = new Rectangle(0, 0, ShmupTutorial.RenderWidth, ShmupTutorial.RenderHeight);

	if (!screenRect.Intersects(rect))
		Set(entity, new MarkedForDestroy());
}

here we’re using the Intersects functionality of the built in FNA Rectangle class to check if the sprite rectangle is inside the screen rectangle. the only curious thing here is the bit where we subtract half the sprite width from rect.X and rect.Y, but that’s because FNA’s Rectangle has its origin in the top left, while our entities all have their origin in the center.

you can add DestroyWhenOffScreen to the bullets as well if you want, in addition to the DestroyWhenDistanceTraveled. there’s obviously no point in doing anything with a bullet that’s gone off screen.

anyway, let’s update our enemy spawning logic:

while (EnemyFilter.Count < 5) //CHANGED
{
	var enemy = CreateEntity();
	var sprite = Content.Textures.Enemy;
	Set(enemy, new Sprite(sprite, 0.5f));
	Set(enemy, new Position(new Vector2(Rando.Range(0f, ShmupTutorial.RenderWidth), -sprite.Height * 0.49f))); //CHANGED
	Set(enemy, new CanMove(64.0f));
	Set(enemy, new CanDealDamage());
	Set(enemy, new CanTakeDamage(2)); //CHANGED
	Set(enemy, new Direction(Vector2.UnitY)); //NEW
	Set(enemy, new DestroyWhenOffScreen()); //NEW

	var collider = CreateEntity();
	Set(collider, new AABB(0f, 0f, sprite.Width, sprite.Height));
	Set(collider, new Layer(CollisionLayer.EnemyActor, CollisionLayer.Enemy));
	Relate(enemy, collider, new HasCollider());
}

now we’re spawning the enemies off the top of the screen (but not so off screen that they’ll get cleaned up by the Motion system), and i changed the amount of health enemies have now that there’s more of them. the enemy now has a Direction (straight down) and our new DestroyWhenOffScreenComponent. also, instead of spawning one new enemy whenever one dies, it will spawn new enemies whenever there’s fewer than 5.

now this is looking more like a video game. not a particularly good video game, but a video game.

x. main menu

the time has come to add a main menu. well, a semblance of one. we need something to return to when the player dies. in order to add a menu, first we must address text storage and rendering.

you may recall me saying earlier that components in MoonTools.ECS must be unmanaged. this is where that becomes a problem. this means we can’t store a string.

that’s ok though: we can reinvent the concept of pointers from first principles and write a system to assign each string we want to store an ID number, and retreive the strings using that ID number. here’s what that looks like:

using System.Collections.Generic;

namespace ShmupTutorial.Data
{
    public static class TextStorage
    {
        static Dictionary<string, int> StringToID = new Dictionary<string, int>();
        static string[] IDToString = new string[256];
        static Stack<int> OpenIDs = new Stack<int>();
        static int NextID = 0;

        public static string GetString(int id)
        {
            return IDToString[id];
        }

        public static int GetID(string text)
        {
            if (!StringToID.ContainsKey(text))
            {
                RegisterString(text);
            }

            return StringToID[text];
        }

        static void RegisterString(string text)
        {
            if (OpenIDs.Count == 0)
            {
                if (NextID >= IDToString.Length)
                {
                    System.Array.Resize(ref IDToString, IDToString.Length * 2);
                }
                StringToID[text] = NextID;
                IDToString[NextID] = text;
                NextID += 1;
            }
            else
            {
                StringToID[text] = OpenIDs.Pop();
            }
        }
    }
}

this TextStorage class was originally written by evan hemsley for samurai gunn 2. it does a few fancy things for performance reasons, but it’s ultimately quite simple to use. when we call GetID with a string as the argument, it will return a number. when we call GetString with that number later, it will return the string.

now we need a new component to store text:

public readonly record struct Text(int ID);

now we can update our SpriteRenderer to also render text with a filter and font variable. feel free to use a different font if you’d like, this one is very ugly.

using FontStashSharp;

(...)

Filter TextFilter;
DynamicSpriteFont Font;

public SpriteRenderer(World world, SpriteBatch spriteBatch) : base(world)
{
    SpriteBatch = spriteBatch;
    SpriteFilter = FilterBuilder
        .Include<Position>()
        .Include<Sprite>()
        .Build();

    TextFilter = FilterBuilder
    .Include<Position>()
    .Include<Text>()
    .Build();

    Font = Content.Fonts.Opensans.GetFont(16);
}

and then, in our Draw method:

foreach (var entity in TextFilter.Entities)
{
    var position = Get<Position>(entity).Value;
    var text = TextStorage.GetString(Get<Text>(entity).ID);
    var size = Font.MeasureString(text);

    SpriteBatch.DrawString(
        Font,
        text,
        new Vector2((int)position.X, (int)position.Y),
        Color.White,
        null,
        0f,
        new Vector2(size.X * 0.5f, size.Y * 0.5f)
    );
}

this goes after the SpriteFilter loop but before the SpriteBatch.End call.

let’s create a couple new messages:

public readonly record struct StartGame();
public readonly record struct OpenMenu();

now let’s create a Menu system:

using System;
using Microsoft.Xna.Framework;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Data;
using ShmupTutorial.Messages;

namespace ShmupTutorial.Systems;

public class Menu : MoonTools.ECS.System
{

    Filter MenuFilter;
    public Menu(World world) : base(world)
    {
        MenuFilter = FilterBuilder.Include<Text>().Build();
    }

    public override void Update(TimeSpan delta)
    {
        if (SomeMessage<OpenMenu>())
        {
            var prompt = CreateEntity();
            Set(prompt, new Text(TextStorage.GetID("press shoot to start")));
            Set(prompt, new Position(new Vector2(ShmupTutorial.RenderWidth * 0.5f, ShmupTutorial.RenderHeight * 0.5f)));
        }

        foreach (var message in ReadMessages<InputAction>())
        {
            if (
            !Some<CanBeControlled>()
            && message.Action == Actions.Shoot
            && message.State == ActionState.Pressed
            )
            {
                Send(new StartGame());
                foreach (var entity in MenuFilter.Entities)
                    Set(entity, new MarkedForDestroy());
            }
        }
    }
}

the idea here is that whenever this sees an OpenMenu message, it’ll open the menu, which consists of one line of text (“press shoot to start”). when the menu sees an InputMessage that corresponds to Shoot, it’ll start the game. we also check the State to make sure it’s Pressed and not Held so that in the (likely) case you are holding Shoot when you die, you don’t get immediatley launched back into another game.

now, in the Player system, replace

if(!Some<CanBeControlled>())

with

if (SomeMessage<StartGame>())

and in ProjectName.cs put

World.Send(new OpenMenu());

at the bottom of LoadContent, after all the bounds get created but before base.LoadContent() is called.

we still need that null check, though, so move it to after the if (SomeMessage<StartGame>()) block:

}

if (!Some<CanBeControlled>())
    return;

var player = GetSingletonEntity<CanBeControlled>();

if you run the game now, you should see some text, and then be able to push space and get into the game.

xi. player damage and death

ok, let’s finally put a CanTakeDamage component on the player:

Set(player, new CanTakeDamage(3));

now, in our Destroyer add the following:

foreach (var entity in DestroyFilter.Entities)
{
    foreach (var collider in OutRelations<HasCollider>(entity))
        Destroy(collider);

    if (Has<CanBeControlled>(entity)) //NEW
        Send(new OpenMenu()); //NEW

    Destroy(entity);
}

this will automatically open the menu as soon as the player destroyed.

also, in the Enemy system:

public override void Update(TimeSpan delta)
{
    if (SomeMessage<StartGame>())
    {
        foreach (var enemy in EnemyFilter.Entities)
        {
            Set(enemy, new MarkedForDestroy());
        }
    }

    while (Some<CanBeControlled>() && EnemyFilter.Count < 5)
    {

when the player starts the game again, all existing entities will be destroyed, and no new entities will be spawned if there isn’t a player. this is why we changed the player filter’s access modifier, by the way.

if you run the game now, you may immediately notice a problem:

we have 3 hp, but we seem to die immediately. this is because there’s no I-frames, so the enemy just does damage to us every frame until we die. we can solve this with a new component:

public readonly record struct BecomeInvincibleOnDamage(float Time);

Set(player, new BecomeInvincibleOnDamage(1f));

and a new relation:

public readonly record struct Invincible();

now, in the Health system:

foreach (var entity in DamageFilter.Entities)
{
    if (HasInRelation<Invincible>(entity))
    {
        continue;
    }

    var hp = Get<CanTakeDamage>(entity).HP;
    foreach (var message in ReadMessagesWithEntity<Damage>(entity))
    {
        hp -= 1;

        if (Has<BecomeInvincibleOnDamage>(entity))
        {
            var timer = CreateEntity();
            Set(timer, new Timer(Get<BecomeInvincibleOnDamage>(entity).Time));
            Relate(timer, entity, new Invincible());
        }
    }

    if (hp <= 0)
    {
        Set(entity, new MarkedForDestroy());
    }

    Set(entity, new CanTakeDamage(hp));


}

we can use the Time system we created earlier plus our new Invincible relation to make it so an entity can be invincible for a period of time.

if you run the game now, it works a bit better:

it’s still not right though. in most shmups, once you hit an enemy, you can’t collide with enemies for the period of your invincibility.

this can be solved pretty easily in the Player system:

if (HasInRelation<Invincible>(player))
{
    var collider = OutRelationSingleton<HasCollider>(player);
    var aabb = Get<AABB>(collider);
    Set(collider, new Layer(CollisionLayer.Pickup | CollisionLayer.Level));
}
else
{
    var collider = OutRelationSingleton<HasCollider>(player);
    var aabb = Get<AABB>(collider);
    Set(collider, new Layer(CollisionLayer.PlayerActor));
}

we only want to collide with powerups (which we haven’t added yet) and the level bounds while we’re invincible, so let’s make those the only layers the player is on.

xii. scoring and HUD

there’s a few more basics we need to add.

first, there’s no way for us to keep track of how well we’re doing. it would also be nice to have a HUD that indicates how many lives you have.

scoring

we need a new component:

public readonly record struct Score(int Current, int High);

and a new message:

public readonly record struct AddScore(int Add);

now we can use these in a new system, Score:

using System;
using System.ComponentModel;
using Microsoft.Xna.Framework;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Data;
using ShmupTutorial.Messages;

namespace ShmupTutorial.Systems;

public class Score : MoonTools.ECS.System
{
    public Score(World world) : base(world)
    {
    }

    public override void Update(TimeSpan delta)
    {
        if (!Some<Components.Score>())
        {
            var entity = CreateEntity();
            Set(entity, new Components.Score(0, 0));
            Set(entity, new Text(TextStorage.GetID("0 (best: 0)")));
            Set(entity, new Position(new Vector2(ShmupTutorial.RenderWidth * 0.5f, 8f)));
            return;
        }

        var scoreEntity = GetSingletonEntity<Components.Score>();
        var score = Get<Components.Score>(scoreEntity);

        if (SomeMessage<StartGame>())
            Set(scoreEntity, new Components.Score(0, score.High));

        foreach (var msg in ReadMessages<AddScore>())
        {
            var s = score.Current + msg.Add;
            if (s > score.High)
                Set(scoreEntity, new Components.Score(s, s));
            else
                Set(scoreEntity, new Components.Score(s, score.High));
        }

        Set(scoreEntity, new Text(TextStorage.GetID(string.Format("{0} (best: {1})", score.Current, score.High))));
    }
}

first, we create the Score entity if it doesn’t exist, which includes the Textcomponent.

then, if the player has started the game, we have to reset the Current field but not the High field.

and finally, we go through all the AddScore messages and add them to the Score component. if the new Current score is better than the High score, we overwrite the High score.

we can use this system by sending messages from the Health system:

if (hp <= 0)
{
    Set(entity, new MarkedForDestroy());

    if (!Has<CanBeControlled>(entity))
        Send(new AddScore(1));
}

if it’s not the player and it dies, add to the score.

don’t forget to set it up in ProjectName.cs:

Systems.Score Score;

(...)

Score = new Systems.Score(World);

protected override void Update(GameTime gameTime)
{
    Destroyer.Update(gameTime.ElapsedGameTime);
    Time.Update(gameTime.ElapsedGameTime);
    Input.Update(gameTime.ElapsedGameTime);
    Menu.Update(gameTime.ElapsedGameTime);
    Player.Update(gameTime.ElapsedGameTime);
    Enemy.Update(gameTime.ElapsedGameTime);
    Bullet.Update(gameTime.ElapsedGameTime);
    Motion.Update(gameTime.ElapsedGameTime);
    Collision.Update(gameTime.ElapsedGameTime);
    Health.Update(gameTime.ElapsedGameTime);
    Score.Update(gameTime.ElapsedGameTime);
    World.FinishUpdate();
    base.Update(gameTime);
}

and in Menu.cs, we need to make a small adjustment to our MenuFilter:

Filter MenuFilter;
public Menu(World world) : base(world)
{
    MenuFilter = FilterBuilder
    .Include<Text>()
    .Exclude<Components.Score>()
    .Build();
}

lives

rather than a simple number, let’s make a more traditional life display that uses sprites to show you how many lives you have. this is trickier than it sounds, because unlike everything else we’ve seen so far, the lives have an order. when we remove lives, we need to always remove the last life, instead of the life in the middle or something.

there are lots of ways of doing this in ECS, but one of the most flexible is to use entity relations to create a linked list.

i want to take a moment to emphasize a point here: in general, when using ECS, if you can find a way to store a data structure in the ECS itself, you will almost certainly benefit from it. we could store the lives in an array or list outside the ECS, but storing them in the ECS is almost certainly better.

first, create a new relation:

public readonly record struct HasLife();

now, in our Player system:

int StartingHealth = 3;

(...)

if (SomeMessage<StartGame>())
{
    var entity = CreateEntity();
    var sprite = Content.Textures.Player;

    var collider = CreateEntity();
    Set(collider, new AABB(0f, 0f, 8f, 8f));
    Set(collider, new Layer(CollisionLayer.PlayerActor));

    Set(entity, new Sprite(sprite, 0.0f));
    Set(entity, new Position(new Vector2(ShmupTutorial.RenderWidth * 0.5f, ShmupTutorial.RenderHeight * 0.5f)));
    Set(entity, new CanBeControlled());
    Set(entity, new CanMove(128.0f));
    Set(entity, new CanShoot(0.1f));
    Set(entity, new CanTakeDamage(StartingHealth));
    Set(entity, new BecomeInvincibleOnDamage(1f));
    Relate(entity, collider, new HasCollider());

    //NEW
    var prev = entity;
    for (int i = 0; i < StartingHealth; i++)
    {
        var next = CreateEntity();
        Set(next, new Sprite(sprite, 0.0f));
        Set(next, new Position(
            new Vector2((i + 1) * (sprite.Width + 2.0f), ShmupTutorial.RenderHeight - sprite.Height)
        ));
        Relate(prev, next, new HasLife());
        prev = next;
    }
}

this is going to create one new sprite for each health we have. they’re being positioned in the bottom left of the screen with a margin between sprites of 2. i’ve also moved the health to a configuration variable at the top of the class. each life is related to the previous life by the HasLife relation.

now, in the HealthSystem

foreach (var message in ReadMessagesWithEntity<Damage>(entity))
{
    hp -= 1;

    if (Has<BecomeInvincibleOnDamage>(entity))
    {
        var timer = CreateEntity();
        var invincible = Get<BecomeInvincibleOnDamage>(entity);
        Set(timer, new Timer(invincible.Time));
        Relate(timer, entity, new Invincible());
    }

    //NEW
    if (Has<CanBeControlled>(entity))
    {
        var life = entity;
        while (HasOutRelation<HasLife>(life))
        {
            life = OutRelationSingleton<HasLife>(life);
        }
        if (!Has<CanBeControlled>(life))
            Destroy(life);
    }
}

now, we can walk through the linked list by starting at the player and continuing until we find a sprite that has no HasLife out relation. once we do this, we can destroy it.

xiv. polish and visual effects

our game has a technically complete loop now, but it’s missing a lot. the game doesn’t feel very good to play, and there’s a lot of information it doesn’t convey. for instance, it’s hard to tell when you’re invincible. shmups usually communicate this by making the player sprite flicker. also, there’s no feedback when you deal damage. we can solve this with flicker as well. it would also be nice if there were some particles that spawned when we hit things and when enemies were destroyed. another common “game feel” element in action games is screen shake. we can shake the screen when you hit and destroy enemies to add impact to those moments.

in this section, we’ll explore how we can use some of the techniques we’ve already seen to add polish and flair to our project.

flicker

flicker is fairly straightforward, and should be easy with our timer system. we really need two timers here: one that times how long the flicker effect will last, and one that times how long each individual flicker will be. be careful with flicker effects, very fast flickers and flickers that take up a large portion of the screen can cause headaches, eyestrain, and seizures for some people.

create two new relations:

public readonly record struct Flickering(float Time);
public readonly record struct Flicker();

a new message:

public readonly record struct StartFlickering(float TotalTime, float FlickerTime);

a new component:

public readonly record struct Invisible();

and finally a new system, Flicker.cs:

using System;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Messages;
using ShmupTutorial.Relations;

namespace ShmupTutorial.Systems;

public class Flicker : MoonTools.ECS.System
{
    public Filter SpriteFilter;

    public Flicker(World world) : base(world)
    {
        SpriteFilter = FilterBuilder
                        .Include<Sprite>()
                        .Include<Position>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var entity in SpriteFilter.Entities)
        {
            if (HasOutRelation<Flickering>(entity))
            {
                var flickeringTimerEntity = OutRelationSingleton<Flickering>(entity);
                var flickeringTimer = Get<Timer>(flickeringTimerEntity);
                var flickering = GetRelationData<Flickering>(entity, flickeringTimerEntity);

                if (SomeMessageWithEntity<StartFlickering>(entity))
                {
                    var msg = ReadMessageWithEntity<StartFlickering>(entity);
                    Set(flickeringTimerEntity, new Timer(flickeringTimer.Time + msg.TotalTime));
                    Relate(entity, flickeringTimerEntity, new Flickering());
                }

                if (HasOutRelation<Relations.Flicker>(entity))
                {
                    var timer = OutRelationSingleton<Relations.Flicker>(entity);
                    var time = Get<Timer>(timer);
                    if (time.Time > time.Max * 0.5f)
                        Set(entity, new Invisible());
                    else
                        Remove<Invisible>(entity);
                }
                else
                {
                    var timer = CreateEntity();
                    Set(timer, new Timer(flickering.Time));
                    Relate(entity, timer, new Relations.Flicker());
                }
            }
            else if (SomeMessageWithEntity<StartFlickering>(entity))
            {
                var flickering = ReadMessageWithEntity<StartFlickering>(entity);
                var timer = CreateEntity();
                Set(timer, new Timer(flickering.TotalTime));
                Relate(entity, timer, new Flickering(flickering.FlickerTime));
            }
            else
            {
                Remove<Invisible>(entity);
            }
        }
    }
}

this might take a second to wrap your head around. Flickering is the timer that determines how long the flickering effect will last. Flicker (which we have to specify as Relations.Flicker for disambiguation purposes) is the timer for each individual on/off cycle of the flickering effect. if the entity has a Flickering timer on it, we first check and see if new StartFlickering messages have come in. if they have, we add their time to the total flicker time and change the flickering rate to the new rate.

if the entity has a Flicker timer we check if the timer is in the top half or the bottom half of the total cycle time. if it’s in the top half, we set it to be Invisible, otherwise we remove the Invisible. if the entity’s Flicker timer has run out but it’s still Flickering, we create a new Flicker timer.

finally, we handle the case of starting a flicker for an entity that is not currently flickering, which is just creating and attaching a timer. we also handle the case of no flickering and make sure to Remove the Invisible component.

we need to update the SpriteRenderer to use our Invisible component, but this is easy:

foreach (var entity in SpriteFilter.Entities)
{
    if (Has<Invisible>(entity))
        continue;

just skip the rendering if the entity is invisible.

and now we can put some StartFlickering messages in the Health system:

foreach (var message in ReadMessagesWithEntity<Damage>(entity))
{
    hp -= 1;

    if (Has<BecomeInvincibleOnDamage>(entity))
    {
        var timer = CreateEntity();
        var invincible = Get<BecomeInvincibleOnDamage>(entity);
        Set(timer, new Timer(invincible.Time));
        Relate(timer, entity, new Invincible());
        Send(entity, new StartFlickering(invincible.Time, 0.1f));
    }
    else
    {
        Send(entity, new StartFlickering(0.1f, 4.0f / 60.0f));
    }
}

we want the player to flicker for as long as they’re invincible. the enemies should flicker for a shorter time, and faster, because they don’t get i-frames.

don’t forget to add the system to ProjectName.cs:

Systems.Flicker Flicker;

(...)

Flicker = new Systems.Flicker(World);

(...)

protected override void Update(GameTime gameTime)
{
    Destroyer.Update(gameTime.ElapsedGameTime);
    Time.Update(gameTime.ElapsedGameTime);
    Input.Update(gameTime.ElapsedGameTime);
    Menu.Update(gameTime.ElapsedGameTime);
    Player.Update(gameTime.ElapsedGameTime);
    Enemy.Update(gameTime.ElapsedGameTime);
    Bullet.Update(gameTime.ElapsedGameTime);
    Motion.Update(gameTime.ElapsedGameTime);
    Collision.Update(gameTime.ElapsedGameTime);
    Health.Update(gameTime.ElapsedGameTime);
    Flicker.Update(gameTime.ElapsedGameTime);
    World.FinishUpdate();
    base.Update(gameTime);
}

particles

“particles” is the visual effects term of art for an effect that relies on spawning large numbers of small objects and animating them. lots of game engines have particle systems, as do many visual effects programs like adobe after effects. particles are a great way to add some polish and make your game feel better to play. it doesn’t make sense that when we destroy enemies they just disappear! we want them to explode into tiny pieces.

in actor model engines you often have to do all manner of tricks to make spawning large numbers of particles performant. in ECS, you can just spawn them like any other entity, no special tricks required. this makes particles much easier to work with.

we’re going to be just spawning a clump of particles and evolving them based on some parameters. you can also use particles for continuous effects, like smoke and fire, the foam at the base of a waterfall, or all manner of magical or sci-fi sparkles emanating from powerful objects.

the first thing we need to do is create the most complicated message yet:

public readonly record struct SpawnParticles(
    Rectangle Sprite,
    Vector2 Position,
    int MinParticles,
    int MaxParticles,
    float MinVelocity = 1.0f,
    float MaxVelocity = 1.0f,
    float MinLifetime = 1.0f,
    float MaxLifetime = 1.0f,
    float MinStartSize = 1.0f,
    float MaxStartSize = 1.0f,
    float MinEndSize = 1.0f,
    float MaxEndSize = 1.0f
    );

you generally don’t want particles to just stick around, you want them to do stuff. we therefore need a lot of parameters to set how the particles are going to evolve over time. our particles are going to be spawned as a single group and then evolve from there, so we can just send a message to the Particles system.

we also need a component:

public readonly record struct ChangeSize(
    float StartSize,
    float EndSize
);

now let’s use these in a Particle system:

using System;
using Microsoft.Xna.Framework;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Messages;
using ShmupTutorial.Utility;

namespace ShmupTutorial.Systems;

public class Particles : MoonTools.ECS.System
{
    public Filter ChangeSizeFilter;

    public Particles(World world) : base(world)
    {
        ChangeSizeFilter = FilterBuilder
                        .Include<Timer>()
                        .Include<ChangeSize>()
                        .Build();
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var message in ReadMessages<SpawnParticles>())
        {
            var numParticles = Rando.IntInclusive(message.MinParticles, message.MaxParticles);
            for (int i = 0; i < numParticles; i++)
            {
                var lifetime = Rando.Range(message.MinLifetime, message.MaxLifetime);
                var startSize = Rando.Range(message.MinStartSize, message.MaxStartSize);
                var particle = CreateEntity();
                Set(particle, new ChangeSize(
                    startSize,
                    Rando.Range(message.MinEndSize, message.MaxEndSize)
                ));
                Set(particle, new CanMove(Rando.Range(message.MinVelocity, message.MaxVelocity)));
                Set(particle, new Direction(Rando.OnUnitCircle()));
                Set(particle, new Timer(lifetime));
                Set(particle, new Sprite(message.Sprite, 1.0f));
                Set(particle, new Scale(Vector2.One * startSize));
                Set(particle, new Position(message.Position));
            }
        }

        foreach (var entity in ChangeSizeFilter.Entities)
        {
            var size = Get<ChangeSize>(entity);
            var timer = Get<Timer>(entity);
            var t = 1.0f - timer.Remaining;
            Set(entity, new Scale(Vector2.One * MathHelper.Lerp(size.StartSize, size.EndSize, t)));
        }
    }
}

this file is long but it’s not doing a ton. this pattern should be familiar to you. one small thing is that we’re attaching a Timer directly to the particle rather than using a relationship. Timers are destroyed at the end of their life anyway, which is exactly the behavior we want. besides that, almost everything can be done with components we already have.

we also see heavy use of my Rando class, including the Rando.OnUnitCircle method. you can’t just generate random X and Y coordintes between 0 and 1, because that won’t form a cirlce, and you can’t just normalize that because the distribution won’t be uniform. you have to generate polar coordinates and then convert to cartesian to get a uniform distribution around a circle or sphere. check the implementation in the Rando class for the details.

the last bit is animating the size change. we want the particles to shrink as their lifetime ticks down, so they don’t just blink out of existence. it looks nice. this is where we finally use that Remaining property we built ages ago.

you can experiment with using other interpolation functions besides Lerp. see a bunch of examples at easings.net, and there’s a moontools library that implements all of those called MoonTools.Easing.

now, if you can spawn some particles when entities are killed in the Health system:

if (hp <= 0)
{
    Set(entity, new MarkedForDestroy());

    var sprite = Get<Sprite>(entity).Rect;
    var position = Get<Position>(entity).Value;
    Send(new SpawnParticles(
        sprite,
        position,
        5, 10,
        8.0f, 256.0f,
        0.1f, 2.0f,
        0.3f, 0.5f,
        0f, 0.2f
    ));

screen shake

for this, let’s start by moving our render target shenanigans into the SpriteRenderer:

RenderTarget2D RenderTarget;
GraphicsDevice GraphicsDevice;
GameWindow Window;


public SpriteRenderer(World world,
    SpriteBatch spriteBatch,
    GraphicsDevice graphicsDevice,
    RenderTarget2D renderTarget,
    GameWindow window
) : base(world)
{
    SpriteBatch = spriteBatch;
    SpriteFilter = FilterBuilder
        .Include<Position>()
        .Include<Sprite>()
        .Build();

    TextFilter = FilterBuilder
    .Include<Position>()
    .Include<Text>()
    .Build();

    RenderTarget = renderTarget;
    GraphicsDevice = graphicsDevice;
    Window = window;

    Font = Content.Fonts.Opensans.GetFont(16);
}

public void Draw()
{
    GraphicsDevice.SetRenderTarget(RenderTarget);

    GraphicsDevice.Clear(Color.Black);

    SpriteBatch.Begin(
        SpriteSortMode.BackToFront,
        BlendState.AlphaBlend,
        SamplerState.PointClamp,
        DepthStencilState.None,
        RasterizerState.CullCounterClockwise
    );

//(drawing code...)

    SpriteBatch.End();

    GraphicsDevice.SetRenderTarget(null);
    GraphicsDevice.Clear(Color.Black);
    SpriteBatch.Begin(
        SpriteSortMode.Deferred,
        BlendState.Opaque,
        SamplerState.PointClamp,
        DepthStencilState.None,
        RasterizerState.CullCounterClockwise
    );

    var height = Window.ClientBounds.Height;
    height -= height % ShmupTutorial.RenderHeight;
    var width = (int)MathF.Floor(height * ShmupTutorial.AspectRatio);
    var wDiff = Window.ClientBounds.Width - width;
    var hDiff = Window.ClientBounds.Height - height;

    SpriteBatch.Draw(
        RenderTarget,
        new Rectangle(
            (int)MathF.Floor(wDiff * 0.5f),
            (int)MathF.Floor(hDiff * 0.5f),
            width,
            height),
        null,
        Color.White
    );
    SpriteBatch.End();

now we dependency inject all the graphics objects, so update the constructor in ProjectName.cs:

SpriteRenderer = new SpriteRenderer(World, SpriteBatch, GraphicsDevice, RenderTarget, Window);

now let’s create a new component:

public readonly record struct ShakeScreen(float Magnitude);

now, in our renderer:

Filter ShakeFilter;

(...)


ShakeFilter = FilterBuilder
.Include<ShakeScreen>()
.Include<Timer>()
.Build();

(...)

var shake = 0.0f;
foreach (var screenshake in ShakeFilter.Entities)
{
    var timer = Get<Timer>(screenshake);
    var shaker = Get<ShakeScreen>(screenshake);
    shake += shaker.Magnitude * (timer.Time / timer.Max);
}



var shakeDirection = Rando.InsideUnitSphere() * shake;

SpriteBatch.Draw(
    RenderTarget,
    new Rectangle(
        (int)(MathF.Floor(wDiff * 0.5f) + shakeDirection.X),
        (int)(MathF.Floor(hDiff * 0.5f) + shakeDirection.Y),
        width,
        height),
    null,
    Color.White
);

this will sum the magnitude of all the shake events currently happening and calculate shake based on all of them. we multiply by the linear interpolation factor we calculated before to have the shakes decrease in severity as the shake goes on.

now let’s add some shake to the Health system:

if (Has<CanBeControlled>(entity))
{
    var life = entity;
    while (HasOutRelation<HasLife>(life))
    {
        life = OutRelationSingleton<HasLife>(life);
    }
    if (!Has<CanBeControlled>(life))
    {
        Destroy(life);
    }

    var shaker = CreateEntity();
    Set(shaker, new ShakeScreen(4.0f));
    Set(shaker, new Timer(0.3f));
}

(...)

if (hp <= 0)
{
    Set(entity, new MarkedForDestroy());

    var sprite = Get<Sprite>(entity).Rect;
    var position = Get<Position>(entity).Value;
    Send(new SpawnParticles(
        sprite,
        position,
        5, 10,
        8.0f, 256.0f,
        0.1f, 2.0f,
        0.3f, 0.5f,
        0f, 0.2f
    ));

    if (!Has<CanBeControlled>(entity))
    {
        Send(new AddScore(1));
        var shaker = CreateEntity();
        Set(shaker, new ShakeScreen(4.0f));
        Set(shaker, new Timer(0.1f));
    }
    else
    {
        var shaker = CreateEntity();
        Set(shaker, new ShakeScreen(8.0f));
        Set(shaker, new Timer(0.5f));
    }
}

xv. sound

you can probably figure this one out on your own at this point, but i figured i’d cover how to incorporate sound effects into your game.

in the assets pack, i included a few sound effects, so they should be in your Content.cs folder.

sound effects are classes so we can’t just store them in messages and components. time to create a new storage class.

using System.Collections.Generic;
using Microsoft.Xna.Framework.Audio;

namespace ShmupTutorial.Data
{
    public static class SoundStorage
    {
        static Dictionary<SoundEffect, int> SoundEffectToID = new Dictionary<SoundEffect, int>();
        static SoundEffect[] IDToSoundEffect = new SoundEffect[256];
        static Stack<int> OpenIDs = new Stack<int>();
        static int NextID = 0;

        public static SoundEffect GetSoundEffect(int id)
        {
            return IDToSoundEffect[id];
        }

        public static int GetID(SoundEffect text)
        {
            if (!SoundEffectToID.ContainsKey(text))
            {
                RegisterSoundEffect(text);
            }

            return SoundEffectToID[text];
        }

        private static void RegisterSoundEffect(SoundEffect text)
        {
            if (OpenIDs.Count == 0)
            {
                if (NextID >= IDToSoundEffect.Length)
                {
                    System.Array.Resize(ref IDToSoundEffect, IDToSoundEffect.Length * 2);
                }
                SoundEffectToID[text] = NextID;
                IDToSoundEffect[NextID] = text;
                NextID += 1;
            }
            else
            {
                SoundEffectToID[text] = OpenIDs.Pop();
            }
        }
    }
}

note that this is literally the same class as TextStorage.cs but with string replaced by SoundEffect.

now we need a new message:

public readonly record struct PlaySound(int ID);

and a system to process them:

using System;
using System.Numerics;
using MoonTools.ECS;
using ShmupTutorial.Components;
using ShmupTutorial.Data;
using ShmupTutorial.Messages;
using ShmupTutorial.Relations;

namespace ShmupTutorial.Systems;

public class Sound : MoonTools.ECS.System
{
    public Sound(World world) : base(world)
    {
    }

    public override void Update(TimeSpan delta)
    {
        foreach (var message in ReadMessages<PlaySound>())
        {
            var sound = SoundStorage.GetSoundEffect(message.ID);
            sound.Play();
        }
    }
}

now we can send these messages in various places, like whenever a bullet is shot in the Bullet system:

if (Has<CanShoot>(message.Source) && !HasInRelation<DisableShoot>(message.Source))
{
    Send(new PlaySound(SoundStorage.GetID(Content.SFX.Shoot)));

when the player takes damage in the Health system:

if (Has<CanBeControlled>(entity))
{
    if (hp > 0)
        Send(new PlaySound(SoundStorage.GetID(Content.SFX.Hit)));

and similarly when the player or enemy dies:

if (!Has<CanBeControlled>(entity))
{
    Send(new PlaySound(SoundStorage.GetID(SFX.Enemydeath)));
    Send(new AddScore(1));
    var shaker = CreateEntity();
    Set(shaker, new ShakeScreen(4.0f));
    Set(shaker, new Timer(0.1f));
}
else
{
    Send(new PlaySound(SoundStorage.GetID(SFX.Death)));
    var shaker = CreateEntity();
    Set(shaker, new ShakeScreen(8.0f));
    Set(shaker, new Timer(0.5f));
}

if you run the game now, there will be sound! it might be loud, so be careful to turn your volume down before you make any noises.

i made all these sounds with bfxr, a free sound effects generator. make some of your own and fill your games with sound!

xvi: conclusion

so that’s the whole game. it’s still not very good! for one, the art is terrible (i’ll take responsibility for that). but there’s not a lot going on. if you want, try to imagine improvements you could make and see if you can implement them. i hope to do a follow-up to this tutorial to cover some more things you could add to this game: more types of enemies, enemies that shoot bullets, boss fights, and more.

there’s also lots more i didn’t cover, in particular user interface things. in the near future i am planning a tutorial similar to this one where we make a visual novel, and in that tutorial i will dive deep into how to make a pleasing user interface, as well as how to handle things like mouse input.

and, once again, if you find this tutorial valuable, i have a patreon and a ko-fi. your support is much appreciated.