Saving Your Editor Levels

In the previous lessons, we've built the core mechanics of our level editor: creating a window, managing actors, implementing drag-and-drop with grid snapping, and handling selection and deletion. However, any level we design currently vanishes the moment we close the application.

This lesson tackles persistence. We'll add controls to the editor's footer buttons to save the current level layout to a file and buttons to load previously saved levels. This involves defining new custom SDL events to signal these actions.

We'll then implement binary serialization using SDL's SDL_RWops structure and related functions (SDL_WriteU8(), SDL_WriteLE32(), etc.).

We'll carefully design a binary format for our level files, deciding what data needs saving (version, grid size, actor types, positions) and how to represent it efficiently.

Finally, we'll implement the Save() logic within our Level class, writing the editor's state to a file according to our defined format. We'll also extend actors with a virtual Serialize() method, allowing different actor types to save their specific data, preparing the groundwork for loading in the next lesson.

We’ll assume our project contains 3 levels, but feel free to add more.

Footer Buttons

Let's begin by adding the user interface elements for saving and loading. We'll place several buttons in the footer area below the main level canvas. These buttons will trigger different actions related to level management.

To communicate these actions within our application, we'll rely on custom SDL events, just like we did for actor dragging.

We need distinct event types for loading a specific level, saving the current level, and initiating a "save and play" sequence. We'll define these new event types in our Config.h file, within the UserEvents namespace, using SDL_RegisterEvents().

We register LOAD_LEVEL, SAVE_LEVEL, and SAVE_AND_PLAY_LEVEL. as the primary events we need to react to for serialization (in this lesson) and deserialization (in the next lesson) actions.

We’ll also add LEVEL_EDIT to signal when a change occurs, and LAUNCH_LEVEL which the editor will eventually use to signal the game (once built) to start playing a specific level.

1// Config.h
2// ...
3
4namespace UserEvents{
5#ifdef WITH_EDITOR
6inline Uint32 ACTOR_DRAG{SDL_RegisterEvents(1)};
7inline Uint32 LOAD_LEVEL{SDL_RegisterEvents(1)};
8inline Uint32 SAVE_LEVEL{SDL_RegisterEvents(1)};
9inline Uint32 SAVE_AND_PLAY_LEVEL{
10  SDL_RegisterEvents(1)};
11inline Uint32 LEVEL_EDIT{SDL_RegisterEvents(1)};
12#endif
13inline Uint32 LAUNCH_LEVEL{
14  SDL_RegisterEvents(1)};
15}
16
17// ...

Load Level Button

Let's implement the buttons that allow the user to choose which level file to work with. We'll define a LoadLevelButton class in Editor/EditorButtons.h, inheriting from Button.

An essential piece of information for this button is the level number it represents. The constructor will take this number as an argument and store it privately.

In the constructor's initializer list, we call the base Button constructor. The button's label is set using std::to_string(Level). Its position (Rect) is calculated to place it correctly in the footer row, spaced according to its level number.

To provide visual feedback about the initially loaded level, we add logic to the LoadLevelButton constructor: if the button is being created for level 1, its state is immediately set to Active as later, when our program first launches, we’ll make it load level 1 automatically.

All other load buttons start in the default Normal state.

1// Editor/EditorButtons.h
2#pragma once;
3#include "Button.h"
4
5namespace Editor{
6using namespace Config::Editor;
7class LoadLevelButton : public Button {
8public:
9  constexpr static int WIDTH{40};
10  LoadLevelButton(Scene& ParentScene, int Level)
11  : Level{Level},
12    Button {
13      ParentScene,
14      std::to_string(Level),
15      {
16        PADDING * Level + WIDTH * (Level-1),
17        LEVEL_HEIGHT + PADDING,
18        WIDTH, 30
19      }
20    }
21  {
22    if (Level == 1) {
23      SetState(ButtonState::Active);
24    }
25  }
26
27private:
28  int Level;
29};
30}

When a LoadLevelButton is clicked, it needs to signal the rest of the application that a request to load its associated level has been made. We achieve this by overriding the virtual HandleLeftClick() function.

Inside HandleLeftClick(), we create an SDL_Event struct, setting its type to our custom UserEvents::LOAD_LEVEL. Now, we need to communicate which level was requested.

