Breakout: Loading Levels

In our editor project, we serialized data using the format provided below. We have three one-byte integers, representing the serialization version, width of the grid, and height of the grid respectively.

We then have a 4-byte integer, which lets us know how many actors (or entities) are in the level. We then have the data for those actors. The amount of actor data is unknown in advance - it depends on the number of actors and the type of those actors.

All multi-byte values use the little-endian (LE) order:

Let's expand our Load() function to load the serialized data. The following code assumes that the levels created by our level editor are stored in an "Assets/" directory alongside our executable, with file names like "Level1.bin".

We'll use SDL_ReadU8 and SDL_ReadU32LE to read the header values. In SDL3, these functions take a pointer to the variable where the data should be stored and return a boolean indicating success or failure.

1// ...
2#include <format> 
3#include <iostream> // for std::cerr
4
5void BreakoutScene::Load(int Level) {
6  // ...
7
8  std::string FileName{Config::BASE_PATH +
9    std::format("Assets/Level{}.bin", Level)
10  };
11  SDL_IOStream* Handle{
12    SDL_IOFromFile(FileName.c_str(), "rb")
13  };
14  if (!Handle) {
15    CheckSDLError("Loading Level");
16    return;
17  }
18
19  Uint8 FileVersion{0};
20  SDL_ReadU8(Handle, &FileVersion);
21
22  Uint8 GridWidth{0};
23  SDL_ReadU8(Handle, &GridWidth);
24
25  Uint8 GridHeight{0};
26  SDL_ReadU8(Handle, &GridHeight);
27
28  Uint32 BlockCount{0};
29  SDL_ReadU32LE(Handle, &BlockCount);
30
31  std::cout << std::format(
32    "Loading a version "
33    "{} level ({}x{}) with {} blocks\n",
34    FileVersion, GridWidth, GridHeight,
35    BlockCount
36  );
37}

1Loading a version 1 level (13x6) with 55 blocks

Now that we've deserialized the fixed-size level data, let's work on deserializing the dynamic array of entities. Each actor in the array starts with a type, row, and column integer, each being a single byte. They then have a variable amount of additional data, depending on their type.

The following diagram shows an example where we have two actors in the array, but this pattern repeats for however many blocks are in the level, as represented by the BlockCount integer.

Most of our blocks have no additional data beyond their type, row, and column. However, in our editor project, we serialized some additional data from our green blocks as a proof of concept. We'll handle that additional data a bit later in this section.

Adding a Block Class

In our editor project, each block type was a different class. We could do the same here, but we don't need to.

We can get a lot of diverse behavior from the same object type, simply by changing which components that object has, and how those components are configured.

Let's create a Block type that all of our deserialized entities will use. Our constructor will accept the SDL_IOStream handle, and will start by grabbing the Type, Row, and Column values (in that order) from it:

1#pragma once
2#include <format>
3#include <iostream>
4#include <SDL3/SDL.h>
5#include "Engine/ECS/Entity.h"
6
7class Block : public Entity {
8 public:
9  Block(SDL_IOStream* Handle, BreakoutScene& Scene)
10  : Entity{Scene}
11  {
12    Uint8 Type{0};
13    SDL_ReadU8(Handle, &Type);
14    Uint8 GridRow{0};
15    SDL_ReadU8(Handle, &GridRow);
16    Uint8 GridCol{0};
17    SDL_ReadU8(Handle, &GridCol);
18
19    std::cout << std::format(
20      "Loaded type {} block (Row={}, Col={})\n",
21      Type, GridRow, GridCol
22    );
23  }
24};

Handling Additional Data

Beyond using data from the SDL_IOStream stream, our Block constructor additionally needs to advance the read/write offset within that stream such that, for the next block, the offset is at the start of that block's data.

Reading data using functions like SDL_ReadU8() automatically advances the offset. Therefore, as long as each invocation of the constructor is reading all the entity's data, the next block's constructor will be handed a stream whose offset is in the correct position - right at the start of the entity that the constructor is responsible for deserializing.

We are reading all the data for most of our block types but, in our editor project, we had our green blocks serialize some additional data, just to show how it could be done.

Our green block's serialization function is additionally saving a 16-bit integer, a second 32-bit integer representing the size of an array, and then that quantity of 32-bit integers. The code in our Editor to make that happen is shown below for reference:

1// ...
2
3void GreenBlock::Serialize(SDL_IOStream* Handle) const {
4  Actor::Serialize(Handle);
5  SDL_WriteU16LE(Handle, SomeNumber);
6  SDL_WriteU32LE(Handle, Uint32(SomeArray.size()));
7  for (Sint32 Num : SomeArray) {
8    SDL_WriteU32LE(Handle, Num);
9  }
10}
11
12// ...

