The introduced in the previous lesson provides a flexible way to manage variations among game entities by externalizing their common properties into data. This avoids a proliferation of C++ classes and makes game updates and content creation more accessible.

In this final lesson in the chapter, we put this theory into practice, combining it with the file I/O techniques covered previously. We will build the foundations of a system to load these type objects and their corresponding entities from external data, process that data, and use it to instantiate our C++ objects.

We'll use data serialized as text in this project. In the next chapter, we'll build a program using binary serialization, so we can establish experience in both approaches.

Starting Point

We'll build upon the Entity and MonsterType classes we created in the previous lesson. A complete version of that code is provided below, integrated into a minimal main() function that initializes SDL.

Files

src

Select a file to view its content

15,10: Rendering Goblin using art file: goblin.png
25,10: Goblin is transforming into a Dragon!
35,10: Rendering Dragon using art file: dragon.png

Reading Type Objects

Let's start with our serialized type objects. We'll represent our types as comma-separated values within a file called types.txt. An example collection of types might look something like this:

[output]/types.txt

1Goblin,3,100,15,goblin.png,Swarm
2Dragon,7,500,45,dragon.png,RangedSnipe

If you want to follow along, this file should be in the same directory as your compiled executable.

Using JSON

In the previous lesson, we were demonstrating the concept of serialized type objects using the friendlier JSON format:

1{
2  "Goblin": {
3    "name": "Goblin",
4    "level": 3,
5    "health": 100,
6    "damage": 15,
7    "art": "goblin.png",
8    "fightingStyle": "Swarm"
9  },
10  "Dragon": {
11    "name": "Dragon",
12    "level": 7,
13    "health": 500,
14    "damage": 45,
15    "art": "dragon.png",
16    "fightingStyle": "RangedSnipe"
17  }
18}

We could use that in our implementation instead of our more basic comma-separated rows. And, in a more complex project, perhaps we should.

However, writing the code to deserialize JSON is significantly more difficult. If we wanted to use JSON, we'd generally enlist the help of a third-party library. We have a on handling JSON using a popular library created by Niels Lohmann.

In our MonsterType struct, let's add a static function that will read our file, and return a std::vector of our MonsterType type objects. We'll create a Bestiary alias for this type:

src/MonsterType.h

1#pragma once
2#include <string>
3#include <vector>
4
5class Entity;
6struct MonsterType;
7using Bestiary = std::vector<MonsterType>;
8
9enum class FightingStyle { /*...*/ };
15
16struct MonsterType {
24
25  static Bestiary LoadMonsterTypes();
26};

Let's start our implementation by loading the entire types.txt file into a std::string, using techniques we covered earlier in the chapter. To keep things focused, we'll skip error checking in these examples:

src/MonsterType.cpp

1#include "MonsterType.h"
2#include <SDL3/SDL.h>
3#include <string>
4#include <vector>
5#include "Entity.h"
6
7Entity MonsterType::CreateInstance(
8  int x, int y
9) const {
10  return Entity{this, x, y};
11}
12
13Bestiary MonsterType::LoadMonsterTypes() {
14  std::string Base{SDL_GetBasePath()};
15  char* Raw{static_cast<char*>(
16    SDL_LoadFile((Base + "types.txt").c_str(), nullptr))
17  };
18  std::string Data(Raw);
19  SDL_free(Raw);
20
21  Bestiary MonsterTypes;
22  // TODO: Populate the array
23  // (implemented in next section)
24  return MonsterTypes;
25}

Deserializing Type Objects

Next, let's focus on populating the local MonsterTypes array within our function, so we can return all the types stored in our text file. Having loaded our serialized file, our Data string currently looks like this:

1Goblin,3,100,15,goblin.png,Swarm
2Dragon,7,500,45,dragon.png,RangedSnipe

To deserialize this into a collection of type objects, we'll do three things:

Firstly, we'll identify all of the line breaks in our string, and then create a substring for each line. For this example file, that will leave us with two strings:

"Goblin,3,100,15,goblin.png,Swarm"
"Dragon,7,500,45,dragon.png,RangedSnipe"