As we’ve seen, the SDL_UserEvent structure within SDL_Event has several fields we can use, including data1, data2, and code. We’ve mostly been using data1 and data2, as they’re void* pointers suitable for passing any arbitrary data we need. Our other option, code is a simple Sint32 (signed 32-bit integer).

Since our Level member is just an integer, using code is simpler and avoids dealing with void* casting. We’ll copy the button's Level member to E.user.code and then push the event onto the queue using SDL_PushEvent().

1// Editor/EditorButtons.h
2// ...
3
4namespace Editor{
5using namespace Config::Editor;
6class LoadLevelButton : public Button {
7public:
8  // ...
9
10  void HandleLeftClick() override {
11    SDL_Event E{UserEvents::LOAD_LEVEL};
12    E.user.code = Level;
13    SDL_PushEvent(&E);
14  }
15  
16   // ...
17};
18}

A LoadLevelButton needs to visually reflect which level is currently active. This requires reacting to LOAD_LEVEL events pushed by any button. We’ll override the HandleEvent() method for this.

The first line calls Button::HandleEvent(E) to ensure the base class handles the basic motion and clicking actions correcntly. Then, we check if E.type is UserEvents::LOAD_LEVEL.

If a load event is detected, we need to determine if this button should become active. We compare the event's payload, E.user.code, which holds the level number being loaded, against this button's own Level member.

If they’re ther same, it means this button represents the level being loaded, so we call update our state to ButtonState::Active. Otherwise, this button represents an inactive level, and we’ll revert our state to ButtonState::Normal to ensure we’re not highlighted.