We're not currently using that additional data in our block constructor so, when dealing with a green block, our byte offset is left in the wrong position. This means that every entity that we load after the green block will not be deserialized correctly.

When we encounter a green block, we should read all of those elements too. This ensures that, by the end of the constructor, the byte offset in our stream has advanced to the end of the object we're supposed to be deserializing.

When our constructor is dealing with a green block, the deserialized Type will have a value of 2. However, in our editor project, we added an ActorType enum in our config file which lets us map those type integers to more descriptive names. As such, we can cast that Type integer to an ActorType, and then check if it is equal to ActorType::GreenBlock.

We don't really need this additional green block data for our game, but let's log it out to confirm it's working:

1// ...
2#include "Config.h"
3
4class Block : public Entity {
5 public:
6  Block(SDL_IOStream* Handle, BreakoutScene& Scene)
7  : Entity{Scene}
8  {
Previous Code (Unchanged)|Show
20
21    if (
22      static_cast<Config::ActorType>(Type) ==
23      Config::ActorType::GreenBlock
24    ) {
25      std::cout << "  Green Block Data: ";
26      Uint16 SomeNumber{0};
27      SDL_ReadU16LE(Handle, &SomeNumber);
28      std::cout << SomeNumber << ", [";
29
30      Uint32 ArraySize{0};
31      SDL_ReadU32LE(Handle, &ArraySize);
32      for (size_t i{0}; i < ArraySize; ++i) {
33        Uint32 ArrayValue{0};
34        SDL_ReadU32LE(Handle, &ArrayValue);
35        std::cout << ArrayValue
36          << (i < ArraySize - 1 ? ", " : "");
37      }
38      std::cout << "]\n";
39    }
40  }
41};

Loading Actors

Now that we have our Block class and constructor set up, let's use it back in our BreakoutScene's Load() function to create all the entities we need:

1// ...
2#include "Breakout/Block.h"
3
4void BreakoutScene::Load(int Level) {
Previous Code (Unchanged)|Show
49
50  for (size_t i{0}; i < BlockCount; ++i) {
51    Entities.emplace_back(
52      std::make_unique<Block>(Handle, *this)
53    );
54  }
55
56  SDL_CloseIO(Handle);
57}

We should see our block data being loaded in our terminal output:

1Loaded type 4 block (Row=4, Col=3)
2Loaded type 1 block (Row=4, Col=2)
3Loaded type 3 block (Row=4, Col=1)
4Loaded type 2 block (Row=3, Col=2)
5  Green Block Data: 32, [1, 2, 3]
6Loaded type 5 block (Row=3, Col=3)

Seeking

In this section, we read our additional green block data to ensure our read/write offset was updated to the correct position. But there is an alternative approach: we could just update our byte offset directly.

If we don't need to read the additional data, we can instead just directly advance (or "seek") our read/write offset to the end of our current object.

To do this, we need to calculate how many bytes we need to seek forward, and then call SDL_SeekIO(). To use SDL_SeekIO(), we pass three arguments:

1. The SDL_IOStream handle
2. The offset we want to seek by
3. How we want that offset to be used. SDL_IO_SEEK_CUR means we want the offset to be updated relative to its current position.

In the following example:

1. We call SDL_SeekIO() to advance past our 16-bit (2-byte) integer
2. We then read the next 32-bit integer so we can understand how many elements are in our array
3. We then call SDL_SeekIO() again to advance past the array. We know each element in the array is 32 bits (4 bytes), so we multiply that by the number of elements in the array

1// ...
2
3class Block : public Entity {
4 public:
5  Block(SDL_IOStream* Handle, BreakoutScene& Scene)
6  : Entity{Scene}
7  {
Previous Code (Unchanged)|Show
19
20    if (
21      static_cast<Config::ActorType>(Type) ==
22      Config::ActorType::GreenBlock
23    ) {
24      SDL_SeekIO(Handle, 2, SDL_IO_SEEK_CUR);
25      Uint32 ArraySize{0};
26      SDL_ReadU32LE(Handle, &ArraySize);
27      SDL_SeekIO(
28        Handle, ArraySize * 4, SDL_IO_SEEK_CUR
29      );
30    }
31  }
32};

We covered SDL_SeekIO() and read/write offsets in general earlier in the course

Generalizing Dynamically Sized Entities

Our implementation depends on our deserialization function to know exactly which entities contain additional data, and the nature of that data.

In more advanced projects, we could solve this problem by serializing additional metadata to explain what is going on. For example, each entity could serialize an additional integer, representing its size:

Alternatively, our level could serialize an additional array, storing the size of each entity:

Or the offset of each entity within the data:

This would allow the deserialization logic to easily jump around within the data. It can use these size or position values to calculate the offset of the object it's interested in within the data, and then call SDL_SeekIO() to jump right to it.

Remember, when we update our serialization format, there will still be files out there using the older format. This means that anywhere we're deserializing those files may now need to support both versions.

This is why we typically include a version number in our serialized data - it helps our deserialization code easily understand what it's dealing with.

Finally, let's add image and collision components to our blocks to make them visible and interactive.

Mapping Images

The image associated with each Block entity will depend on the block's Type. We'll add a std::unordered_map to map those types to their associated image paths:

1// ...
2#include <unordered_map>
3
4class Block : public Entity {
5  // ...
6
7private:
8  using ImageMap = std::unordered_map<
9    Config::ActorType, std::string>;
10  using enum Config::ActorType;
11  inline static ImageMap Images{
12    {Actor, ""},
13    {BlueBlock, "Assets/Brick_Blue_A.png"},
14    {GreenBlock, "Assets/Brick_Green_A.png"},
15    {CyanBlock, "Assets/Brick_Cyan_A.png"},
16    {OrangeBlock, "Assets/Brick_Orange_A.png"},
17    {RedBlock, "Assets/Brick_Red_A.png"},
18    {YellowBlock, "Assets/Brick_Yellow_A.png"}
19  };
20};

Adding Components

Let's add our components. We'll add a TransformComponent, a CollisionComponent, and an ImageComponent. We'll need to reference these components later, so let's save their pointers as member variables:

1// ...
2#include "Engine/ECS/TransformComponent.h"
3#include "Engine/ECS/ImageComponent.h"
4#include "Engine/ECS/CollisionComponent.h"
5
6class Block : public Entity {
7 public:
8  Block(SDL_IOStream* Handle, BreakoutScene& Scene)
9  : Entity{Scene}
10  {
Previous Code (Unchanged)|Show
34
35    Transform = AddComponent<TransformComponent>();
36    Collision = AddComponent<CollisionComponent>();
37    Image = AddComponent<ImageComponent>(
38      Config::BASE_PATH +
39      Images[static_cast<Config::ActorType>(Type)]
40    );
41  }
42
43private:
44  TransformComponent* Transform{nullptr};
45  ImageComponent* Image{nullptr};
46  CollisionComponent* Collision{nullptr};
47  // ...
48};

Configuring Components

As our last step, let's position and size our blocks and their colliders so they appear in the correct location in our scene. Our editor is providing those positions as grid rows and columns, which we need to convert to suitable screen-space coordinates that work for our scene.

Our engine's components provide the methods we need for this. We can use the SetPosition() function of our transform component, the SetSize() function of the collision component, and the SetWidth() and SetHeight() methods on the image component.

In my case, a width of 55.4 and height of 27 works well, but you may need to use different values depending on your scene and images. Remember, you can enable the DRAW_DEBUG_HELPERS flag to help with this:

1// ...
2
3class Block : public Entity {
4 public:
5  Block(SDL_IOStream* Handle, BreakoutScene& Scene)
6  : Entity{Scene}
7  {
Previous Code (Unchanged)|Show
31
32    float Width{55.4f};
33    float Height{27.f};
34    Transform = AddComponent<TransformComponent>();
35    Transform->SetPosition(Vec2{
36      GridCol * Width,
37      GridRow * Height
38    });
39
40    Collision = AddComponent<CollisionComponent>();
41    Collision->SetSize(Width, Height);
42
43    Image = AddComponent<ImageComponent>(
44      Config::BASE_PATH +
45      Images[static_cast<Config::ActorType>(Type)]
46    );
47    Image->SetWidth(Width);
48    Image->SetHeight(Height);
49  }
50  // ...
51};

With these changes, we should now see the blocks positioned in our world, and our ball can bounce off them:

In the next section, we'll update our blocks to let them be destroyed when the ball hits them.

Complete versions of the files we updated in this section are available below:

We've now successfully loaded our custom levels into the game, filling the screen with breakable bricks.

This lesson focused on deserialization, where we used SDL_IOStream to read the binary data we saved from our level editor. We created a Block class designed to be instantiated from a file stream and configured its components to match the loaded data.

Here are the key steps:

• We opened and read from a binary file using SDL_IOFromFile().
• We parsed a byte stream containing level metadata and a dynamic array of actor data.
• We created a Block class that deserializes itself from an SDL_IOStream handle.
• We ensured our file parsing was robust by correctly handling variable-sized entity data either by reading those variables, or skipping past them using SDL_SeekIO.
• We converted the editor's grid coordinates into screen-space positions for our game.