Then, for each of these strings, we create a substring for each of the comma-separated values. Each line will result in 6 substrings which, for our goblin example, will look like this:

"Goblin" (the name)
"3" (the level)
"100" (the health)
"15" (the damage)
"goblin.png" (the art file)
"Swarm" (the fighting style)

Finally, we need to create a MonsterType object using these values. This will involve converting the strings to the correct types that our MonsterType struct expects.

Splitting Strings into Tokens

Let's start by splitting a string into its substrings (or "tokens") based on a delimiter. To split our string into its lines, our delimiter will be the new line character, \\n. Then, to split each of those strings into the comma-separated values, we'll split on the comma , delimiter.

This string-splitting capability will be useful in multiple locations, so we'll create an inline function for it in a new Utilities.h file. This function uses the same techniques we covered in our earlier lesson on parsing data using a std::string:

src/Utilities.h

1#pragma once
2#include <string>
3#include <vector>
4
5namespace Utilities {
6inline std::vector<std::string> SplitString(
7  const std::string& Str, char Delimiter
8) {
9  std::vector<std::string> Tokens;
10  size_t StartPos{0};
11  size_t FindPos;
12
13  while (
14    (
15      FindPos = Str.find(Delimiter, StartPos)
16    ) != std::string::npos
17  ) {
18    Tokens.push_back(
19      Str.substr(StartPos, FindPos - StartPos)
20    );
21    StartPos = FindPos + 1;
22  }
23
24  // Don't forget the last token
25  if (StartPos <= Str.length()) {
26    Tokens.push_back(Str.substr(StartPos));
27  }
28
29  return Tokens;
30}
31}

We cover this in more detail in our lesson on using std::string.

Advanced

String Streams and `std::getline()`

Our SplitString() function can be implemented in a slightly simpler way using the standard library's string stream utility, in conjunction with std::getline(). Both are available within <sstream>:

1// Utilities.h
2#pragma once
3#include <sstream>
4#include <vector>
5#include <string>
6
7namespace Utilities{
8inline std::vector<std::string> SplitString(
9  const std::string& Str, char Delimiter
10) {
11  std::vector<std::string> Tokens;
12  std::string Token;
13  std::istringstream TokenStream(Str);
14
15  while (std::getline(
16    TokenStream, Token, Delimiter
17  )) {
18    Tokens.push_back(Token);
19  }
20  return Tokens;
21}
22}

We don't cover standard library streams here, but we have a full chapter on them in our advanced course, including a dedicated lesson on specifically.

Over in our MonsterType.cpp file, let's #include our new utility function and use it to first split our string into its lines based on the line break \n delimiter, and then split each of these lines into its 6 values based on the comma , delimiter:

src/MonsterType.cpp

1#include "MonsterType.h"
2#include <SDL3/SDL.h>
3#include <string>
4#include <vector>
5#include "Entity.h"
6#include "Utilities.h"
7
8Entity MonsterType::CreateInstance(
9  int x, int y
10) const {
11  return Entity{this, x, y};
12}
13
14Bestiary MonsterType::LoadMonsterTypes() {
15  std::string Base{SDL_GetBasePath()};
16  char* Raw{static_cast<char*>(
17    SDL_LoadFile((Base + "types.txt").c_str(), nullptr))};
18  std::string Data(Raw);
19  SDL_free(Raw);
20
21  Bestiary MonsterTypes;
22  using namespace Utilities;
23  for (std::string& Line : SplitString(Data, '\n')) {
24    std::vector<std::string> Fields{SplitString(Line, ',')};
25    // TODO: Create and push the type object
26    // (implemented in next section)
27  }
28  return MonsterTypes;
29}

Creating Type Objects

Within each iteration of our for loop, our Fields vector now has the 6 strings it needs to create the current type object - that is, each instance of MonsterType represented by the current line we're processing.

However, each of the fields is a std::string, so we need to convert it to the correct type expected by the MonsterType struct. In order, the fields correspond to:

MonsterType::Name - this is is a std::string, so we can use our deserialized value directly - no conversion needed
MonsterType::Level - this is an int, so we'll use std::stoi() to convert our string to an integer
MonsterType::Health - this is an int so we'll use std::stoi()
MonsterType::Damage - this is an int so we'll use std::stoi()
MonsterType::ArtFile - this is a std::string so no conversion needed
MonsterType::Style - this is a value from our FightingStyle enum. We'll create a function to map the std::string to the corresponding FightingStyle.

We don't have any float values in this example but, if we did, we'd convert the strings to the floating point value using std::stof().

Let's start by adding our std::string to FightingStyle enum mapper. This function is only needed in the MonsterType.cpp file, so we'll add it there. We'll put it in an anonymous namespace to prevent polluting our global namespace:

src/MonsterType.cpp

1// ...
2
3namespace{
4FightingStyle StringToFightingStyle(
5  const std::string& StyleStr
6) {
7  if (StyleStr == "BruteForce") {
8    return FightingStyle::BruteForce;
9  }
10  if (StyleStr == "RangedSnipe") {
11    return FightingStyle::RangedSnipe;
12  }
13  return FightingStyle::Swarm; // Default
14}
15}
16
17// ...

Finally, in LoadMonsterTypes(), we'll populate our MonsterTypes array before returning it:

src/MonsterType.cpp

1// ...
2
3Bestiary MonsterType::LoadMonsterTypes() {
4  std::string Base{SDL_GetBasePath()};
5  char* Raw{static_cast<char*>(
6    SDL_LoadFile((Base + "types.txt").c_str(), nullptr))};
7  std::string Data(Raw);
8  SDL_free(Raw);
9
10  Bestiary MonsterTypes;
11  using namespace Utilities;
12  for (std::string& Line : SplitString(Data, '\n')) {
13    std::vector<std::string> Fields{SplitString(Line, ',')};
14    MonsterTypes.push_back({
15      // Name
16      Fields[0], 
17      // Level
18      std::stoi(Fields[1]), 
19      // Health
20      std::stoi(Fields[2]),
21      // Damage
22      std::stoi(Fields[3]), 
23      // Art File
24      Fields[4], 
25      // Fighting Style
26      StringToFightingStyle(Fields[5])
27    });
28  }
29  return MonsterTypes;
30}

Over in main, let's confirm everything is working:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "MonsterType.h"
5#include "Entity.h"
6
7int main(int, char**) {
8  SDL_Init(0);
9  Bestiary Types{MonsterType::LoadMonsterTypes()};
10  std::cout << "Types: ";
11  for (const MonsterType& Type : Types) {
12    std::cout << Type.Name << ", ";
13  }
14  return 0;
15}

1Types: Goblin, Dragon,

Advanced

Enum Casting

In this section, we added a function for mapping strings to enum values. That function required us to check every possible value in the enum. This is fine for simple cases but, in more complex projects, we'd want to build a better system, or use a library to help us.

A popular choice is Magic Enum which, among other things, allows strings to be converted to the enum value with the same name. That would allow us to replace our StringToFightingStyle() function, and any similar function we might have needed in the future, with code that looks like this:

1// If Fields[5] is a string like "Swarm",
2// this will return FightingStyle::Swarm
3magic_enum::enum_cast<FightingStyle>(Fields[5])

Loading Dungeon Data

Now that our type objects are being loaded successfully, let's add some data to represent our dungeon. Each monster in our dungeon will be an Entity, whose Type is one of the type objects we deserialized.

Our serialized dungeon data might look something like below, where every line will represent an enemy, and the commas within each line delimit the type, x position, and y position of that enemy.

We'll call this file dungeon.txt and store it alongside our executable:

[output]/dungeon.txt

1Goblin,5,3
2Goblin,5,6
3Goblin,7,4
4Dragon,9,9

We can construct all the objects our dungeon requires, attaching the correct type object. For this example, we'll store them in a std::vector within a Dungeon instance.

Our Dungeon constructor will be responsible for populating its Enemies array. To help with that, we'll provide a reference to our Bestiary - the array of type objects we deserialized earlier:

src/Dungeon.h

