Guardar y cargar una partida
Cómo guardar y cargar una partida utilizando las clases JSON o CBOR de Qt.
Muchos juegos ofrecen la función de guardar, de modo que el progreso del jugador a lo largo del juego se pueda guardar y cargar más adelante. El proceso de guardar una partida suele consistir en serializar las variables miembro de cada objeto del juego en un archivo. Se pueden utilizar muchos formatos para este fin, uno de los cuales es JSON. Con QJsonDocument, también tienes la posibilidad de serializar un documento en formato CBOR, lo cual es ideal si no quieres que el archivo guardado sea fácil de leer (aunque consulta «Análisis y visualización de datos CBOR» para saber cómo se puede leer), o si necesitas reducir el tamaño del archivo.
En este ejemplo, mostraremos cómo guardar y cargar un juego sencillo en formatos JSON y binario.
La clase «Character»
La clase «Character» representa a un personaje no jugador (NPC) en nuestro juego y almacena el nombre, el nivel y el tipo de clase del jugador.
Proporciona las funciones estáticas fromJson() y no estáticas toJson() para serializarse a sí misma.
Nota: Este patrón (fromJson()/toJson()) funciona porque los QJsonObjects pueden crearse independientemente de un QJsonDocument, y porque los tipos de datos que se (des)serializan aquí son tipos de valor, por lo que pueden copiarse. Al serializar a otro formato —por ejemplo, XML o QDataStream, que requieren pasar un objeto similar a un documento— o cuando la identidad del objeto es importante (las subclases deQObject, por ejemplo), otros patrones pueden resultar más adecuados. Consulte el ejemplo «dombookmarks» para XML y la implementación de ` QListWidgetItem::read()` y ` QListWidgetItem::write()` para una serialización idiomática de ` QDataStream `. Las funciones ` print() ` de este ejemplo son buenos ejemplos de serialización de ` QTextStream `, aunque, por supuesto, carecen de la parte de deserialización.
class Character
{
Q_GADGET
public:
enum ClassType { Warrior, Mage, Archer };
Q_ENUM(ClassType)
Character();
Character(const QString &name, int level, ClassType classType);
QString name() const;
void setName(const QString &name);
int level() const;
void setLevel(int level);
ClassType classType() const;
void setClassType(ClassType classType);
static Character fromJson(const QJsonObject &json);
QJsonObject toJson() const;
void print(QTextStream &s, int indentation = 0) const;
private:
QString mName;
int mLevel = 0;
ClassType mClassType = Warrior;
};Nos interesan especialmente las implementaciones de las funciones fromJson() y toJson():
Character Character::fromJson(const QJsonObject &json)
{
Character result;
if (const QJsonValue v = json["name"]; v.isString())
result.mName = v.toString();
if (const QJsonValue v = json["level"]; v.isDouble())
result.mLevel = v.toInt();
if (const QJsonValue v = json["classType"]; v.isDouble())
result.mClassType = ClassType(v.toInt());
return result;
}En la función fromJson(), creamos un objeto local de tipo Character result y asignamos valores a los miembros de result a partir del argumento QJsonObject. Se puede utilizar tanto QJsonObject::operator[]() como QJsonObject::value() para acceder a los valores del objeto JSON; ambas son funciones const y devuelven QJsonValue::Undefined si la clave no es válida. En concreto, las funciones is... (por ejemplo, QJsonValue::isString(), QJsonValue::isDouble()) devuelven false para QJsonValue::Undefined, por lo que podemos comprobar tanto la existencia como el tipo correcto en una sola consulta.
Si un valor no existe en el objeto JSON, o tiene un tipo incorrecto, tampoco escribimos en el miembro correspondiente de ` result `, conservando así cualquier valor que el constructor por defecto haya podido establecer. Esto significa que los valores por defecto se definen de forma centralizada en un único lugar (el constructor por defecto) y no es necesario repetirlos en el código de serialización (DRY).
Fíjate en el uso de la instrucción «if-with-initializer» de C++17 para separar el ámbito y la comprobación de la variable ` v`. Esto nos permite mantener un nombre de variable corto, ya que su ámbito es limitado.
Compáralo con el enfoque ingenuo que utiliza ` QJsonObject::contains()`:
if (json.contains("name") && json["name"].isString())
result.mName = json["name"].toString();que, además de ser menos legible, requiere un total de tres búsquedas (no, el compilador no las optimizará en una sola), por lo que es tres veces más lento y repite « "name" » tres veces (incumpliendo el principio DRY).
QJsonObject Character::toJson() const
{
QJsonObject json;
json["name"] = mName;
json["level"] = mLevel;
json["classType"] = mClassType;
return json;
}En la función toJson(), hacemos lo contrario que en la función fromJson(): asignamos valores del objeto Character a un nuevo objeto JSON que, a continuación, devolvemos. Al igual que con el acceso a los valores, hay dos formas de establecer valores en un QJsonObject: QJsonObject::operator[]() y QJsonObject::insert(). Ambas sobrescribirán cualquier valor existente en la clave indicada.
La clase Level
class Level
{
public:
Level() = default;
explicit Level(const QString &name);
QString name() const;
QList<Character> npcs() const;
void setNpcs(const QList<Character> &npcs);
static Level fromJson(const QJsonObject &json);
QJsonObject toJson() const;
void print(QTextStream &s, int indentation = 0) const;
private:
QString mName;
QList<Character> mNpcs;
};Queremos que cada uno de los niveles de nuestro juego cuente con varios PNJ, por lo que mantenemos un ` QList ` de objetos `Character`. También proporcionamos las conocidas funciones `fromJson()` y `toJson()`.
Level Level::fromJson(const QJsonObject &json)
{
Level result;
if (const QJsonValue v = json["name"]; v.isString())
result.mName = v.toString();
if (const QJsonValue v = json["npcs"]; v.isArray()) {
const QJsonArray npcs = v.toArray();
result.mNpcs.reserve(npcs.size());
for (const QJsonValue &npc : npcs)
result.mNpcs.append(Character::fromJson(npc.toObject()));
}
return result;
}Los contenedores se pueden leer y escribir en formato JSON utilizando QJsonArray. En nuestro caso, construimos un QJsonArray a partir del valor asociado a la clave "npcs". A continuación, para cada elemento QJsonValue de la matriz, llamamos a toObject() para obtener el objeto JSON del Character. A continuación, Character::fromJson() puede convertir ese QJSonObject en un objeto Character para añadirlo a nuestro array de PNJ.
Nota: Los contenedores asociados se pueden crear almacenando la clave en cada objeto de valor (si aún no está ahí). Con este enfoque, el contenedor se almacena como una matriz normal de objetos, pero el índice de cada elemento se utiliza como clave para reconstruir el contenedor al volver a leerlo.
QJsonObject Level::toJson() const
{
QJsonObject json;
json["name"] = mName;
QJsonArray npcArray;
for (const Character &npc : mNpcs)
npcArray.append(npc.toJson());
json["npcs"] = npcArray;
return json;
}De nuevo, la función toJson() es similar a la función fromJson(), salvo que funciona a la inversa.
La clase Game
Una vez definidas las clases «Character» y «Level», podemos pasar a la clase «Game»:
class Game
{
public:
enum SaveFormat { Json, Binary };
Character player() const;
QList<Level> levels() const;
void newGame();
bool loadGame(SaveFormat saveFormat);
bool saveGame(SaveFormat saveFormat) const;
void read(const QJsonObject &json);
QJsonObject toJson() const;
void print(QTextStream &s, int indentation = 0) const;
private:
Character mPlayer;
QList<Level> mLevels;
};En primer lugar, definimos la enumeración « SaveFormat ». Esto nos permitirá especificar el formato en el que se debe guardar el juego: « Json » o « Binary ».
A continuación, proporcionamos métodos de acceso para el jugador y los niveles. Después, exponemos tres funciones: newGame(), saveGame() y loadGame().
Las funciones read() y toJson() son utilizadas por saveGame() y loadGame().
Nota: A pesar de que ` Game ` es una clase de valor, suponemos que el autor quiere que un juego tenga identidad, al igual que la ventana principal. Por lo tanto, no utilizamos una función estática fromJson(), que crearía un nuevo objeto, sino una función read() que podemos invocar sobre objetos existentes. Existe una correspondencia 1:1 entre read() y fromJson(), en el sentido de que una puede implementarse en términos de la otra:
void read(const QJsonObject &json) { *this = fromJson(json); }
static Game fromObject(const QJsonObject &json) { Game g; g.read(json); return g; }Simplemente utilizamos lo que resulte más cómodo para quienes invocan las funciones.
void Game::newGame()
{
mPlayer = Character();
mPlayer.setName("Hero"_L1);
mPlayer.setClassType(Character::Archer);
mPlayer.setLevel(QRandomGenerator::global()->bounded(15, 21));
mLevels.clear();
mLevels.reserve(2);
Level village("Village"_L1);
QList<Character> villageNpcs;
villageNpcs.reserve(2);
villageNpcs.append(Character("Barry the Blacksmith"_L1,
QRandomGenerator::global()->bounded(8, 11), Character::Warrior));
villageNpcs.append(Character("Terry the Trader"_L1,
QRandomGenerator::global()->bounded(6, 8), Character::Warrior));
village.setNpcs(villageNpcs);
mLevels.append(village);
Level dungeon("Dungeon"_L1);
QList<Character> dungeonNpcs;
dungeonNpcs.reserve(3);
dungeonNpcs.append(Character("Eric the Evil"_L1,
QRandomGenerator::global()->bounded(18, 26), Character::Mage));
dungeonNpcs.append(Character("Eric's Left Minion"_L1,
QRandomGenerator::global()->bounded(5, 7), Character::Warrior));
dungeonNpcs.append(Character("Eric's Right Minion"_L1,
QRandomGenerator::global()->bounded(4, 9), Character::Warrior));
dungeon.setNpcs(dungeonNpcs);
mLevels.append(dungeon);
}Para configurar un nuevo juego, creamos al jugador y rellenamos los niveles y sus PNJ.
void Game::read(const QJsonObject &json)
{
if (const QJsonValue v = json["player"]; v.isObject())
mPlayer = Character::fromJson(v.toObject());
if (const QJsonValue v = json["levels"]; v.isArray()) {
const QJsonArray levels = v.toArray();
mLevels.clear();
mLevels.reserve(levels.size());
for (const QJsonValue &level : levels)
mLevels.append(Level::fromJson(level.toObject()));
}
}La función read() comienza sustituyendo al jugador por el que se ha leído del JSON. A continuación, vaciamos (clear()) la matriz de niveles para que, al llamar dos veces a loadGame() sobre el mismo objeto Game, no queden niveles antiguos sin eliminar.
A continuación, rellenamos la matriz de niveles leyendo cada Level desde un ` QJsonArray`.
QJsonObject Game::toJson() const
{
QJsonObject json;
json["player"] = mPlayer.toJson();
QJsonArray levels;
for (const Level &level : mLevels)
levels.append(level.toJson());
json["levels"] = levels;
return json;
}Guardar el juego en JSON es similar a guardar un nivel.
bool Game::loadGame(Game::SaveFormat saveFormat)
{
QFile loadFile(saveFormat== Json ? "save.json"_L1 : "save.dat"_L1);
if (!loadFile.open(QIODevice::ReadOnly)) {
qWarning("Couldn't open save file.");
return false;
}
QByteArray saveData = loadFile.readAll();
QJsonDocument loadDoc(saveFormat== Json
? QJsonDocument::fromJson(saveData)
: QJsonDocument(QCborValue::fromCbor(saveData).toMap().toJsonObject()));
read(loadDoc.object());
QTextStream(stdout) << "Se ha cargado la partida guardada de " << loadDoc["player"]["name"].toString()
<< " utilizando " << (saveFormat != Json ? "CBOR": "JSON") << "...\n";
return true;
}Al cargar una partida guardada en loadGame(), lo primero que hacemos es abrir el archivo de guardado según el formato en el que se guardó; "save.json" para JSON, y "save.dat" para CBOR. Mostramos un mensaje de advertencia y devolvemos false si no se ha podido abrir el archivo.
Dado que tanto QJsonDocument::fromJson() como QCborValue::fromCbor() aceptan un QByteArray, podemos leer todo el contenido del archivo de guardado en uno solo, independientemente del formato de guardado.
Tras crear el QJsonDocument, le indicamos al objeto Game que se lea a sí mismo y, a continuación, devolvemos true para indicar que la operación se ha realizado con éxito.
bool Game::saveGame(Game::SaveFormat saveFormat) const
{
QFile saveFile(saveFormat== Json ? "save.json"_L1 : "save.dat"_L1);
if (!saveFile.open(QIODevice::WriteOnly)) {
qWarning("Couldn't open save file.");
return false;
}
QJsonObject gameObject = toJson();
saveFile.write(saveFormat== Json ? QJsonDocument(gameObject).toJson()
: QCborValue::fromJsonValue(gameObject).toCbor());
return true;
}Como era de esperar, saveGame() se parece mucho a loadGame(). Determinamos la extensión del archivo en función del formato, mostramos una advertencia y devolvemos « false » si falla la apertura del archivo. A continuación, guardamos el objeto Game en un ` QJsonObject`. Para guardar el juego en el formato especificado, convertimos el objeto JSON en un ` QJsonDocument ` para una posterior llamada a ` QJsonDocument::toJson()`, o en un ` QCborValue ` para ` QCborValue::toCbor()`.
Poniéndolo todo en contexto
Ya estamos listos para entrar en main():
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
const QStringList args = QCoreApplication::arguments();
const bool newGame
= args.size() <= 1 || QString::compare(args[1], "load"_L1, Qt::CaseInsensitive) != 0;
const bool json
= args.size() <= 2 || QString::compare(args[2], "binary"_L1, Qt::CaseInsensitive) != 0;
Game game;
if (newGame)
game.newGame();
else if (!game.loadGame(json ? Game::Json : Game::Binary))
return 1;
// Game is played; changes are made...Dado que solo nos interesa demostrar la serialización de un juego con JSON, nuestro juego no es realmente jugable. Por lo tanto, solo necesitamos un QCoreApplication a y no tenemos bucle de eventos. Al iniciar la aplicación, analizamos los argumentos de la línea de comandos para decidir cómo iniciar el juego. Para el primer argumento, están disponibles las opciones «new» (por defecto) y «load». Cuando se especifica «new», se generará una nueva partida, y cuando se especifica «load», se cargará una partida guardada anteriormente. Para el segundo argumento, las opciones disponibles son «json» (por defecto) y «binary». Este argumento determinará en qué archivo se guardará y/o desde cuál se cargará. A continuación, suponemos que el jugador se lo ha pasado muy bien y ha avanzado mucho, modificando el estado interno de nuestros objetos Character, Level y Game.
QTextStream s(stdout);
s << "Game ended in the following state:\n";
game.print(s);
if (!game.saveGame(json ? Game::Json : Game::Binary))
return 1;
return 0;
}Cuando el jugador haya terminado, guardamos su partida. A efectos de demostración, podemos serializar en formato JSON o CBOR. Puedes examinar el contenido de los archivos en el mismo directorio que el ejecutable (o volver a ejecutar el ejemplo, asegurándote de especificar también la opción «load»), aunque el archivo de guardado binario contendrá algunos caracteres basura (lo cual es normal).
Con esto concluye nuestro ejemplo. Como puedes ver, la serialización con las clases JSON de Qt es muy sencilla y práctica. Las ventajas de utilizar ` QJsonDocument ` y similares en lugar de ` QDataStream`, por ejemplo, es que no solo se obtienen archivos JSON legibles para el ser humano, sino que también se tiene la opción de utilizar un formato binario si es necesario, sin necesidad de reescribir ningún código.
Véase también «Compatibilidad con JSON en Qt», «Compatibilidad con CBOR en Qt» y «Entrada y salida de datos».
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.