1// Editor/EditorButtons.h
2// ...
3
4namespace Editor{
5using namespace Config::Editor;
6class LoadLevelButton : public Button {
7public:
8  // ...
9
10  void HandleEvent(const SDL_Event& E) {
11    Button::HandleEvent(E);
12    if (E.type == UserEvents::LOAD_LEVEL) {
13      if (E.user.code == Level) {
14        SetState(ButtonState::Active);
15      } else {
16        SetState(ButtonState::Normal);
17      }
18    }
19  }
20
21  // ...
22}

We’re updating this state in the HandleEvent() function rather than HandleLeftClick() because we’ll have multiple LoadLevelButton instances in our scene. When any one of them is clicked, we want all of them to react and update their state accordingly.

Play Level Button

Next, we’ll implement the PlayLevelButton. This button's purpose is to initiate a save operation followed by a signal to start the game with the saved level.

In its overridden HandleLeftClick() method, we simply construct an SDL_Event with the type SAVE_AND_PLAY_LEVEL and push it onto the event queue. The logic to perform the save and then push the LAUNCH_LEVEL event will reside in the Level class's event handling later.

1// Editor/EditorButtons.h
2// ...
3
4namespace Editor{
5// ...
6
7class PlayLevelButton : public Button {
8public:
9  constexpr static int WIDTH{70};
10  PlayLevelButton(Scene& ParentScene)
11  : Button {
12      ParentScene,
13      "PLAY",
14      {
15        LEVEL_WIDTH - WIDTH - PADDING,
16        LEVEL_HEIGHT + PADDING,
17        WIDTH, 30
18      }
19    }
20  {}
21
22  void HandleLeftClick() override {
23    using namespace UserEvents;
24    SDL_Event E{SAVE_AND_PLAY_LEVEL};
25    SDL_PushEvent(&E);
26  }
27};
28}

Save Level Button

Now for the SaveLevelButton. A key usability feature is to only enable saving when changes have been made. We don't want the user clicking "Save" unnecessarily.

To implement this, the SaveLevelButton constructor sets the button's initial state to Disabled right after setting up the base class properties like text and position. It will be enabled later when a level edit occurs.

1// Editor/EditorButtons.h
2// ...
3
4namespace Editor{
5// ...
6
7class SaveLevelButton : public Button {
8public:
9  constexpr static int WIDTH{70};
10  SaveLevelButton(Scene& ParentScene)
11  : Button {
12      ParentScene,
13      "SAVE",
14      {
15        LEVEL_WIDTH - WIDTH
16          - PlayLevelButton::WIDTH - PADDING * 2,
17        LEVEL_HEIGHT + PADDING,
18        WIDTH, 30
19      }
20    }
21  {
22    SetState(ButtonState::Disabled);
23  }
24
25  // ...
26};
27}

The SaveLevelButton needs to dynamically change its state based on whether the level has been modified. It does this in its HandleEvent() function (again, calling the base class version first).

It listens for our new event type, LEVEL_EDIT. We'll later modify the Level class later to push this event whenever an actor is added, moved, or deleted.

When LEVEL_EDIT is detected, the SaveLevelButton enables itself by setting its state to Normal.

Conversely, saving or loading implies the current state is persisted, so there's nothing new to save immediately afterward. The button listens for LOAD_LEVEL, SAVE_LEVEL, and SAVE_AND_PLAY_LEVEL events. Upon detecting any of these, it sets its state back to Disabled.

1// Editor/EditorButtons.h
2// ...
3
4namespace Editor{
5// ...
6
7class SaveLevelButton : public Button {
8public:
9  // ...
10
11  void HandleEvent(const SDL_Event& E) {
12    Button::HandleEvent(E);
13    using namespace UserEvents;
14    if (E.type == LEVEL_EDIT) {
15      SetState(ButtonState::Normal);
16    } else if (
17      E.type == LOAD_LEVEL ||
18      E.type == SAVE_LEVEL ||
19      E.type == SAVE_AND_PLAY_LEVEL
20    ) {
21      SetState(ButtonState::Disabled);
22    }
23  }
24};
25}

Finally, when our SaveLevelButton is clicked, we’ll push a SAVE_LEVEL event, which will trigger our serialization once we add it:

1// Editor/EditorButtons.h
2// ...
3
4namespace Editor{
5// ...
6
7class SaveLevelButton : public Button {
8public:
9  // ...
10
11  void HandleLeftClick() override {
12    SDL_Event E{UserEvents::SAVE_LEVEL};
13    SDL_PushEvent(&E);
14  }
15};
16}

Connecting the Buttons

Now that we've defined our specialized button classes (LoadLevelButton, SaveLevelButton, PlayLevelButton), we need to create instances of them within our Editor::Scene.

We add member variables for three LoadLevelButtons (for levels 1, 2, and 3), one SaveLevelButton, and one PlayLevelButton to the private section of the Scene class.

We then ensure these buttons participate in the application loop by calling their respective HandleEvent(), Tick(), and Render() methods from within the corresponding Scene methods.

1// Editor/Scene.h
2// ...
3#include "EditorButtons.h"
4
5namespace Editor{
6class Scene {
7 public:
8  // ...
9  void HandleEvent(const SDL_Event& E) {
10    ActorShelf.HandleEvent(E);
11    TooltipWindow.HandleEvent(E);
12    CurrentLevel.HandleEvent(E);
13
14    LoadButton1.HandleEvent(E);
15    LoadButton2.HandleEvent(E);
16    LoadButton3.HandleEvent(E);
17    SaveButton.HandleEvent(E);
18    PlayButton.HandleEvent(E);
19  }
20
21  void Tick(float DeltaTime) {
22    ActorShelf.Tick(DeltaTime);
23    TooltipWindow.Tick(DeltaTime);
24    CurrentLevel.Tick(DeltaTime);
25
26    LoadButton1.Tick(DeltaTime);
27    LoadButton2.Tick(DeltaTime);
28    LoadButton3.Tick(DeltaTime);
29    SaveButton.Tick(DeltaTime);
30    PlayButton.Tick(DeltaTime);
31  }
32
33  void Render(SDL_Surface* Surface) {
34    ActorShelf.Render(Surface);
35    TooltipWindow.Render();
36    CurrentLevel.Render(Surface);
37
38    LoadButton1.Render(Surface);
39    LoadButton2.Render(Surface);
40    LoadButton3.Render(Surface);
41    SaveButton.Render(Surface);
42    PlayButton.Render(Surface);
43  }
44  
45  // ...
46
47 private:
48  // ...
49
50  LoadLevelButton LoadButton1{*this, 1};
51  LoadLevelButton LoadButton2{*this, 2};
52  LoadLevelButton LoadButton3{*this, 3};
53  SaveLevelButton SaveButton{*this};
54  PlayLevelButton PlayButton{*this};
55};
56}

Our buttons are now pushing events, but nothing is reacting to them yet. The Level class is the logical place to handle saving and loading operations, as it manages the actor data.

Let's add placeholder member functions Load(), Save(), and SaveAndPlay() to the Level class definition in Editor/Level.h. We also add an integer member LoadedLevel, initialized to 1, to keep track of which level file is currently active in the editor.

1// Editor/Level.h
2// ...
3
4namespace Editor {
5// ...
6
7class Level {
8 public:
9  // ...
10  void Load();
11  void Save();
12  void SaveAndPlay();
13 private:
14  // ...
15  int LoadedLevel{1};
16};
17}

Now we connect the events to these new functions within Level::HandleEvent() in Level.cpp. We add else if clauses to check for our new event types: LOAD_LEVEL, SAVE_LEVEL, and SAVE_AND_PLAY_LEVEL.

When LOAD_LEVEL is detected, we update the LoadedLevel member with the level number from the event's user.code field, and then call the Load() function. When SAVE_LEVEL is detected, we simply call Save().

For SAVE_AND_PLAY_LEVEL, we call SaveAndPlay(). Inside SaveAndPlay(), we first call Save() to ensure the level is persisted, and then we push another custom event, UserEvents::LAUNCH_LEVEL.

This new event signals that the game itself should launch, loading the level specified by LoadedLevel (attached via E.user.code).

1// Editor/Source/Level.cpp
2// ...
3
4void Level::HandleEvent(const SDL_Event& E) {
5  using namespace UserEvents;
Other Events (Unchanged)|Show
31  else if (E.type == LOAD_LEVEL) {
32    LoadedLevel = E.user.code;
33    Load();
34  } else if (E.type == SAVE_LEVEL) {
35    Save();
36  } else if (E.type == SAVE_AND_PLAY_LEVEL) {
37    SaveAndPlay();
38  }
39}
40
41// ...
42
43void Level::Load() {
44  // Coming soon...
45}
46
47void Level::Save() {
48  // Coming soon...
49}
50
51void Level::SaveAndPlay() {
52  Save();
53  SDL_Event E{UserEvents::LAUNCH_LEVEL};
54  E.user.code = LoadedLevel;
55  SDL_PushEvent(&E);
56}

Our SaveLevelButton needs to know when to become enabled. This happens whenever the user modifies the level by adding, moving, or deleting an actor. The Level::HandleDrop() function is called whenever an actor is successfully dropped (either cloned or moved).

Therefore, at the end of HandleDrop(), after the actor has been positioned or added, we push a UserEvents::LEVEL_EDIT event. This signals to the SaveLevelButton (and potentially other UI elements in the future) that the level state has changed and might need saving.

1// Editor/Source/Level.cpp
2// ...
3
4void Level::HandleDrop(Actor* DragActor) {
Previous Code (Unchanged)|Show
30  SDL_Event E{UserEvents::LEVEL_EDIT};
31  SDL_PushEvent(&E);
32}

Serialization Strategy

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.

Serializing the Level

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}

