We've learned how to save our level designs, translating the in-memory state of actors and grid settings into a binary file using SDL3's file I/O capabilities. Now, we need the ability to bring those saved designs back to life in the editor.

This lesson focuses entirely on deserialization - the process of reading the binary data and reconstructing the original objects. We'll implement the Level::Load() function, carefully using SDL_ReadU8(), SDL_ReadU32LE(), and other SDL_IOStream functions to read data in the sequence it was saved.

A major focus will be the Factory Pattern. Since we only store a numeric type identifier (like 1 for BlueBlock), we need a way to invoke the correct constructor based on that number. We'll achieve this by:

Adding static Construct() methods to actor subclasses.
Storing pointers to these methods (using std::function).
Using the type identifier read from the file to select and call the right factory function.

This ensures our loading logic is flexible and can handle different actor types correctly.

By the end of this lesson, we'll have completed our level editor project!

Screenshot showing our completed level editor

Level Deserialization

With the serialization logic in place, we can now turn our attention to the reverse process: deserialization. The Level::Load() function is where we'll read the binary data from a .bin file and reconstruct the level state within the editor.

The first step mirrors saving: we need to open the file. We construct the filename using the LoadedLevel number and attempt to open it using SDL_IOFromFile(), this time with the mode "rb" for reading in binary.

If the file doesn't exist or cannot be opened, SDL_IOFromFile() returns nullptr, which we check for. Before reading any data, we also call Actors.clear() to remove any existing actors from the level currently loaded in the editor.

src/Editor/Level.cpp

1// ...
2
3void Level::Load() {
4  Actors.clear();
5  std::string FileName{
6    Config::BASE_PATH + std::format(
7      "Assets/Level{}.bin", LoadedLevel
8    )
9  };
10  SDL_IOStream* Handle{SDL_IOFromFile(
11    FileName.c_str(), "rb")};
12  if (!Handle) {
13    CheckSDLError("Loading Level");
14    return;
15  }
16
17  // TODO: Deserialize stuff
18
19  SDL_CloseIO(Handle);
20}

Our deserializing code must closely align with our serialization code. We must deserialize our objects respecting the size, order, and endianness in which they were serialized.

Our serialized data has three Uint8 values representing the version, grid width, and grid height in that order, followed by a little-endian Uint32 representing the number of actors in the level.

In SDL3, the reading functions like SDL_ReadU8 and SDL_ReadU32LE work by updating a variable via a pointer, and returning a boolean to indicate success.

Let's deserialize our header data using this API:

src/Editor/Level.cpp

1// ...
2
3void Level::Load() {
16
17  Uint8 FileVersion{0};
18  SDL_ReadU8(Handle, &FileVersion);
19  if (FileVersion != VERSION) {
20    // This file is from a different version of
21    // our software - react as needed
22  }
23
24  Uint8 GridWidth{0};
25  SDL_ReadU8(Handle, &GridWidth);
26
27  Uint8 GridHeight{0};
28  SDL_ReadU8(Handle, &GridHeight);
29
30  Uint32 ActorCount{0};
31  SDL_ReadU32LE(Handle, &ActorCount);
32
33  std::cout << std::format( "Loading a version "
34    "{} level ({}x{}) with {} actors\\n",
35    FileVersion, GridWidth,
36    GridHeight, ActorCount
37  );
38
39  // TODO: Load Actors
40
41  SDL_CloseIO(Handle);
42}

Currently, our loading code exists but isn't called automatically when the editor starts. To make the editor load Level 1 immediately on launch, we can call Load() directly from the Level class's constructor.

Since the LoadedLevel member defaults to 1, adding Load() inside the constructor body will trigger the loading sequence for "Assets/Level1.bin" as soon as the Level object is created within the Scene.

src/Editor/Level.h

1// ...
2
3namespace Editor {
4// ...
5
6class Level {
7 public:
8  Level(Scene& ParentScene)
9  : ParentScene{ParentScene} {
10    Load();
11  }
12  // ...
13};
14}

If a "Level1.bin" file exists from a previous save, its data should now be read and logged.

1Loading a version 1 level (13x6) with 2 actors

Actor Factories

To load our actors, let's use some of the techniques we covered in our . Each specific Actor subtype that can exist in our serialized data will have a function that is responsible for deserializing that data, constructing the object based on that data, and returning a pointer to it.

The natural place to define these functions is alongside the types themselves, so we'll add them as static functions to our Actor subtypes, like BlueBlock and GreenBlock.

Let's start with BlueBlock. To construct a BlueBlock, we need two things:

A reference to the parent Scene. Our Level's Load() function can pass this when it's calling our factory function.
An SDL_Rect representing its position and size. The position (x, y) can be calculated from the grid row and grid column values in the serialized data. The size (w, h) is the same for all BlueBlock instances, and is currently stored as static WIDTH and HEIGHT values.

