We've learned how to save our level designs, translating the in-memory state of actors and grid settings into a binary file using SDL'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_ReadLE32(), and other SDL_RWops functions to read data in the sequence it was saved.

A major focus will be the Factory Pattern. Since we only store a type identifier (like 1 for BlueBlock), we need a way to invoke the correct constructor. 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_RWFromFile(), this time with the mode "rb" for reading in binary.

If the file doesn't exist or cannot be opened, SDL_RWFromFile() 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.

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

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.

Let's deserialize them in that order, and log out what we found:

1// Editor/Source/Level.cpp
2// ...
3
4void Level::Load() {
15  
16  Uint8 FileVersion{SDL_ReadU8(Handle)};
17  if (FileVersion != VERSION) {
18    // This file is from a different version of
19    // our software - react as needed
20  }
21  Uint8 GridWidth{SDL_ReadU8(Handle)};
22  Uint8 GridHeight{SDL_ReadU8(Handle)};
23  Uint32 ActorCount{SDL_ReadLE32(Handle)};
24
25  std::cout << std::format( "Loading a version "
26    "{} level ({}x{}) with {} actors\n",
27    FileVersion, GridWidth,
28    GridHeight, ActorCount
29  );
30
31  // TODO: Load Actors
32
33  SDL_RWclose(Handle);
34}

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.

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

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 lesson on function pointers. 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 a 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:

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

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

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

Deserializing Green Blocks

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

1// Editor/Blocks.h
2// ...
3
4namespace Editor{
5// ...
6
7class GreenBlock : public Actor {
8public:
9  // ...
10
11  static std::unique_ptr<Actor> Construct(
12    SDL_RWops* Handle,
13    Scene& ParentScene
14  ) {
15    auto NewActor{std::make_unique<GreenBlock>(
16      ParentScene,
17      GeneratePositionRectangle(
18        Handle, WIDTH, HEIGHT))};
19
20    NewActor->SomeNumber = SDL_ReadLE16(Handle);
21
22    Uint32 ArraySize{SDL_ReadLE32(Handle)};
23    NewActor->SomeArray.resize(ArraySize);
24    for (int i{0}; i < ArraySize; ++i) {
25      NewActor->SomeArray[i] = SDL_ReadLE32(Handle);
26    }
27    return NewActor;
28  }
29};
30}

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:

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

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::functional 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.

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 make the mapping from ActorType values to their corresponding std::functional factory more explicit:

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

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{SDL_ReadU8(Handle)};
2
3auto Loader{ActorLoaders[
4  // When ActorLoaders is a vector:
5  Type
6  
7  // When ActorLoaders is an unordered_map:
8  static_cast<ActorType>(Type)
9]};

We cover maps in more detail later in the course.

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::functional to create it, and then add it to the level:

1// Editor/Source/Level.cpp
2// ...
3
4void Level::Load() {
29
30  for (size_t i{0}; i < ActorCount; ++i) {
31    Uint8 ActorType{SDL_ReadU8(Handle)};
32    auto Loader{ActorLoaders[ActorType]};
33    if (Loader) {
34      ActorPtr NewActor{Loader(Handle, ParentScene)};
35      NewActor->SetLocation(ActorLocation::Level);
36      AddToLevel(std::move(NewActor));
37    } else {
38      std::cout << "Error: No Loader for Actor "
39        "Type " << ActorType << '\n';
40    }
41  }
42
43  SDL_RWclose(Handle);
44}

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 of using our preprocessor macro if we created one
Add an instance of our new type to the ActorMenu.

With that, our program is now be 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

Complete versions of the files we changed in this lesson are provided below:

The remaining project files, which were not changed in this lesson, are available below:

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_RWops to read the binary file created in the previous lesson.

We emphasized matching the read operations (SDL_ReadU8(), SDL_ReadLE32(), 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_RWFromFile().
Error check the result of SDL_RWFromFile().
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 Saved Levels

Level Deserialization

Actor Factories

Deserializing Green Blocks

Using the Factories

Complete Code

Summary

Exponents and `cmath`

Game Development with SDL2

Loading Saved Levels

Level Deserialization

Actor Factories

Deserializing Green Blocks

Using the Factories

Complete Code

Summary

Exponents and cmath

Exponents and `cmath`