std::format() and Alternatives

The previous example uses std::format() to create our dynamic string representing the path to the level’s binary file. We covered std::format() in our introductory course here:

String Interpolation

A detailed guide to string formatting using C++20's std::format(), and C++23's std::print()

The std::format() function was added in C++20. In older language specifications, we can construct our string using this technique instead:

1std::string FileName{"Assets/Level"};
2FileName += std::to_string(LoadedLevel) += ".bin";

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:

Read/Write Offsets and Seeking

Learn how to manipulate the read/write offset of an SDL_RWops object to control stream interactions.

Serializing the Actors

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}

Adding Different Actors

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}

Preprocessor Macros

You might notice that the declarations for BlueBlock and GreenBlock share a lot of repetitive code - constructor declaration, Clone(), and GetActorType(). This is a fairly common scenario when dealing with designs that rely on run-time polymorphism.

When dealing with many similar classes, this boilerplate can become tedious and error-prone.

One way C++ offers to reduce this repetition is through preprocessor macros. We can define a function-like macro that takes the block type (e.g., BlueBlock, GreenBlock) and expands it out to the common code.

For example, we could define a macro like this:

1#define DECLARE_BLOCK_TYPE(BlockName)               \
2 public:                                            \
3  static constexpr int WIDTH{50};                   \
4  static constexpr int HEIGHT{25};                  \
5  BlockName(Scene& ParentScene, SDL_Rect Rect);     \
6  std::unique_ptr<Actor> Clone() const override {   \
7    return std::make_unique<BlockName>(*this);      \
8  }                                                 \
9  Config::ActorType GetActorType() const override { \
10    return Config::ActorType::BlockName;            \
11  }