All of our block types will need to calculate this SDL_Rect, so let's add a helper function to the Actor base class that they can all use. Note that this function takes an SDL_IOStream*.

src/Editor/Actor.h

1// ...
2
3namespace Editor {
4class Scene;
5class Actor {
6 public:
7  // ...
8  static SDL_Rect GeneratePositionRectangle(
9    SDL_IOStream* Handle, int Width, int Height
10  ) {
11    using namespace Config::Editor;
12    Uint8 GridRow{0}, GridCol{0};
13    SDL_ReadU8(Handle, &GridRow);
14    SDL_ReadU8(Handle, &GridCol);
15
16    SDL_Rect R{0, 0, Width, Height};
17    R.x = GridCol * HORIZONTAL_GRID_SNAP;
18    R.y = GridRow * VERTICAL_GRID_SNAP;
19    return R;
20  }
21  // ...
22};
23}

Back in BlueBlock, let's add our static Construct() function:

src/Editor/Blocks.h

1// ...
2
3namespace Editor{
4class BlueBlock : public Actor {
5public:
6  // ...
7
8  static std::unique_ptr<Actor> Construct(
9    SDL_IOStream* Handle,
10    Scene& ParentScene
11  ) {
12    return std::make_unique<BlueBlock>(
13      ParentScene,
14      GeneratePositionRectangle(
15        Handle, WIDTH, HEIGHT));
16  }
17};
18}

Deserializing Green Blocks

GreenBlock::Construct() will be similar - we'll also just grab the contrived SomeNumber and SomeArray data from the file using the little-endian read functions and apply it to the object we create:

src/Editor/Blocks.h

1// ...
2
3namespace Editor{
4// ...
5
6class GreenBlock : public Actor {
7public:
8  // ...
9
10  static std::unique_ptr<Actor> Construct(
11    SDL_IOStream* Handle,
12    Scene& ParentScene
13  ) {
14    auto NewActor{std::make_unique<GreenBlock>(
15      ParentScene,
16      GeneratePositionRectangle(
17        Handle, WIDTH, HEIGHT))};
18
19    // Read the 16-bit integer
20    Uint16 TempShort{0};
21    SDL_ReadU16LE(Handle, &TempShort);
22    NewActor->SomeNumber = static_cast<Sint16>(TempShort);
23
24    // Read array size
25    Uint32 ArraySize{0};
26    SDL_ReadU32LE(Handle, &ArraySize);
27
28    // Read array elements
29    NewActor->SomeArray.resize(ArraySize);
30    for (Uint32 i{0}; i < ArraySize; ++i) {
31      Uint32 TempInt{0};
32      SDL_ReadU32LE(Handle, &TempInt);
33      NewActor->SomeArray[i] = static_cast<Sint32>(TempInt);
34    }
35    return NewActor;
36  }
37};
38}

Using the Factories

Back in Level::Load(), let's use these factories to recreate our full level. We'll store our loaders as std::function wrappers. We only need them in our Level.cpp file, so let's add them in an anonymous namespace in that file, above our Load() function:

src/Editor/Level.cpp

1// ...
2#include <functional>
3// ...
4
5namespace{
6using namespace Config;
7using ActorLoaderFunc = std::function<
8  std::unique_ptr<Actor>(SDL_IOStream*, Scene&)>; 
9
10std::vector<ActorLoaderFunc> ActorLoaders{
11  {},                    // Index 0
12  BlueBlock::Construct,  // Index 1
13  GreenBlock::Construct, // Index 2
14};
15}
16// ...

The effect of putting ActorLoaders in an anonymous namespace is that it can now only be accessed from within this same source file, Level.cpp. This prevents us from polluting our global scope with symbols that are only relevant to one area of our program.

The indices of this ActorLoaders array corresponds to the numeric actor types in our serialized data. As a reminder, our ActorType enum is set up like this:

1enum class ActorType : Uint8 {
2  Actor = 0,
3  BlueBlock = 1,
4  GreenBlock = 2,
5};

So, we store the loader for BlueBlock at index 1, and GreenBlock at index 2. Our program doesn't allow basic Actor instances to be added to the level, so we'll never need to deserialize those. As such, we just store an empty std::function at the base Actor index (0).

Design Improvements and Maps

When our design requires us to keep two values in sync, we should generally try to improve our approach. Inevitably we, or someone on our team, will make some change that breaks that link, thereby introducing a bug. This is particularly likely when the values we need to keep in sync are in totally different files (Config.h and Level.cpp)

We'll learn better techniques for implementing these patterns later, but one simple improvement is to use a std::unordered_map as an alternative to a std::vector. This lets us make the mapping from ActorType values to their corresponding std::function factory more explicit:

