From 901f3dec1cbdb7b34ef729db3fbc5fdb10ca36a5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 11:16:52 +0100 Subject: [PATCH] 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= 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 --- CMakeLists.txt | 9 ++ src/game/digest.cpp | 59 +++++++++++ src/game/digest.hpp | 26 +++++ src/ui/main.cpp | 35 ++++++- tests/season_sim.cpp | 22 +++++ tests/ui_walk.cpp | 192 ++++++++++++++++++++++++++++++++++++ tools/ci/compare_digests.py | 59 +++++++++++ 7 files changed, 399 insertions(+), 3 deletions(-) create mode 100644 src/game/digest.cpp create mode 100644 src/game/digest.hpp create mode 100644 tests/ui_walk.cpp create mode 100644 tools/ci/compare_digests.py diff --git a/CMakeLists.txt b/CMakeLists.txt index 2876508..f61abfc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -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) diff --git a/src/game/digest.cpp b/src/game/digest.cpp new file mode 100644 index 0000000..fe90d03 --- /dev/null +++ b/src/game/digest.cpp @@ -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 diff --git a/src/game/digest.hpp b/src/game/digest.hpp new file mode 100644 index 0000000..a91d4f0 --- /dev/null +++ b/src/game/digest.hpp @@ -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 + +#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 diff --git a/src/ui/main.cpp b/src/ui/main.cpp index 34f2610..fe180ca 100644 --- a/src/ui/main.cpp +++ b/src/ui/main.cpp @@ -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(++frame), + screen.screen_name().c_str(), image.width, image.height, + static_cast(fnv1a(image.pixels.data(), image.pixels.size())), + static_cast(fnv1a(reinterpret_cast(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 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"); diff --git a/tests/season_sim.cpp b/tests/season_sim.cpp index 8b4503d..85e2b92 100644 --- a/tests/season_sim.cpp +++ b/tests/season_sim.cpp @@ -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(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=: 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(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)); diff --git a/tests/ui_walk.cpp b/tests/ui_walk.cpp new file mode 100644 index 0000000..fc1b254 --- /dev/null +++ b/tests/ui_walk.cpp @@ -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 +// +// picture state +// +// 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 " 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