Then, defining our block classes becomes much shorter:

1// Editor/Blocks.h
2#pragma once
3#include "Actor.h"
4
Macro Definition|Show
5#define DECLARE_BLOCK_TYPE(BlockName)
17
18namespace Editor {
19class BlueBlock : public Actor {
20  DECLARE_BLOCK_TYPE(BlueBlock)
21};
22
23class GreenBlock : public Actor {
24  DECLARE_BLOCK_TYPE(GreenBlock)
25};
26}

Preprocessor Definitions

Explore the essential concepts of C++ preprocessing, from understanding directives to implementing macros

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.

Overriding Serialization

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 Code

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

1#pragma once
2#include <iostream>
3#include <SDL.h>
4#include <string>
5#include <vector>
6
7namespace UserEvents{
8#ifdef WITH_EDITOR
9inline Uint32 ACTOR_DRAG{SDL_RegisterEvents(1)};
10inline Uint32 LOAD_LEVEL{SDL_RegisterEvents(1)};
11inline Uint32 SAVE_LEVEL{SDL_RegisterEvents(1)};
12inline Uint32 SAVE_AND_PLAY_LEVEL{
13  SDL_RegisterEvents(1)};
14inline Uint32 LEVEL_EDIT{SDL_RegisterEvents(1)};
15#endif
16inline Uint32 LAUNCH_LEVEL{
17  SDL_RegisterEvents(1)};
18}
19
20namespace Config {
21enum class ActorType : Uint8 {
22  Actor = 0,
23  BlueBlock = 1,
24  GreenBlock = 2,
25};
26
27inline const std::vector BUTTON_COLORS{
28  SDL_Color{15, 15, 15, 255},  // Normal
29  SDL_Color{15, 155, 15, 255}, // Hover
30  SDL_Color{225, 15, 15, 255}, // Active
31  SDL_Color{60, 60, 60, 255}   // Disabled
32};
33
34inline constexpr SDL_Color FONT_COLOR{
35  255, 255, 255, 255};
36
37inline const std::string FONT{
38  "Assets/Rubik-SemiBold.ttf"};
39}
40
41#ifdef WITH_EDITOR
42namespace Config::Editor {
43inline const Uint8 VERSION{1};
44// Level
45inline const int HORIZONTAL_GRID_SNAP{50};
46inline const int VERTICAL_GRID_SNAP{25};
47inline const Uint8 GRID_WIDTH{13};
48inline const Uint8 GRID_HEIGHT{6};
49inline const int LEVEL_WIDTH{
50  HORIZONTAL_GRID_SNAP * GRID_WIDTH};
51inline const int LEVEL_HEIGHT{
52  VERTICAL_GRID_SNAP * GRID_HEIGHT};
53inline constexpr SDL_Color LEVEL_BACKGROUND{
54  50, 50, 50, 255};
55
56// ActorMenu
57inline const int ACTOR_MENU_WIDTH{70};
58inline const int ACTOR_MENU_POSITION_X{LEVEL_WIDTH};
59inline const SDL_Color ACTOR_MENU_BACKGROUND{
60  15, 15, 15, 255};
61inline const int PADDING{10};
62
63// Window
64inline const std::string WINDOW_TITLE{"Editor"};
65inline const int WINDOW_WIDTH{
66  LEVEL_WIDTH + ACTOR_MENU_WIDTH};
67inline const int WINDOW_HEIGHT{LEVEL_HEIGHT + 50};
68inline const SDL_Color WINDOW_BACKGROUND{
69  35, 35, 35, 255};
70}
71#endif
72
73inline void CheckSDLError(
74  const std::string& Msg) {
75#ifdef CHECK_ERRORS
76  const char* error = SDL_GetError();
77  if (*error != '\0') {
78    std::cerr << Msg << " Error: "
79      << error << '\n';
80    SDL_ClearError();
81  }
82#endif
83}

