Saving Your Editor Levels

Let's work on serializing our level, such that we can store it on our hard drive. We need to decide on two things:

• What we need to serialize
• What format we should serialize it in

What to Serialize

It's technically the case that the core functionality of being able to load a level we previous saved only requires us to serialize the actors in our level. Specifically, for each actor, we need to remember it's type (eg, BlueBlock) and position within the level.

However, it's often useful to store some additional metadata alongside this core information. This might include the size of our level (how many rows and columns it has) or the version of our software that created the serialized data.

This version tends to be particularly useful as, in the future, we may update our software, and that update might include changes to how data is serialized. By having the version right at the start of our serialized data, we can immediately understand if we're loading a file from an earlier iteration, and adapt accordingly.

So, in this project, our level will serialize:

• The editor version
• The grid width
• The grid height
• The actors in the level

Each actor is also a complex type, so we need to further break down how they will be serialized. For each of our actors, we'll store:

• Their type
• Their grid row
• Their grid column

We'll also introduce a slightly more advanced actor later, that needs to serialize some additional information.

Serialization Format

If this were a real project, we'd likely want to serialize our levels using a standard, text-based format. An example level, serialized as JSON, might look like this:

1{
2  "Version": 1,
3  "GridWidth": 13,
4  "GridHeight": 5,
5  "Actors": [{
6    "Type": "BlueBlock",
7    "Row": 2,
8    "Column": 5
9  }, {
10    "Type": "BlueBlock",
11    "Row": 6,
12    "Column": 3
13  }]
14}

This makes our data easier to understand and edit, even outside of our level editor program. This is less efficient than binary serialization but, in this case, we don't really need to maximize performance. The trade off of having our levels take slightly longer to save and load is worth the increased clarity.

However, this is a learning project that aims to reinforce concepts we covered in previous lessons, like memory layout and endianness. Therefore, we will opt for a custom binary format. This gives us direct control over the byte-level representation and requires careful handling of data types and byte order.

We'll serialize our levels like this:

• Editor version: Uint8
• Grid width: Uint8
• Grid height: Uint8
• Actor count: Uint32 (little-endian)

Note that the widths of these values were chosen somewhat arbitrarily. If we thought any of these unsigned 8-bit values could be larger than 255, for example, we wanted to make much bigger levels, we'd use wider integers.

Following these level-specific values, we'll then serialize our actors as a contiguous block. We don't necessarily know how big this block will be - it depends on the number of actors. In the future, it will also depend on the types of those actors, as different actor types will have different serialization requirements - some might need to save more data than others.

To keep things organised, the specific serialization format of each actor will be defined by that actor's type. For example, the BlueBlock class will control how a BlueBlock instance is serialized. It will control what data it seralizes, and how many bytes each data point requires.

However, all our actor types will include the following information, which we'll serialize at the start of the respective actor's block:

• Actor type: Uint8
• Row: Uint8
• Column: Uint8

The following shows the resulting serialization layout if our Level's Actors array contained two actors, but this pattern repeats for any actor count.

To begin the saving process, we need the version number defined in our serialization strategy.

Let's add this to Config.h, nested inside Config::Editor. This constant will be the first byte written to our level files.

1// Config.h
2// ...
3
4#ifdef WITH_EDITOR
5namespace Config::Editor {
6inline const Uint8 VERSION{1};
7// ...
8}
9#endif
10
11// ...

Now let's implement the Level::Save() function in Level.cpp. The first step is to open the correct file for writing. We construct the filename dynamically using std::format() from C++20 (or an alternative string concatenation method, which we cover after this code example).

Our file name needs to include the LoadedLevel number, like "Assets/Level1.bin".

Once we have the file path, we'll try to open it as an existing file for writing in binary using "wb". If this doesn't work, we'll assume the file doesn't exist, so we'll then try to create and open it using "w+b":

1// Editor/Source/Level.cpp
2// ...
3#include <format>
4
5void Level::Save() {
6  std::string FileName{
7    std::format("Assets/Level{}.bin", LoadedLevel)
8  };
9  SDL_RWops* Handle{SDL_RWFromFile(
10    FileName.c_str(), "wb")
11  };
12  CheckSDLError(
13    "Saving Level to Existing File");
14  if (!Handle) {
15    Handle = SDL_RWFromFile(
16      FileName.c_str(), "w+b"
17    );
18    CheckSDLError(
19      "Saving Level to New File");
20  }
21
22  // TODO: Serialize stuff...
23
24  SDL_RWclose(Handle);
25}