1#pragma once
2#include <vector>
3#include "Entity.h"
4#include "MonsterType.h"
5
6struct Dungeon {
7  Dungeon(const Bestiary& Types) {
8    // Populate Enemies (next)
9  }
10
11  std::vector<Entity> Enemies;
12};

Deserializing Dungeons

To populate our Enemies from the serialized data, let's start by following the same pattern as before. We'll load our dungeon.txt file into a std::string. We'll then use our SplitString() utility to split that string into a vector of lines, and then each line into a vector of values:

src/Dungeon.h

1#pragma once
2#include <string>
3#include <vector>
4#include <SDL3/SDL.h>
5#include "Entity.h"
6#include "MonsterType.h"
7#include "Utilities.h"
8
9struct Dungeon {
10  Dungeon(const Bestiary& Types) {
11    std::string Base{SDL_GetBasePath()};
12    char* Raw{static_cast<char*>(
13      SDL_LoadFile((Base + "dungeon.txt").c_str(), nullptr)
14    )};
15    std::string Data(Raw);
16    SDL_free(Raw);
17
18    using namespace Utilities;
19    for (std::string& Line : SplitString(Data, '\n')) {
20      std::vector<std::string> Fields{SplitString(Line, ',')};
21      // Construct an entity and add to Enemies array (next)
22    }
23  }
24
25  std::vector<Entity> Enemies;
26};

This time, each entry in our Fields array has only three values but, as before, they're all std::strings. To construct an Entity, we need the following conversions:

Entity::Type is a MonsterType pointer. We'll need to convert the std::string to the appropriate pointer within our type object collection, which is the Bestiary provided to our constructor.
Entity::X_Pos is an int, so we'll convert the second std::string in Fields to an int using std::stoi().
Entity::Y_Pos is also an int, so we'll use std::stoi() on the third value in Fields too.

Let's start by creating a static function that will convert the type string to the corresponding MonsterType pointer from the bestiary. The MonsterType struct seems like the natural place for such a function:

src/MonsterType.h

1// ...
2
3struct MonsterType {
4  // ...
5
6  static const MonsterType* FindType(
7    const Bestiary& Types,
8    const std::string& DesiredType
9  ) {
10    for (const MonsterType& Type : Types) {
11      if (Type.Name == DesiredType) return &Type;
12    }
13    return nullptr;
14  }
15};

Back in our Dungeon constructor, let's use this new FindType() function, alongside std::stoi() , to populate our collection of enemies:

src/Dungeon.h

1#pragma once
2#include <string>
3#include <vector>
4#include <SDL3/SDL.h>
5#include "Entity.h"
6#include "MonsterType.h"
7#include "Utilities.h"
8
9struct Dungeon {
10  Dungeon(const Bestiary& Types) {
11    char* Raw{static_cast<char*>(
12      SDL_LoadFile("dungeon.txt", nullptr))};
13    std::string Data(Raw);
14    SDL_free(Raw);
15
16    using namespace Utilities;
17    for (std::string& Line : SplitString(Data, '\n')) {
18      std::vector<std::string> Fields{SplitString(Line, ',')};
19      Enemies.emplace_back(Entity{
20        // Type Object
21        MonsterType::FindType(Types, Fields[0]),
22        std::stoi(Fields[1]), // X Position
23        std::stoi(Fields[2]), // Y Position
24      });
25    }
26  }
27
28  std::vector<Entity> Enemies;
29};

Finally, let's create a Dungeon and confirm everything is working:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "MonsterType.h"
5#include "Entity.h"
6#include "Dungeon.h"
7
8int main(int, char**) {
9  SDL_Init(0);
10
11  Bestiary TypeObjects{
12    MonsterType::LoadMonsterTypes()
13  };
14  std::cout << "Types: ";
15  for (const MonsterType& Type : TypeObjects) {
16    std::cout << Type.Name << ", ";
17  }
18
19  Dungeon DragonsLair{TypeObjects};
20  std::cout << "\nEnemies in Dungeon: \n";
21  for (const Entity& E : DragonsLair.Enemies) {
22    std::cout << "  " << E.Type->Name
23      << " (" << E.X_Pos << ", "
24      << E.Y_Pos << ")\n";
25  }
26
27  return 0;
28}