1#pragma once;
2#include "Button.h"
3
4namespace Editor{
5using namespace Config::Editor;
6class LoadLevelButton : public Button {
7public:
8  constexpr static int WIDTH{40};
9  LoadLevelButton(Scene& ParentScene, int Level)
10  : Level{Level},
11    Button {
12      ParentScene,
13      std::to_string(Level),
14      {
15        PADDING * Level + WIDTH * (Level-1),
16        LEVEL_HEIGHT + PADDING,
17        WIDTH, 30
18      }
19    }
20  {
21    if (Level == 1) {
22      SetState(ButtonState::Active);
23    }
24  }
25
26  void HandleEvent(const SDL_Event& E) {
27    Button::HandleEvent(E);
28    if (E.type == UserEvents::LOAD_LEVEL) {
29      if (E.user.code == Level) {
30        SetState(ButtonState::Active);
31      } else {
32        SetState(ButtonState::Normal);
33      }
34    }
35  }
36
37  void HandleLeftClick() override {
38    SDL_Event E{UserEvents::LOAD_LEVEL};
39    E.user.code = Level;
40    SDL_PushEvent(&E);
41  }
42
43private:
44  int Level;
45};
46
47class PlayLevelButton : public Button {
48public:
49  constexpr static int WIDTH{70};
50  PlayLevelButton(Scene& ParentScene)
51  : Button {
52      ParentScene,
53      "PLAY",
54      {
55        LEVEL_WIDTH - WIDTH - PADDING,
56        LEVEL_HEIGHT + PADDING,
57        WIDTH, 30
58      }
59    }
60  {}
61
62  void HandleLeftClick() override {
63    using namespace UserEvents;
64    SDL_Event E{SAVE_AND_PLAY_LEVEL};
65    SDL_PushEvent(&E);
66  }
67};
68
69class SaveLevelButton : public Button {
70public:
71  constexpr static int WIDTH{70};
72  SaveLevelButton(Scene& ParentScene)
73  : Button {
74      ParentScene,
75      "SAVE",
76      {
77        LEVEL_WIDTH - WIDTH
78          - PlayLevelButton::WIDTH - PADDING * 2,
79        LEVEL_HEIGHT + PADDING,
80        WIDTH, 30
81      }
82    }
83  {
84    SetState(ButtonState::Disabled);
85  }
86
87  void HandleEvent(const SDL_Event& E) {
88    Button::HandleEvent(E);
89    using namespace UserEvents;
90    if (E.type == LEVEL_EDIT) {
91      SetState(ButtonState::Normal);
92    } else if (
93      E.type == LOAD_LEVEL ||
94      E.type == SAVE_LEVEL ||
95      E.type == SAVE_AND_PLAY_LEVEL
96    ) {
97      SetState(ButtonState::Disabled);
98    }
99  }
100
101  void HandleLeftClick() override {
102    SDL_Event E{UserEvents::SAVE_LEVEL};
103    SDL_PushEvent(&E);
104  }
105};
106}