With our level file open for writing, let's start by inserting the first three values of our serialization format. Given we've chosen 8 bit values for our VERSION, GRID_WIDTH, and GRID_HEIGHT, we don't need to worry about the byte order, as these all just have a single byte.

We can write a single byte using SDL_WriteU8():

1// Editor/Source/Level.cpp
2// ...
3
4void Level::Save() {
Previous Code (Unchanged)|Show
20  
21  using namespace Config::Editor;
22  SDL_WriteU8(Handle, VERSION);
23  SDL_WriteU8(Handle, GRID_WIDTH);
24  SDL_WriteU8(Handle, GRID_HEIGHT);
25
26  // TODO: Serialize the actors
27  // ...
28
29  SDL_RWclose(Handle);
30}

Remember, behind the scenes, our SDL_RWops object is keeping track of where the last write operation occurred, so all the data we write is appended to what we previous wrote. For example, after we call SDL_WriteU8() to write the VERSION, the internal byte offset advances by one byte, so the next call to SDL_WriteU8() ensures the GRID_WIDTH immediately comes after the VERSION.

This means we're constantly appending to our data. That remains true even when we pass the Handle pointer to another function, which we'll do soon. Any writing that that function does is appending to what was already there.

We covered this mechanism, and how to intervene in its operation, in the previous chapter:

Let's move on to our Actors array. We'll start by storing the number of actors in our level. We've chosen a 32 bit (4-byte) value for this, and settled on little-endian byte order, so we'll use SDL_WriteLE32().

Then, we iterate through all of our actors, and ask them to serialize themselves by calling a Serialize() method, which we'll implement next:

1// Editor/Source/Level.cpp
2// ...
3
4void Level::Save() {
Previous Code (Unchanged)|Show
22
23  SDL_WriteLE32(Handle, Actors.size());
24  for (const ActorPtr& A : Actors) {
25    A->Serialize(Handle);
26  }
27
28  SDL_RWclose(Handle);
29}

In our base Actor class, let's add our Serialize() method, which serializes the actor's type, followed by its position in the grid. Currently, we only make one actor available to be added to our level (the BlueBlock), but we'll expand this soon.

We want different actor subtypes to define their own serialziation procedures, so we'll mark this function as virtual:

1// Editor/Actor.h
2// ...
3
4namespace Editor {
5class Scene;
6class Actor {
7 public:
8  
9
10  virtual void Serialize(SDL_RWops* Handle) const {
11    // Serialize Type
12    // ...
13    
14    // Serialize Position
15    // ...
16  }
17};
18}

Serializing the Actor Type

To serialize the actor's type, we first need a defined set of numeric identifiers for each type. An enum class is perfect for this.

In Config.h, we'll add enum class ActorType : Uint8 inside the Config namespace. The : Uint8 explicitly sets the underlying type to an 8-bit unsigned integer, fitting our single-byte type identifier plan. We define Actor = 0 and BlueBlock = 1 as the first members.

1// Config.h
2// ...
3
4namespace Config {
5enum class ActorType : Uint8 {
6  Actor = 0,
7  BlueBlock = 1,
8};
9
10// ...
11}
12
13// ...

Now that we have the ActorType enum, each actor instance needs to be able to report its own type. We can add another virtual function to the Actor base class for this.

In Editor/Actor.h, we'll declare the virtual Config::ActorType GetActorType() function. The base class implementation will return Config::ActorType::Actor. Derived classes will override this to return their specific enum value.

1// Editor/Actor.h
2// ...
3
4namespace Editor {
5class Scene;
6class Actor {
7 public:
8  // ...
9  virtual Config::ActorType GetActorType() const {
10    return Config::ActorType::Actor;
11  }
12  // ...
13};
14}

Subclasses must implement the GetActorType() virtual function to identify themselves correctly.

For the BlueBlock class in Editor/Blocks.h, we add the overriding function: Config::ActorType GetActorType(). Its implementation simply returns Config::ActorType::BlueBlock.

