Regression net for behaviour-preserving refactoring

- game/digest: fingerprint of the whole game state (saved stream, unsaved
  run-time values, both random generators)
- season_sim: SIM_DIGEST=<file> writes one digest per desk; SIM_LEAGUE picks
  the start league
- tools/ci/compare_digests.py compares two directories of digest files
- ui_walk (tool): replays an input script against the UI flow and the
  production controller without a window, one picture/state fingerprint per step
- openbmh_ui --frames: the same fingerprints for its scripted mode

No change of game behaviour. Reference files live outside the repository.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
ClaudeandClaude committed 2026-11-10 11:16:52 +01:00
1 parent d9d408069e
commit 901f3dec1c
7 files changed
+399 -3

No files matched your search

+9
View File
@@ -267,6 +267,7 @@ add_library(bmhcore STATIC
src/game/bank_credit.cpp
src/game/career.cpp
src/game/save.cpp
src/game/digest.cpp
src/game/turn.cpp
src/game/turn_driver.cpp
)
@@ -513,6 +514,14 @@ if(MSVC)
target_compile_options(app_controller_tests PRIVATE /utf-8)
endif()
bmh_add_data_test(NAME app_controller_tests COMMAND app_controller_tests "${BMH_DATA}")
# Regression tool (not a test): replays an input script against the UI flow and the controller without a
# window and writes picture/state fingerprints per step (see tests/ui_walk.cpp).
add_executable(ui_walk tests/ui_walk.cpp ${BMH_APP_CONTROLLER_SOURCE} ${BMH_APP_SESSION_SDL_SOURCE})
target_link_libraries(ui_walk PRIVATE bmhui openbmh_audio ${BMH_SDL_TARGET})
if(MSVC)
target_compile_options(ui_walk PRIVATE /utf-8)
endif()
set(BMH_TEST_APP_DELAY_SETTINGS_TESTS_INPUT_1 "" CACHE PATH "External input 1 for app_delay_settings_tests; not distributed")
bmh_add_data_test(NAME app_desktop_input_tests COMMAND app_controller_tests "${BMH_DATA}" --desktop-input-only)
bmh_add_data_test(NAME app_advertising_input_tests COMMAND app_controller_tests "${BMH_DATA}" --advertising-input-only)
+59
View File
@@ -0,0 +1,59 @@
// SPDX-License-Identifier: GPL-3.0-only
// state_digest: see digest.hpp.
#include "game/digest.hpp"
#include "game/save.hpp"
namespace bmh {
namespace {
// FNV-1a, 64 bit: simple, stable across platforms and compilers (no std::hash).
struct Fnv {
uint64_t value = 0xcbf29ce484222325ull;
void byte(uint8_t b) { value = (value ^ b) * 0x100000001b3ull; }
// (integers are fed byte by byte, least significant first, so the result does not depend on
// the byte order of the machine)
void u64(uint64_t v) {
for (int i = 0; i < 8; i++) byte(uint8_t(v >> (i * 8)));
}
void i64(int64_t v) { u64(uint64_t(v)); }
};
} // namespace
uint64_t state_digest(const GameState& g, int32_t game_seed, uint32_t rand_seed) {
Fnv h;
// 1. everything that is saved, in the block order of the original
const Bytes stream = save_stream(g);
h.u64(stream.size());
for (uint8_t b : stream) h.byte(b);
// 2. the run-time values a savegame does not hold (GameState members marked "not saved")
h.i64(g.indoor);
h.i64(g.level);
h.i64(g.chance_rain);
h.i64(g.chance_temperature);
h.i64(g.last_shooter);
h.i64(g.last_pick_quality);
h.i64(g.live_scene);
h.u64(g.live_matches.size());
for (int team : g.live_matches) h.i64(team);
for (uint16_t home : g.sportschau_homes) h.u64(home);
for (uint8_t priority : g.sportschau_priorities) h.u64(priority);
h.i64(g.sportschau_selection_available);
h.i64(g.list_toggle);
h.i64(g.lineups_frozen);
h.i64(g.pools_open);
h.i64(g.autosave_months);
h.i64(g.autosave_month);
h.u64(g.date);
h.u64(g.season_start);
h.i64(g.season);
h.i64(g.development_balance);
h.i64(g.trend_rotation);
// 3. both random generators
h.i64(game_seed);
h.u64(rand_seed);
return h.value;
}
} // namespace bmh
+26
View File
@@ -0,0 +1,26 @@
// SPDX-License-Identifier: GPL-3.0-only
#pragma once
// A fingerprint of the complete game state, for behaviour-preserving refactoring.
//
// Two runs of the same career must produce the same digest after every turn. The digest covers
// - everything a savegame holds (the decrypted stream of save_stream: all state blocks and the
// four name pools), and
// - the run-time values that are not saved but steer later draws (the chance weather, the last
// shooter, the transfer list toggle, the autosave counters, ...).
// The states of the two random generators are passed in by the caller, because they do not belong
// to GameState.
//
// It is a regression tool only: the value has no meaning of its own and may change whenever the
// engine's behaviour is changed on purpose (then the reference files are simply recorded again).
#include <cstdint>
#include "game/state.hpp"
namespace bmh {
// FNV-1a (64 bit) over the saved stream and the unsaved run-time values of `g`, the game
// generator's seed and the Watcom generator's seed.
uint64_t state_digest(const GameState& g, int32_t game_seed, uint32_t rand_seed);
} // namespace bmh
+32 -3
View File
@@ -36,6 +36,29 @@ static void emit(std::string fields) {
std::cout << fields << ",\"step\":" << ++step << ",\"elapsed_ns\":" << elapsed << "}\n" << std::flush;
}
// --frames FILE: after every reported step one line with the screen name and two fingerprints
// (FNV-1a, 64 bit): of the rendered 320x240 picture (palette indices) and of the state JSON. A
// scripted walk through the screens (--save, --script) thereby becomes a regression net for
// refactoring of the drawing code: the same script must write the same file before and after.
static std::FILE* g_frames = nullptr;
static uint64_t fnv1a(const uint8_t* data, size_t size) {
uint64_t h = 0xcbf29ce484222325ull;
for (size_t i = 0; i < size; ++i) h = (h ^ data[i]) * 0x100000001b3ull;
return h;
}
static void write_frame(const ui::StartupFlow& screen, const std::string& state) {
static uint64_t frame = 0;
if (!g_frames) return;
const Image image = screen.render();
std::fprintf(g_frames, "%llu %s %dx%d picture %016llx state %016llx\n", static_cast<unsigned long long>(++frame),
screen.screen_name().c_str(), image.width, image.height,
static_cast<unsigned long long>(fnv1a(image.pixels.data(), image.pixels.size())),
static_cast<unsigned long long>(fnv1a(reinterpret_cast<const uint8_t*>(state.data()), state.size())));
std::fflush(g_frames);
}
static void report(const ui::StartupFlow& screen, ui::FlowResult result,
std::string_view input = {}) {
const char* request = result.request == ui::FlowRequest::new_career ? "new_career" :
@@ -49,6 +72,7 @@ static void report(const ui::StartupFlow& screen, ui::FlowResult result,
result.request == ui::FlowRequest::file_action ? "file_action" :
result.request == ui::FlowRequest::load_game ? "load_game" : "none";
auto state = screen.state_json();
write_frame(screen, state);
state.pop_back();
std::ostringstream out;
out << state << ",\"changed\":" << (result.changed ? "true" : "false")
@@ -76,13 +100,13 @@ static std::string pointer_input(std::string_view type, int x, int y) {
}
int main(int argc, char** argv) {
fs::path data = ".", dump, script, save, save_directory;
fs::path data = ".", dump, script, save, save_directory, frames;
std::optional<bool> indoor;
try {
for (int i = 1; i < argc; ++i) {
std::string arg = argv[i];
if (arg == "--help") {
std::puts("openbmh_ui --data BMH [--save original.FBM] [--save-directory dir] [--pitch-context outdoor|indoor] [--dump screen.bmp] [--script inputs.txt]\n"
std::puts("openbmh_ui --data BMH [--save original.FBM] [--save-directory dir] [--pitch-context outdoor|indoor] [--dump screen.bmp] [--script inputs.txt] [--frames fingerprints.txt]\n"
"Script: left X Y / right X Y / move X Y / hold X Y MS / text NAME / key ENTER|BACKSPACE|ESC|letter.\n"
"Script context injection: resume PATH (decimal original master IDs in observed selection order).\n"
"Native coordinates: 320x240. manager_confirmed waits for updated order; final new_career waits for engine.\n"
@@ -91,11 +115,12 @@ int main(int argc, char** argv) {
"Game changes remain pending until an explicit engine acknowledgement; RMT closes idle menus.");
return 0;
}
if (arg != "--data" && arg != "--dump" && arg != "--script" && arg != "--save" && arg != "--save-directory" && arg != "--pitch-context") throw FormatError("unknown option: " + arg);
if (arg != "--data" && arg != "--dump" && arg != "--script" && arg != "--save" && arg != "--save-directory" && arg != "--pitch-context" && arg != "--frames") throw FormatError("unknown option: " + arg);
if (++i == argc) throw FormatError("missing value for " + arg);
if (arg == "--data") data = argv[i];
if (arg == "--dump") dump = argv[i];
if (arg == "--script") script = argv[i];
if (arg == "--frames") frames = argv[i];
if (arg == "--save") save = argv[i];
if (arg == "--save-directory") save_directory = argv[i];
if (arg == "--pitch-context") {
@@ -105,6 +130,10 @@ int main(int argc, char** argv) {
}
}
if (save_directory.empty()) save_directory = data;
if (!frames.empty()) {
g_frames = std::fopen(frames.string().c_str(), "wb");
if (!g_frames) throw FormatError("cannot write the frame fingerprint file");
}
install_fixture_tables(load_le(ui::asset_path(data, "BMH.exe")));
ui::StartupFlow screen(data, save_directory);
if (indoor && save.empty()) throw FormatError("pitch context requires a reference save");
+22
View File
@@ -23,6 +23,7 @@
#include "app/career_session.hpp"
#include "game/desk_actions.hpp"
#include "game/digest.hpp"
#include "game/save.hpp"
#include "game/lineup.hpp"
#include "game/matchday.hpp"
@@ -194,6 +195,9 @@ int main(int argc, char** argv) {
choice.name = "SIM";
choice.master_club = argc > 3 ? std::atoi(argv[3]) : 0;
choice.strength = argc > 5 ? std::atoi(argv[5]) : 2;
// SIM_LEAGUE=<0..4>: the league the manager starts in (default 0, the first league), so that the
// regression careers also cover promotion and the lower leagues.
if (const char* start_league = std::getenv("SIM_LEAGUE")) choice.start_league = std::atoi(start_league);
std::string error;
if (!session.confirm_manager(options, choice, error)) throw std::runtime_error("manager: " + error);
ui::CareerInitializationResult init;
@@ -284,6 +288,22 @@ int main(int argc, char** argv) {
GameState& g = const_cast<GameState&>(session.state());
std::printf("career started: team %d, date %u, money %d\n", g.manager_teams.at(0), g.date, money(g, 0));
check_state(g, "start", checks);
// SIM_DIGEST=<file>: one line per desk with the fingerprint of the whole state and both
// random generators (game/digest.hpp). Two builds that behave the same write the same
// file; this is the regression net for behaviour-preserving refactoring. Reading the
// state for the digest draws no random number and changes nothing.
std::FILE* digest_file = nullptr;
if (const char* digest_path = std::getenv("SIM_DIGEST")) {
digest_file = std::fopen(digest_path, "wb");
if (!digest_file) throw std::runtime_error(std::string("cannot write SIM_DIGEST file ") + digest_path);
}
const auto write_digest = [&](int turn) {
if (!digest_file) return;
std::fprintf(digest_file, "turn %d day %u digest %016llx\n", turn, g.date,
static_cast<unsigned long long>(state_digest(g, session.game().seed(), session.rand().seed())));
std::fflush(digest_file);
};
write_digest(0);
bool listed_for_sale = false;
int ad_contracts = 0; // SIM_ADVERTISING: contracts accepted
for (; played < turns; played++) {
@@ -364,6 +384,7 @@ int main(int argc, char** argv) {
g_human_team = g.manager_teams.at(0);
check_results(session.last_turn_results(), when, checks, goals, matches);
check_state(g, when, checks);
write_digest(played + 1);
std::printf("%s: %s, place %d, money %d\n", when.c_str(), r.kind == TurnDeskKind::SeasonEndDesk ? "season end desk" : "desk",
table_position(g, g.manager_teams.at(0)), money(g, 0));
if (r.kind == TurnDeskKind::SeasonEndDesk) {
@@ -371,6 +392,7 @@ int main(int argc, char** argv) {
++seasons;
} // (the next kickoff runs the season change)
}
if (digest_file) std::fclose(digest_file);
if (const char* final_save = std::getenv("SIM_FINAL_SAVE")) {
WatcomRandom envelope(1); // Diagnostic export must not change either gameplay stream.
write_savegame(final_save, make_savegame(g, envelope));
+192
View File
@@ -0,0 +1,192 @@
// SPDX-License-Identifier: GPL-3.0-only
// ui_walk - regression tool for refactoring of the user interface: replays a fixed input script against
// the real UI flow and the real controller (no window) and writes one fingerprint line per step.
//
// A new career is started from the setup screen like a player does it (default options, first manager),
// with the given Watcom seed. Every script line is one input; its request is served by the production
// controller (app::serve_flow_request) with all presenters absent, so nothing waits for a window. After
// every step the tool writes
//
// <step> <screen name> picture <fnv1a of the 320x240 palette indices> state <fnv1a of the state JSON>
//
// The values mean nothing by themselves: a change that must not alter the UI has to reproduce the file
// written by the build before it, byte for byte. A step that throws or that the controller refuses is
// recorded as "error <text>" and the walk goes on (the same error must then appear again).
//
// The walk is not a faithful player: the SDL loop of the app also feeds timers and presentation
// acknowledgements that this tool does not. Some screens therefore refuse their requests or cannot be
// left; the script command "home" returns to the desk and, when that fails, starts the same career
// again (deterministic), so one stuck screen does not end the coverage of the others.
//
// Usage: ui_walk <BMH data dir> <script> <output file> [watcom seed=1]
// Script lines: left X Y | right X Y | double X Y | move X Y | hold X Y MS | key NAME | text T | home
// (native 320x240 coordinates; '#' starts a comment)
#include <cstdint>
#include <cstdio>
#include <filesystem>
#include <fstream>
#include <memory>
#include <optional>
#include <sstream>
#include <stdexcept>
#include <string>
#include "app/controller.hpp"
#include "ui/flow.hpp"
using namespace bmh;
namespace {
uint64_t fnv1a(const uint8_t* data, size_t size) {
uint64_t h = 0xcbf29ce484222325ull;
for (size_t i = 0; i < size; ++i) h = (h ^ data[i]) * 0x100000001b3ull;
return h;
}
// The flow, the session behind it and the output file of one walk.
struct Walk {
std::filesystem::path data, save_directory;
uint32_t seed = 1;
std::FILE* out = nullptr;
std::unique_ptr<ui::StartupFlow> flow;
std::unique_ptr<app::CareerSession> session;
uint64_t revision = 0;
openbmh::audio::Playback playback;
std::optional<uint64_t> audio_session;
uint64_t step = 0, restarts = 0;
void record(const std::string& error) {
++step;
if (!error.empty()) {
std::fprintf(out, "%llu error %s\n", static_cast<unsigned long long>(step), error.c_str());
return;
}
const Image image = flow->render();
const std::string state = flow->state_json();
std::fprintf(out, "%llu %s picture %016llx state %016llx\n", static_cast<unsigned long long>(step),
flow->screen_name().c_str(),
static_cast<unsigned long long>(fnv1a(image.pixels.data(), image.pixels.size())),
static_cast<unsigned long long>(fnv1a(reinterpret_cast<const uint8_t*>(state.data()), state.size())));
}
// One request: served by the production controller. Its answer (an error text for a refused
// request) is part of the fingerprint line.
void serve(const ui::FlowResult& result) {
try {
const std::string answer = app::serve_flow_request(*flow, result, session, data, save_directory, seed, revision,
playback, audio_session, false);
record(answer.empty() ? std::string() : "refused: " + answer);
} catch (const std::exception& e) {
record(std::string("exception: ") + e.what());
}
}
// A mouse click as the SDL loop of the app delivers it: the pressed look at the press of the left
// button, pointer_down() for the screens that react to the press itself (the same list as in
// src/app/main.cpp), then the click at the release.
void click(int x, int y, bool right) {
try {
if (!right && flow->press_hold(x, y)) record({});
if (flow->desktop() || flow->in_balance() || flow->in_desk_records() || flow->in_achievements() ||
flow->in_indoor_standings() || flow->in_reschedule_calendar() || flow->in_league_pairings() ||
flow->in_family_table() || flow->in_toto_calculator() || flow->in_stadium() || flow->in_environment() ||
flow->in_strengths() || flow->in_top_scorers() || flow->in_opportunities() || flow->in_statistics_menu() ||
flow->in_statistics_page() || flow->in_analytics() || flow->in_other_games() || flow->in_pitch() ||
flow->in_settings())
serve(flow->pointer_down(x, y, right));
serve(flow->click(x, y, right));
} catch (const std::exception& e) {
record(std::string("exception: ") + e.what());
}
}
// The desk itself is shown (desktop() alone is also true while a screen lies over it).
bool at_desk() const { return flow->screen_name() == "desktop"; }
// Setup screen -> first manager -> career start (the clicks of a player who accepts every default).
void start() {
session.reset();
revision = 0;
audio_session.reset();
flow = std::make_unique<ui::StartupFlow>(data, save_directory);
record({});
click(150, 215, false);
click(5, 225, true);
click(5, 225, true);
click(90, 169, false);
if (!at_desk()) throw std::runtime_error("the career start did not reach the desk");
}
// Back to the desk: right clicks and ESC as a player would try; a screen that cannot be left this
// way ends in a restart of the same career.
void home() {
for (int i = 0; i < 6 && !at_desk(); ++i) {
click(318, 2, true);
if (!at_desk()) {
try { serve(flow->send_key("ESC")); } catch (const std::exception& e) { record(std::string("exception: ") + e.what()); }
}
}
if (!at_desk()) {
++restarts;
std::fprintf(out, "restart from %s\n", flow->screen_name().c_str());
start();
}
}
};
} // namespace
int main(int argc, char** argv) {
if (argc < 4) {
std::printf("usage: ui_walk <BMH data dir> <script> <output file> [watcom seed]\n");
return 2;
}
try {
Walk walk;
walk.data = argv[1];
walk.seed = argc > 4 ? uint32_t(std::stoul(argv[4])) : 1u;
std::ifstream script(argv[2]);
if (!script) throw std::runtime_error("cannot read the script");
walk.out = std::fopen(argv[3], "wb");
if (!walk.out) throw std::runtime_error("cannot write the output file");
// Saves written by the walk (file dialog) go to a scratch directory, never into the game data.
walk.save_directory = std::filesystem::temp_directory_path() / "openbmh_ui_walk";
std::filesystem::remove_all(walk.save_directory);
std::filesystem::create_directories(walk.save_directory);
walk.start();
std::string line;
while (std::getline(script, line)) {
if (!line.empty() && line.back() == '\r') line.pop_back();
const auto first = line.find_first_not_of(" \t");
if (first == std::string::npos || line[first] == '#') continue;
std::istringstream row(line);
std::string command;
row >> command;
try {
if (command == "home") { walk.home(); continue; }
if (command == "key" || command == "text") {
std::string value;
std::getline(row, value);
if (!value.empty() && value[0] == ' ') value.erase(0, 1);
if (command == "key") walk.serve(walk.flow->send_key(value));
else walk.serve(ui::FlowResult{walk.flow->text(value)});
continue;
}
int x = 0, y = 0, ms = 0;
if (!(row >> x >> y)) throw std::runtime_error("bad script line: " + line);
if (command == "left") walk.click(x, y, false);
else if (command == "right") walk.click(x, y, true);
else if (command == "double") walk.serve(walk.flow->click(x, y, false, true));
else if (command == "move") walk.serve(ui::FlowResult{walk.flow->move(x, y)});
else if (command == "hold" && (row >> ms)) walk.serve(walk.flow->hold(x, y, ms));
else throw std::runtime_error("bad script line: " + line);
} catch (const std::exception& e) {
walk.record(std::string("exception: ") + e.what());
}
}
std::fclose(walk.out);
std::printf("%llu steps, %llu restarts, last screen %s\n", static_cast<unsigned long long>(walk.step),
static_cast<unsigned long long>(walk.restarts), walk.flow->screen_name().c_str());
return 0;
} catch (const std::exception& e) {
std::fprintf(stderr, "ui_walk: %s\n", e.what());
return 1;
}
}
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-only
"""Compare two directories of season_sim digest files.
season_sim writes, with SIM_DIGEST=<file>, one line per desk:
turn <n> day <date> digest <16 hex digits>
The digest is a fingerprint of the whole game state and of both random generators
(src/game/digest.hpp). A refactoring that does not change behaviour must reproduce every
line of every reference career. This script compares the *.digest files of a reference
directory with those of a candidate directory and reports, per career, the first desk
that differs.
Usage: compare_digests.py <reference dir> <candidate dir>
Exit code: 0 identical, 1 differences or missing files, 2 usage error.
"""
import pathlib
import sys
def main() -> int:
if len(sys.argv) != 3:
print(__doc__)
return 2
reference, candidate = (pathlib.Path(a) for a in sys.argv[1:])
names = sorted(p.name for p in reference.glob("*.digest"))
if not names:
print(f"no *.digest files in {reference}")
return 2
bad = 0
for name in names:
ref_lines = (reference / name).read_text().splitlines()
other = candidate / name
if not other.exists():
print(f"{name}: MISSING in the candidate directory")
bad += 1
continue
new_lines = other.read_text().splitlines()
first = next((i for i, (a, b) in enumerate(zip(ref_lines, new_lines)) if a != b), None)
if first is None and len(ref_lines) == len(new_lines):
print(f"{name}: identical ({len(ref_lines)} desks)")
continue
bad += 1
if first is None:
print(f"{name}: DIFFERENT length, reference {len(ref_lines)} desks, candidate {len(new_lines)}")
else:
print(f"{name}: DIFFERENT from line {first + 1}")
print(f" reference: {ref_lines[first]}")
print(f" candidate: {new_lines[first]}")
# a career that exists only in the candidate is not an error of the refactoring, but worth a note
for extra in sorted(p.name for p in candidate.glob("*.digest") if p.name not in names):
print(f"{extra}: only in the candidate directory (not compared)")
print("RESULT:", "identical" if bad == 0 else f"{bad} of {len(names)} careers differ")
return 0 if bad == 0 else 1
if __name__ == "__main__":
sys.exit(main())