1#pragma once
2#include <SDL.h>
3#include "ActorMenu.h"
4#include "ActorTooltip.h"
5#include "AssetManager.h"
6#include "Level.h"
7#include "Window.h"
8#include "EditorButtons.h"
9
10namespace Editor{
11class Scene {
12 public:
13  Scene(Window& ParentWindow)
14  : ParentWindow{ParentWindow}
15  {}
16
17  void HandleEvent(const SDL_Event& E) {
18    ActorShelf.HandleEvent(E);
19    TooltipWindow.HandleEvent(E);
20    CurrentLevel.HandleEvent(E);
21
22    LoadButton1.HandleEvent(E);
23    LoadButton2.HandleEvent(E);
24    LoadButton3.HandleEvent(E);
25    SaveButton.HandleEvent(E);
26    PlayButton.HandleEvent(E);
27  }
28
29  void Tick(float DeltaTime) {
30    ActorShelf.Tick(DeltaTime);
31    TooltipWindow.Tick(DeltaTime);
32    CurrentLevel.Tick(DeltaTime);
33
34    LoadButton1.Tick(DeltaTime);
35    LoadButton2.Tick(DeltaTime);
36    LoadButton3.Tick(DeltaTime);
37    SaveButton.Tick(DeltaTime);
38    PlayButton.Tick(DeltaTime);
39  }
40
41  void Render(SDL_Surface* Surface) {
42    ActorShelf.Render(Surface);
43    TooltipWindow.Render();
44    CurrentLevel.Render(Surface);
45
46    LoadButton1.Render(Surface);
47    LoadButton2.Render(Surface);
48    LoadButton3.Render(Surface);
49    SaveButton.Render(Surface);
50    PlayButton.Render(Surface);
51  }
52
53  AssetManager& GetAssets() {
54    return Assets;
55  }
56
57  bool HasMouseFocus() const {
58    return ParentWindow.HasMouseFocus();
59  }
60
61  Window& GetWindow() const {
62    return ParentWindow;
63  }
64
65  Level& GetLevel() {
66    return CurrentLevel;
67  }
68
69 private:
70  ActorMenu ActorShelf{*this};
71  ActorTooltip TooltipWindow{*this};
72  Level CurrentLevel{*this};
73  Window& ParentWindow;
74  AssetManager Assets;
75
76  LoadLevelButton LoadButton1{*this, 1};
77  LoadLevelButton LoadButton2{*this, 2};
78  LoadLevelButton LoadButton3{*this, 3};
79  SaveLevelButton SaveButton{*this};
80  PlayLevelButton PlayButton{*this};
81};
82}

1#pragma once
2#include <SDL.h>
3#include <memory>
4#include <vector>
5#include "Actor.h"
6
7namespace Editor {
8class Scene;
9using ActorPtr = std::unique_ptr<Actor>;
10using ActorPtrs = std::vector<ActorPtr>;
11
12class Level {
13 public:
14  Level(Scene& ParentScene)
15  : ParentScene{ParentScene} {}
16
17  void HandleEvent(const SDL_Event& E);
18  void HandleDrop(Actor* DragActor);
19  void Tick(float DeltaTime);
20  void Render(SDL_Surface* Surface);
21  bool HasMouseFocus() const;
22  void AddToLevel(ActorPtr NewActor);
23  SDL_Point SnapToGridPosition(int x, int y);
24  void DeleteAtPosition(
25    int x, int y, const Actor* Unless);
26  void Load();
27  void Save();
28  void SaveAndPlay();
29
30 private:
31  Scene& ParentScene;
32  ActorPtrs Actors;
33  Actor* SelectedActor{nullptr};
34  int LoadedLevel{1};
35
36  SDL_Rect Rect{
37    0, 0,
38    Config::Editor::LEVEL_WIDTH,
39    Config::Editor::LEVEL_HEIGHT
40  };
41};
42}