1// Editor/Blocks.h
2// ...
3
4namespace Editor{
5class BlueBlock : public Actor {
6public:
7  // ...
8
9  Config::ActorType GetActorType() const override {
10    return Config::ActorType::BlueBlock;
11  }
12};
13}

Back in Actor::Serialize() (in Actor.h), we can now write the type identifier. We call the virtual function GetActorType() to obtain the ActorType enum value.

We need to write this as a raw byte. We explicitly cast the enum value to Uint8 (its underlying type) and store it in a temporary variable. Then, we use SDL_WriteU8() to write this byte to the Handle.

1// Editor/Actor.h
2// ...
3namespace Editor {
4class Scene;
5class Actor {
6 public:
7  // ...
8
9  virtual void Serialize(
10    SDL_RWops* Handle
11  ) const {
12    using namespace Config::Editor;
13    Uint8 ActorType{static_cast<Uint8>(
14      GetActorType())};
15    SDL_WriteU8(Handle, ActorType);
16
17    // Serialize Position
18    // ...
19  }
20  // ...
21};
22}

Serializing the Actor Position

Next, let's serialize the actor's positions, which are stored in its Rect.x and Rect.y values. Unfortunately, these positions represent where the actor is drawn in our editor window.

This is fine if we're only ever going to use this data inside our editor. But, in the future, we'll also be loading these levels into our game, so we should serialize the information in a more generally useful way.

To convert the x and y values to their position within the grid, we can divide them by our HORIZONTAL_GRID_SNAP and VERTICAL_GRID_SNAP values respectively:

1// Editor/Actor.h
2// ...
3namespace Editor {
4class Scene;
5class Actor {
6 public:
7  // ...
8
9  virtual void Serialize(
10    SDL_RWops* Handle
11  ) const {
12    using namespace Config::Editor;
13    Uint8 ActorType{static_cast<Uint8>(
14      GetActorType())};
15    SDL_WriteU8(Handle, ActorType);
16
17    Uint8 GridRow = Rect.y / VERTICAL_GRID_SNAP;
18    SDL_WriteU8(Handle, GridRow);
19
20    Uint8 GridCol = Rect.x / HORIZONTAL_GRID_SNAP;
21    SDL_WriteU8(Handle, GridCol);
22  }
23  // ...
24};
25}

Our Actor is now beign serialized correctly. Indirectly, our BlueBlock is also being serialized correctly, because the base Serialize() function that it inherits is sufficient for its needs.

Let's add a new actor, that we'll add some more complex serialization requirements to later. We'll add a GreenBlock to our ActorType enum:

1// Config.h
2// ...
3
4namespace Config {
5enum class ActorType : Uint8 {
6  Actor = 0,
7  BlueBlock = 1,
8  GreenBlock = 2,
9};
10
11// ...
12}
13
14// ...

In Editor/Blocks.h, we'll declare the GreenBlock class. It inherits publicly from Actor.

We declare its constructor, static constexpr dimensions, and override the GetActorType() virtual function to return ActorType::GreenBlock.

We also override Clone() to ensure it creates a GreenBlock instance when cloned.

1// Editor/Blocks.h
2// ...
3
4namespace Editor{
BlueBlock Class (For Reference)|Show
5class BlueBlock : public Actor {/*...*/};
23
24class GreenBlock : public Actor {
25public:
26  static constexpr int WIDTH{50};
27  static constexpr int HEIGHT{25};
28
29  GreenBlock(Scene& ParentScene,
30             SDL_Rect Rect);
31
32  Config::ActorType GetActorType() const override {
33    return Config::ActorType::GreenBlock;
34  }
35
36  std::unique_ptr<Actor> Clone() const override {
37    return std::make_unique<GreenBlock>(*this);
38  }
39};
40}

Let's define the GreenBlock constructor in Editor/Source/Blocks.cpp.

The implementation mirrors the BlueBlock constructor, calling the base Actor constructor with the scene, the calculated SDL_Rect, and the specific GreenBlock image obtained from ParentScene.GetAssets().

1// Editor/Source/Blocks.cpp
2// ...
3
4GreenBlock::GreenBlock(
5  Scene& ParentScene, SDL_Rect Rect
6) : Actor{
7  ParentScene,
8  SDL_Rect{Rect.x, Rect.y, WIDTH, HEIGHT},
9  ParentScene.GetAssets().GreenBlock
10} {}

