Setup and verification
GCC with C++20 and CMake 3.25 or newer, Qt 6.4 or newer. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.
Set CMAKE_PREFIX_PATH to your Qt installation if CMake cannot find Qt. Required FactoryForge source files are already included under vendor.
Verified on 2026-10-21 on Linux x86_64. Save and load in a temporary directory. The solution checks dirty, undo and preservation of the draft after a failed load.
This lesson connects the interface to the complete application layer. Its small example does not implement a second editor. It uses the same Document and repository classes as the graphical FactoryForge editor. Download the complete source ZIP from the project page before building it.
An editor draft and a running simulation are different states. Document owns the starting layout. Changes produce project values for its history. A saved comparison value identifies unsaved work. The simulation later starts from an independent copy. Moving vehicles therefore cannot silently change the saved map layout.
Package contents and individual files
- main.cpp
- CMakeLists.txt
- vendor/factory-forge/src/data/json_project_repository.cpp
- vendor/factory-forge/include/factory/data/json_project_repository.h
- vendor/factory-forge/include/factory/application/project_repository.h
- vendor/factory-forge/include/factory/core/project.h
- vendor/factory-forge/src/application/document.cpp
- vendor/factory-forge/include/factory/core/pathfinder.h
- vendor/factory-forge/include/factory/application/document.h
- vendor/factory-forge/src/core/puzzles.cpp
- vendor/factory-forge/include/factory/core/puzzles.h
- vendor/factory-forge/src/core/pathfinder.cpp
- vendor/factory-forge/src/core/project.cpp
- vendor/factory-forge/SOURCE.txt
- vendor/factory-forge/LICENSE
- solution/main.cpp
- run_checks.py
01Prepare the source snapshot
Extract the learning package. The required FactoryForge sources are included under vendor from the linked pinned revision. Run cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug and cmake --build build. This standalone check does not require an additional full project download.
cmake_minimum_required(VERSION 3.25)
project(DocumentLesson LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
get_filename_component(FACTORYFORGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/vendor/factory-forge" ABSOLUTE CACHE)
find_package(Qt6 6.4 REQUIRED COMPONENTS Core)
add_executable(lesson main.cpp
"${FACTORYFORGE_SOURCE_DIR}/src/core/project.cpp"
"${FACTORYFORGE_SOURCE_DIR}/src/core/pathfinder.cpp"
"${FACTORYFORGE_SOURCE_DIR}/src/core/puzzles.cpp"
"${FACTORYFORGE_SOURCE_DIR}/src/application/document.cpp"
"${FACTORYFORGE_SOURCE_DIR}/src/data/json_project_repository.cpp")
target_include_directories(lesson PRIVATE "${FACTORYFORGE_SOURCE_DIR}/include")
target_link_libraries(lesson PRIVATE Qt6::Core)
02Read the document model
The example creates a repository and Document. replace establishes a verified puzzle solution as the starting state. edit takes a change operation and first works on a copy. A failed edit does not modify the existing draft. The graphical editor applies the same principle to grid tools and settings.
#include "factory/application/document.h"
#include "factory/core/puzzles.h"
#include "factory/data/json_project_repository.h"
#include <QCoreApplication>
#include <QTemporaryDir>
#include <iostream>
int main(int argc, char **argv) {
QCoreApplication app(argc, argv);
auto repository = std::make_shared<factory::JsonProjectRepository>();
factory::Document document(repository);
document.replace(factory::makePuzzle(0, true));
document.edit(
[](factory::Project &project) { project.name = "Warehouse experiment"; });
document.undo();
document.redo();
QTemporaryDir directory;
if (!directory.isValid())
return 1;
const auto path = directory.filePath("example.factoryforge").toStdString();
document.save(path);
document.load(path);
std::cout << "project=" << document.project().name << '\n';
std::cout << std::boolalpha << "dirty=" << document.dirty() << '\n';
}
Run / check
cmake -S . -B build -G Ninja -DFACTORYFORGE_SOURCE_DIR=/path/to/factory-forge
cmake --build build
./build/lesson03Separate history from saved state
undo moves the history cursor back and redo moves it forward. A fresh edit after undo discards the incompatible redo branch. dirty compares the current project value with the last successfully saved value. Counting keystrokes since saving would incorrectly report the case where undo returns to that saved state.
04Inspect the repository
ProjectRepository declares load and save without depending on Qt. JsonProjectRepository handles JSON and QSaveFile. It validates the format version, dimensions, data types and unique IDs before accepting a file. Drafts may be incomplete. Before play, preflight additionally checks goals, budgets and reachable connections.
05Execute the round-trip
The example writes inside QTemporaryDir. This isolated temporary directory is unrelated to personal project files and is removed after execution. save updates the saved comparison value only after writing succeeds. load adopts only a completely read project. Configure, build and run using the commands below main.cpp.
project=Warehouse experiment dirty=false
06Inspect the verification
Save and load in a temporary directory. The solution checks dirty, undo and preservation of the draft after a failed load.Run python3 run_checks.py from the extracted package. Compare the test expectations with the exercise before opening the solution.
The example and automated solution pass. The stated manual checks remain separate.
07Check the complete editor
Start the app, draw a road, undo it and redo the change. Save, reopen and compare the stations. Type a new name in a custom map and cancel closing. Both input and the draft must remain available. Desktop and repository tests verify those promises.
Your exercise
Change the name again after saving. Check dirty, undo the new change and check it again. Then attempt to load a missing file.
Show the solution and explanation
The additional change makes dirty true. Undo returns to the saved project value and dirty becomes false. A failed load raises an error before replace is called. Catch the error and confirm that the previous name remains available. Keep using the isolated temporary directory rather than personal files.
#include "factory/application/document.h"
#include "factory/core/puzzles.h"
#include "factory/data/json_project_repository.h"
#include <QCoreApplication>
#include <QTemporaryDir>
#include <cassert>
#include <iostream>
int main(int argc, char **argv) {
QCoreApplication app(argc, argv);
auto repository = std::make_shared<factory::JsonProjectRepository>();
factory::Document document(repository);
document.replace(factory::makePuzzle(0, true));
document.edit(
[](factory::Project &project) { project.name = "Warehouse experiment"; });
document.undo();
document.redo();
QTemporaryDir directory;
if (!directory.isValid())
return 1;
const auto path = directory.filePath("example.factoryforge").toStdString();
document.save(path);
document.load(path);
assert(!document.dirty());
document.edit([](factory::Project &project) { project.name = "Changed"; });
assert(document.dirty());
document.undo();
assert(!document.dirty());
try {
document.load(path + ".missing");
return 2;
} catch (const std::exception &) {
}
assert(document.project().name == "Warehouse experiment");
std::cout << "project=" << document.project().name << '\n';
std::cout << std::boolalpha << "dirty=" << document.dirty() << '\n';
}
Project context and sources
The first six examples are standalone teaching programs. Lessons 7 through 9 use the complete FactoryForge source snapshot. Code, exercises and verified simplifications are explained separately. The project page provides a source ZIP while the GitHub repository is not yet published.