1#include <ranges>
2#include <format>
3#include "Editor/Level.h"
4#include "Editor/Scene.h"
5
6using namespace Editor;
7
8void Level::HandleEvent(const SDL_Event& E) {
9  using namespace std::views;
10  using namespace UserEvents;
11  for (ActorPtr& A : reverse(Actors)) {
12    if (A->HandleEvent(E)) {
13      break;
14    }
15  }
16
17  if (
18    E.type == SDL_MOUSEBUTTONDOWN &&
19    E.button.button == SDL_BUTTON_LEFT
20  ) {
21    SelectedActor = nullptr;
22  } else if (
23    E.type == SDL_KEYDOWN &&
24    E.key.keysym.sym == SDLK_DELETE &&
25    SelectedActor
26  ) {
27    std::erase_if(Actors,
28      [&](ActorPtr& Actor){
29        return Actor.get() == SelectedActor;
30      }
31    );
32
33    SelectedActor = nullptr;
34  } else if (E.type == LOAD_LEVEL) {
35    LoadedLevel = E.user.code;
36    Load();
37  } else if (E.type == SAVE_LEVEL) {
38    Save();
39  } else if (E.type == SAVE_AND_PLAY_LEVEL) {
40    SaveAndPlay();
41  }
42}
43
44void Level::Tick(float DeltaTime) {
45  for (ActorPtr& A : Actors) {
46    A->Tick(DeltaTime);
47  }
48}
49
50void Level::Render(SDL_Surface* Surface) {
51  auto [r, g, b, a]{
52    Config::Editor::LEVEL_BACKGROUND
53  };
54
55  SDL_FillRect(Surface, &Rect, SDL_MapRGB(
56    Surface->format, r, g, b));
57
58  for (ActorPtr& A : Actors) {
59    if (SelectedActor &&
60      A.get() == SelectedActor &&
61      SelectedActor->GetIsVisible()
62    ) {
63      auto [x, y, w, h]{
64        SelectedActor->GetRect()
65      };
66      SDL_Rect Rect{x - 1, y - 1, w + 2, h + 2};
67      SDL_FillRect(Surface, &Rect, SDL_MapRGB(
68        Surface->format, 255, 255, 255)
69      );
70    }
71    A->Render(Surface);
72  }
73}
74
75void Level::HandleDrop(Actor* DragActor) {
76  DragActor->SetIsVisible(true);
77  if (!HasMouseFocus()) {
78    return;
79  }
80
81  int MouseX, MouseY;
82  SDL_GetMouseState(&MouseX, &MouseY);
83  auto [GridX, GridY]{
84    SnapToGridPosition(
85      MouseX,
86      MouseY
87    )
88  };
89  DeleteAtPosition(GridX, GridY, DragActor);
90
91  using enum ActorLocation;
92  if (DragActor->GetLocation() == Menu) {
93    ActorPtr NewActor{DragActor->Clone()};
94    NewActor->SetPosition(GridX, GridY);
95    SelectedActor = NewActor.get();
96    AddToLevel(std::move(NewActor));
97  } else {
98    DragActor->SetPosition(GridX, GridY);
99    SelectedActor = DragActor;
100  }
101  SDL_Event E{UserEvents::LEVEL_EDIT};
102  SDL_PushEvent(&E);
103}
104
105void Level::AddToLevel(ActorPtr NewActor) {
106  NewActor->SetLocation(ActorLocation::Level);
107  Actors.push_back(std::move(NewActor));
108}
109
110bool Level::HasMouseFocus() const {
111  if (!ParentScene.HasMouseFocus()) {
112    return false;
113  }
114  int x, y;
115  SDL_GetGlobalMouseState(&x, &y);
116  auto [WinX, WinY]{
117    ParentScene.GetWindow().GetPosition()
118  };
119
120  if (
121    x >= WinX + Config::Editor::LEVEL_WIDTH ||
122    y >= WinY + Config::Editor::LEVEL_HEIGHT
123  ) {
124    return false;
125  }
126  return true;
127}
128
129SDL_Point Level::SnapToGridPosition(
130  int x, int y
131) {
132  using namespace Config::Editor;
133  int sx{HORIZONTAL_GRID_SNAP};
134  int sy{VERTICAL_GRID_SNAP};
135  return {
136    (x / sx) * sx,
137    (y / sy) * sy,
138  };
139}
140
141void Level::DeleteAtPosition(
142  int x, int y, const Actor* Unless
143) {
144  std::erase_if(Actors,
145    [&](const ActorPtr& Actor){
146      auto [ax, ay]{Actor->GetPosition()};
147      return
148        ax == x &&
149        ay == y &&
150        Actor.get() != Unless;
151     }
152  );
153}
154
155void Level::Load() {
156  // Coming soon...
157}
158
159void Level::Save() {
160  std::string FileName{
161    std::format("Assets/Level{}.bin", LoadedLevel)
162  };
163  SDL_RWops* Handle{SDL_RWFromFile(
164    FileName.c_str(), "wb")
165  };
166  if (!Handle) {
167    CheckSDLError("Saving Level");
168    Handle = SDL_RWFromFile(
169      FileName.c_str(), "w+b"
170    );
171  }
172
173  using namespace Config::Editor;
174  SDL_WriteU8(Handle, VERSION);
175  SDL_WriteU8(Handle, GRID_WIDTH);
176  SDL_WriteU8(Handle, GRID_HEIGHT);
177
178  SDL_WriteLE32(Handle, Actors.size());
179  for (const ActorPtr& A : Actors) {
180    A->Serialize(Handle);
181  }
182
183  SDL_RWclose(Handle);
184}
185
186void Level::SaveAndPlay() {
187  Save();
188  SDL_Event E{UserEvents::LAUNCH_LEVEL};
189  E.user.code = LoadedLevel;
190  SDL_PushEvent(&E);
191}