To make the new GreenBlock available for users to place in the level, we need to add an instance of it to the ActorMenu.

In Editor/ActorMenu.h, within the ActorMenu constructor, let's add another Actors.emplace_back() call. This time, we'll use std::make_unique<GreenBlock>().

We'll calculate its initial Y position based on the height of the BlueBlock above it and the PADDING to place it below the blue block in the menu.

1// Editor/ActorMenu.h
2// ...
3
4namespace Editor {
5// ...
6class ActorMenu {
7 public:
8  ActorMenu(Scene& ParentScene)
9  : ParentScene{ParentScene}
10  {
11    using namespace Config::Editor;
Adding Blue Block|Show
22    
23    Actors.emplace_back(
24      std::make_unique<GreenBlock>(
25        GetScene(),
26        SDL_Rect{
27          ACTOR_MENU_POSITION_X + PADDING,
28          BlueBlock::HEIGHT + PADDING * 2,
29          0, 0
30        }
31      )
32    );
33  }
34  // ...
35};
36}

Running our program, we should now see two actors available in our menu. We can construct a level using these two actors and, when we click "Save", a binary file is stored in the /Assets directory in the same location as our executable file.

Let's make things more complex by adding some extra state to GreenBlock that it needs to serialize. In Blocks.h, we'll add two members a Sint16 and a std::vector<Sint32>.

Since GreenBlock now has data not covered by the base Actor::Serialize(), it must provide its own override.

But GreenBlock still wants its type and position serialized, so the GreenBlock::Serialize() override will first call Actor::Serialize(Handle) to ensure these base members are written.

After that, it writes its Sint16 using SDL_WriteLE16(), followed by the size of its array using SDL_WriteLE32(), and finally iterates through that array, writing each Sint32 element it contains using SDL_WriteLE32().

1// Editor/Blocks.h
2// ...
3
4namespace Editor{
5// ...
6
7class GreenBlock : public Actor {
8public:
9  // ...
10
11  Sint16 SomeNumber{32};
12  std::vector<Sint32> SomeArray{1, 2, 3};
13
14  void Serialize(SDL_RWops* Handle) const override {
15    Actor::Serialize(Handle);
16    SDL_WriteLE16(Handle, SomeNumber);
17    SDL_WriteLE32(Handle, SomeArray.size());
18    for (Sint32 Num : SomeArray) {
19      SDL_WriteLE32(Handle, Num);
20    }
21  }
22};
23}

Remember, not everything in a class needs to be serialized - we only serialize things that we need to save, and that we can't infer any other way. For example, we don't serialize the image that our actors are using, because that image is entirely dependant on the actor's type, which we're already serializing.

If we had a more complex editor where users could change the image our actors use within the level, without changing their type, then our serialization logic would need to be updated to store this information.

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

This lesson focused on adding persistence to our level editor by implementing the save functionality. We started by adding UI buttons ("Load 1/2/3", "Save", "Play") to the editor's footer.

We defined new custom SDL event types (LOAD_LEVEL, SAVE_LEVEL, etc.) triggered by these buttons. The buttons themselves were implemented as subclasses of Button, handling their specific event pushing and visual state management (like disabling the Save button when there are no changes).

The core work involved designing a binary serialization format for our levels. We decided to store a version number, grid dimensions, and a list of actors. For each actor, we store its type and grid position, with derived types able to serialize additional custom data.

We implemented the Level::Save() function using SDL_RWops and SDL's binary writing functions (SDL_WriteU8(), SDL_WriteLE32(), etc.). We added a virtual Serialize() method to the Actor hierarchy, allowing each actor type to contribute its data to the save file polymorphically.

Key takeaways:

• Use custom SDL events to decouple UI actions from logic execution.
• Manage button states (Active, Disabled) for better UX.
• Define a clear binary serialization format, including versioning and metadata.
• Use SDL_RWops for platform-agnostic file I/O.
• Employ virtual functions for polymorphic serialization in class hierarchies.
• Choose appropriate data types (Uint8, Uint32, Sint16) and endianness (LE) for serialization.
• Only serialize essential state, deriving other data where possible during loading.