1Types: Goblin, Dragon,
2Enemies in Dungeon:
3  Goblin (5, 3)
4  Goblin (5, 6)
5  Goblin (7, 4)
6  Dragon (9, 9)

Complete Code

A complete version of the program we created over the last two lessons is provided below:

Files

src

[output]

Select a file to view its content

Connecting to the Application Loop

In its current form, this program simply logs out the state of our Bestiary and Dungeon:

1Types: Goblin, Dragon, 
2Enemies in Dungeon:
3  Goblin (5, 3)
4  Goblin (5, 6)
5  Goblin (7, 4)
6  Dragon (9, 9)

One way to integrate this deserialization capability into a real project is to extend our Dungeon class with usual event-handling, rendering, and ticking functions we're familiar with from earlier in the course.

Our Dungeon class would then iterate over its children and call corresponding functions on the Entity class:

1// ...
2
3class Dungeon {
4public:
5  // ...
6
7  void Render(SDL_Surface* Surface) {
8    for (Entity& Enemy : Enemies) {
9      Enemy.Render(Surface);
10    }
11  }
12
13  void Tick() {
14    for (Entity& Enemy : Enemies) {
15      Enemy.Tick();
16    }
17  }
18
19  void HandleEvent(SDL_Event& Event) {
20    for (Entity& Enemy : Enemies) {
21      Enemy.HandleEvent(Event);
22    }
23  }
24
25  std::vector<Entity> Enemies;
26};

We'd then connect our Dungeon to the main application loop in the usual way by calling these functions at the appropriate times. For example:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5#include "MonsterType.h"
6#include "Dungeon.h"
7
8int main(int, char**) {
9  SDL_Init(SDL_INIT_VIDEO);
10  Window GameWindow;
11
12  Bestiary TypeObjects{
13    MonsterType::LoadMonsterTypes()
14  };
15  Dungeon DragonsLair{TypeObjects};
16
17  SDL_Event Event;
18  bool IsRunning = true;
19  while (IsRunning) {
20    while (SDL_PollEvent(&Event)) {
21      if (Event.type == SDL_EVENT_QUIT) {
22        IsRunning = false;
23      }
24      DragonsLair.HandleEvent(Event);
25    }
26
27    DragonsLair.Tick();
28
29    GameWindow.Render();
30    DragonsLair.Render();
31
32    GameWindow.Update();
33  }
34
35  SDL_Quit();
36  return 0;
37}

Summary

In this lesson, we put the type object pattern into action by reading MonsterType definitions and Entity configurations from external files. We used SDL_LoadFile() for file input and developed string parsing logic to convert text data into C++ MonsterType and Entity objects, creating a data-driven foundation for game content.

Key Takeaways:

External files (like types.txt, dungeon.txt) can define game object characteristics.
SDL's file utilities like SDL_LoadFile() help read data for parsing.
Parsing often involves splitting file content into smaller parts, often recursively (e.g., data into lines, and then lines into individual fields).
String tokens need conversion to specific data types like int using std::stoi(), or custom enums using helper functions or external libraries.
Loaded type objects can be stored (e.g., in a Bestiary) and used to instantiate game entities.
This method externalizes game data, making it easier to manage and modify without requiring C++ knowledge or project recompilation.
This idea can be extended further. Rather than our monster and dungeon state being loaded from files, our program could downloaded it from the internet instead, from a server we control. This concept is the foundation of multiplayer and "live service" games.

Types From Data Files

Starting Point

Files

Reading Type Objects

[output]/types.txt

src/MonsterType.h

src/MonsterType.cpp

Deserializing Type Objects

Splitting Strings into Tokens

src/Utilities.h

src/MonsterType.cpp

Creating Type Objects

src/MonsterType.cpp

src/MonsterType.cpp

src/main.cpp

Loading Dungeon Data

[output]/dungeon.txt

src/Dungeon.h

Deserializing Dungeons

src/Dungeon.h

src/MonsterType.h

src/Dungeon.h

src/main.cpp

Complete Code

Files

Connecting to the Application Loop

Summary

Game Development with SDL3