src/Editor/Level.cpp

1// ...
2#include <unordered_map>
3
4// ...
5namespace{
6using namespace Config;
7using ActorLoaderFunc = std::function<
8  std::unique_ptr<Actor>(SDL_IOStream*, Scene&)>;
9
10using enum ActorType;
11std::unordered_map<
12  ActorType, ActorLoaderFunc
13> ActorLoaders{
14  {Actor, {}},
15  {BlueBlock, BlueBlock::Construct},
16  {GreenBlock, GreenBlock::Construct}
17};
18}
19
20// ...

Our Load() function can use this std::unordered_map in much the same way it uses a std::vector, using the [] operator to access the correct loader. The only difference is that it needs to cast the Uint8 representing the actor's type back to the Config::ActorType enum value it originated from:

1Uint8 Type{0};
2SDL_ReadU8(Handle, &Type);
3
4auto Loader{ActorLoaders[
5  // When ActorLoaders is a vector:
6  Type
7
8  // When ActorLoaders is an unordered_map:
9  static_cast<ActorType>(Type)
10]};

We cover maps in more detail later in the course.

Loading All Actors

All that's left to do is update our Load() function to loop ActorCount times, grab the type of each actor, call the corresponding std::function to create it, and then add it to the level:

src/Editor/Level.cpp

1// ...
2
3void Level::Load() {
35
36  for (size_t i{0}; i < ActorCount; ++i) {
37    Uint8 ActorType{0};
38    SDL_ReadU8(Handle, &ActorType);
39
40    auto Loader{ActorLoaders[ActorType]};
41    if (Loader) {
42      ActorPtr NewActor{Loader(Handle, ParentScene)};
43      NewActor->SetLocation(ActorLocation::Level);
44      AddToLevel(std::move(NewActor));
45    } else {
46      std::cout << "Error: No Loader for Actor "
47        "Type " << static_cast<int>(ActorType) << '\\n';
48    }
49  }
50
51  SDL_CloseIO(Handle);
52}

With all our plumbing in place, we can just add new actors to our editor as needed. In the Complete Code section below, we've added RedBlock, OrangeBlock, and YellowBlock actors by following the exact same pattern.

Add our new types to the ActorType enum.
Add new classes that inherit from Actor.
Add our necessary functions - Construct(), Clone(), GetActorType(), and the constructor. This can be done manually or using our preprocessor macro if we created one.
Add an instance of our new type to the ActorMenu.

With that, our program is now complete! We can create levels which get saved in the Assets/ directory alongside our program executable. We can also load those levels later, and see them restored in our Editor for us to modify.

Complete Code

A complete version of the project is provided below:

Files

Assets

src

CMakeLists.txt

Select a file to view its content

Summary

In this final part of the editor's core implementation, we focused on deserialization - loading the saved level data back into the editor. We implemented the Level::Load() method, using SDL_IOStream to read the binary file created in the previous lesson.

We emphasized matching the read operations (SDL_ReadU8(), SDL_ReadU32LE(), etc) to the write operations used during serialization. To handle reconstructing actors of unknown types, we introduced static factory methods (Construct) within each actor class. These factories read the necessary data from the file handle and returned a unique_ptr<Actor>.

A std::vector<std::function> was used to map the serialized actor type ID to the corresponding factory function.

Key Takeaways:

Loading involves opening files with "rb" mode using SDL_IOFromFile().
Error check the result of SDL_IOFromFile().
Read data in the exact sequence and format it was written.
Static factory methods provide a clean way to handle object construction during deserialization.
std::function allows storing pointers to these static methods for dynamic dispatch.
Remember to convert grid coordinates back to rendering coordinates when setting actor positions.

Loading Levels

Level Deserialization

src/Editor/Level.cpp

src/Editor/Level.cpp

src/Editor/Level.h

Actor Factories

src/Editor/Actor.h

src/Editor/Blocks.h

Deserializing Green Blocks

src/Editor/Blocks.h

Using the Factories

src/Editor/Level.cpp

Design Improvements and Maps

src/Editor/Level.cpp

Loading All Actors

src/Editor/Level.cpp

Complete Code

Files

Summary

Exponents and `cmath`

Game Development with SDL3

Loading Levels

Level Deserialization

src/Editor/Level.cpp

src/Editor/Level.cpp

src/Editor/Level.h

Actor Factories

src/Editor/Actor.h

src/Editor/Blocks.h

Deserializing Green Blocks

src/Editor/Blocks.h

Using the Factories

src/Editor/Level.cpp

Design Improvements and Maps

src/Editor/Level.cpp

Loading All Actors

src/Editor/Level.cpp

Complete Code

Files

Summary

Exponents and cmath

Exponents and `cmath`