diff --git a/src/app/action_transaction.hpp b/src/app/action_transaction.hpp index e1a8ba9..5457677 100644 --- a/src/app/action_transaction.hpp +++ b/src/app/action_transaction.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// All-or-nothing wrapper for one UI window action on a CareerSession (used by +// desktop_actions.cpp and window_actions.cpp). It snapshots the game state, the RNG and the +// revision counter, runs the action and, if the action returns false or throws, restores +// all three, so a rejected action leaves no half-applied change behind. +// apply_native() is the variant for owners that keep their state in CareerSession::state(). +// Header-only; owns no state of its own. #pragma once #include "app/career_session.hpp" diff --git a/src/app/audio.hpp b/src/app/audio.hpp index 134692e..46b59f8 100644 --- a/src/app/audio.hpp +++ b/src/app/audio.hpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Glue between the original-audio engine (src/audio/playback.hpp) and the app: builds the +// asset set from the game's sound containers and the frequency/operator tables read from the +// executable, derives the music/click/match-sound options from the saved settings bytes of +// the GameState, and sends sound commands only when the original sound path is ready. +// OriginalMouseSound is an SDL event watch that plays the click sound on each real mouse +// button press; it touches only the Playback object, never the GameState, because the +// watch can run on SDL's event thread. Header-only. #include "formats/executable_layout.hpp" #pragma once diff --git a/src/app/career_session.cpp b/src/app/career_session.cpp index 3439105..f0c91cb 100644 --- a/src/app/career_session.cpp +++ b/src/app/career_session.cpp @@ -1,4 +1,16 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of CareerSession (career_session.hpp): the engine side of the career. It +// owns the GameState, the two random generators, the turn driver and every "owner" of an +// open modal window (transfer editor, league table, bank, contracts, ...), and it is the +// only code the UI flow reaches into for game logic, through the controller. +// Request/acknowledge model: the UI sends a typed request that carries the revision it +// observed; the session checks that revision, applies the change (or rejects it with an +// error text), bumps the revision only when something changed and returns a projection or +// dispatch result. The front end then acknowledges that result (controller.cpp and the +// *Actions facades roll the session back if the acknowledgement fails). Live match events and +// notices flow the other way: the session calls presenter hooks synchronously and waits. +// This file also contains the checkpoint/restore code used by those rollbacks, the career +// start (options, manager join), save/load through the .FBM container and autosave. #include "formats/native_save_version.hpp" #include "formats/badge_policy.hpp" #include "game/calendar.hpp" diff --git a/src/app/controller.cpp b/src/app/controller.cpp index 545dea5..65ed8cc 100644 --- a/src/app/controller.cpp +++ b/src/app/controller.cpp @@ -1,4 +1,18 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the controller (controller.hpp): the request/acknowledge model between +// the UI flow, the controller and the session. +// 1. The SDL loop in main.cpp feeds input to ui::StartupFlow, which returns a FlowResult +// with a FlowRequest (desk action, transfer, friendly match, load game, ...). +// 2. serve_flow_request() is the single entry for that request. It rejects requests whose +// revision no longer matches (stale UI), or that are blocked by an open owner. +// 3. It forwards the request to the matching *Actions facade (desktop_actions.*, +// window_actions.*), which runs it on the CareerSession inside a rollback transaction. +// 4. The result is acknowledged back to the flow (for example flow.acknowledge_*, +// show_*), which then changes what is drawn; rendering alone never advances the engine. +// 5. A non-empty return string is an error message (main.cpp prints it); "career_complete" +// ends the program. The shared revision counter grows only when state really changed. +// Presenters (dialogs, live match frames) are optional hooks; an empty hook means the +// headless default. The anonymous namespace holds friendly-match and national-friendly helpers. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "app/controller.hpp" diff --git a/src/app/controller.hpp b/src/app/controller.hpp index bc483eb..16d317a 100644 --- a/src/app/controller.hpp +++ b/src/app/controller.hpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// The controller: the one synchronous boundary between the UI flow (ui::StartupFlow) and +// the engine session (CareerSession). The flow turns a click or key into a ui::FlowResult +// that carries a request; serve_flow_request() validates it against the current revision, +// calls the session, and acknowledges the outcome back to the flow. Everything the engine +// needs from the front end (dialogs, live match presentation, notices) is passed in as +// std::function "presenter" hooks, so tests can drive the same code without a window. +// Pairs with controller.cpp; the real hooks are supplied by main.cpp. #pragma once #include "app/career_session.hpp" diff --git a/src/app/debug_log.hpp b/src/app/debug_log.hpp index 7c71ec9..ce58548 100644 --- a/src/app/debug_log.hpp +++ b/src/app/debug_log.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Debug mode (command line -debug): a process-wide, mutex-protected log file plus numbered +// automatic savegames, both kept in one folder. State is a function-local static; every +// function is a no-op until init() has succeeded, so callers may log unconditionally. +// init() also redirects stderr into the same folder. Header-only. #pragma once #include diff --git a/src/app/desktop_actions.cpp b/src/app/desktop_actions.cpp index 39b5323..ee1729b 100644 --- a/src/app/desktop_actions.cpp +++ b/src/app/desktop_actions.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the desk-level action facades declared in desktop_actions.hpp. Each +// method checkpoints the relevant session owner, runs the request through CareerSession, +// lets the accept callback acknowledge the result to the UI, and rolls everything back via +// detail::apply_window if the callback returns false or throws. Errors are returned through +// the std::string& error parameter. The request/acknowledge flow as a whole is described +// at the top of controller.cpp. #include "formats/executable_layout.hpp" #include "app/desktop_actions.hpp" #include "app/action_transaction.hpp" diff --git a/src/app/desktop_actions.hpp b/src/app/desktop_actions.hpp index abc37ee..d4f3a6f 100644 --- a/src/app/desktop_actions.hpp +++ b/src/app/desktop_actions.hpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Application-boundary facades for desk-level windows: one small class per owner (desk +// settings, balance plan, other games, top scorers, opportunities, manager join, mailbox, +// menu layout, environment, reschedule, contracts, friendly matches). Each wraps a +// CareerSession reference; its apply() runs an action under a rollback transaction (see +// action_transaction.hpp), and open()/dispatch() take the UI request plus the shared +// revision counter and an optional "accept" callback that carries the front end's +// acknowledgement. Implemented in desktop_actions.cpp; window_actions.hpp holds the club windows. #pragma once #include "app/career_session.hpp" diff --git a/src/app/live_matchday_events.hpp b/src/app/live_matchday_events.hpp index bd01560..9b8d9b7 100644 --- a/src/app/live_matchday_events.hpp +++ b/src/app/live_matchday_events.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// SDL event helpers for the live match-day presentation, which runs while the engine is +// synchronously paused in its observer hook. live_matchday_board_side() turns a mouse press +// into a side (0 or 1) of the board only at the allowed minutes and screen intervals; +// pump_live_matchday_events() drains the SDL queue, reports a quit request and an ESC skip +// through its return value / out-parameter, and re-queues only non-interactive system events. +// Header-only; owns no state. #pragma once #include diff --git a/src/app/main.cpp b/src/app/main.cpp index a52bc5e..d4cfc9c 100644 --- a/src/app/main.cpp +++ b/src/app/main.cpp @@ -1,4 +1,19 @@ // SPDX-License-Identifier: GPL-3.0-only +// Entry point of the SDL front end (openbmh_play) and the owner of everything the player +// sees and hears: window, renderer, 320x240 indexed canvas, audio Playback, quit handling. +// It parses the command line, resolves the game data (src/launch), builds ui::StartupFlow and +// then runs the event loops. The request/acknowledge model works like this: +// - Input events go to the StartupFlow; a click or key may return a FlowResult carrying a +// FlowRequest (kickoff, desk action, transfer, save/load, ...). +// - main.cpp's handle() passes that result to app::serve_flow_request() (controller.cpp), +// together with the shared revision counter and a large set of presenter lambdas. +// - The controller asks the CareerSession (career_session.cpp, the engine side) to do the +// work and acknowledges the outcome to the flow; the engine may call a presenter lambda +// back, synchronously, to show a modal dialog or a live match frame, which runs its own +// nested event loop here until the player answers. +// - A non-empty message from the controller is printed to stderr; "career_complete" ends +// the program; the screen is redrawn only when the flow marks it dirty. +// The engine never draws and the UI never advances the engine on its own. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "app/start_screen.hpp" diff --git a/src/app/pitch_pointer.hpp b/src/app/pitch_pointer.hpp index 0e5d4c1..9dd0972 100644 --- a/src/app/pitch_pointer.hpp +++ b/src/app/pitch_pointer.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Mouse pointer for the pitch page. SDL owns the pointer position; the UI only hands over +// the original 11x11 pixel bitmap (121 ARGB values). PitchPointer builds an SDL colour +// cursor from it, enlarged by an integer scale derived from the window size in points, and +// caches it until the pixels or the scale change. set_default() sets the bitmap used on all +// other pages. Header-only; the cursor is freed in clear() / the destructor. #pragma once #include diff --git a/src/app/quit_confirmation.hpp b/src/app/quit_confirmation.hpp index 52f8f49..fa7fd69 100644 --- a/src/app/quit_confirmation.hpp +++ b/src/app/quit_confirmation.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Quit confirmation (a deliberate deviation from the original): a native message box in +// German or English whose default button is "Cancel". poll() and peep() wrap +// SDL_PollEvent / SDL_PeepEvents and drop SDL_QUIT events the user does not confirm. The +// dialog is shown from the UI thread only, and a dialog that fails to open counts as "not +// confirmed". The presenter is injectable (defaults to SDL_ShowMessageBox). Header-only. #pragma once #include diff --git a/src/app/start_screen.cpp b/src/app/start_screen.cpp index e89c3c3..c0354d3 100644 --- a/src/app/start_screen.cpp +++ b/src/app/start_screen.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of StartScreen (start_screen.hpp): decodes the embedded JPEG +// (start_screen_data.hpp) with stb_image into an RGB24 texture, switches the renderer's +// logical size to the image size while presenting and restores the previous logical size in +// the destructor. Errors are reported as std::runtime_error; the stb_image implementation +// is compiled into this file only (JPEG decoding, no stdio). #include "app/start_screen.hpp" #include "app/start_screen_data.hpp" #include diff --git a/src/app/start_screen.hpp b/src/app/start_screen.hpp index 5914971..71b797e 100644 --- a/src/app/start_screen.hpp +++ b/src/app/start_screen.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Start screen shown before the game data is loaded: one embedded picture drawn with its +// own renderer logical size, independent of the indexed game canvas. Owns the SDL +// texture; non-copyable. Implemented in start_screen.cpp, the image bytes come from +// start_screen_data.hpp. #pragma once struct SDL_Renderer; struct SDL_Texture; diff --git a/src/app/start_screen_data.hpp b/src/app/start_screen_data.hpp index 62812f2..2ba8399 100644 --- a/src/app/start_screen_data.hpp +++ b/src/app/start_screen_data.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Declares the embedded start screen artwork (JPEG bytes and their size); the definitions +// live in a separate data translation unit. Consumed only by start_screen.cpp. #pragma once #include namespace bmh::app { diff --git a/src/app/video_session.hpp b/src/app/video_session.hpp index fa00666..a885c3f 100644 --- a/src/app/video_session.hpp +++ b/src/app/video_session.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// RAII guard for SDL video: SDL_Init(SDL_INIT_VIDEO) in the constructor (throws +// std::runtime_error on failure) and SDL_Quit in the destructor. It must exist before any +// native file picker is opened (see the comment on the class). Non-copyable, header-only. #pragma once #include #include diff --git a/src/app/window_actions.cpp b/src/app/window_actions.cpp index d502d6d..fbe3306 100644 --- a/src/app/window_actions.cpp +++ b/src/app/window_actions.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the club and league window facades declared in window_actions.hpp. Each +// method validates the UI request against the session state, runs it on the CareerSession +// inside an apply() transaction (state, RNG and revision are restored on rejection or an +// exception) and hands the result to the front end's acknowledgement callback. Errors come +// back through the std::string& error parameter; see controller.cpp for the overall model. #include "formats/executable_layout.hpp" #include "app/window_actions.hpp" #include "app/action_transaction.hpp" diff --git a/src/app/window_actions.hpp b/src/app/window_actions.hpp index 9536b37..4a7f0ce 100644 --- a/src/app/window_actions.hpp +++ b/src/app/window_actions.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Application-boundary facades for the club and league windows: league table/pairings/ +// strengths, transfer market and offers, bank, stadium, desk actions and lineup. Same pattern +// as desktop_actions.hpp: a class per owner that wraps a CareerSession, offers apply() as a +// rollback transaction and takes the shared revision counter plus an acknowledgement +// callback from the front end. Implemented in window_actions.cpp, called from controller.cpp. #pragma once #include "app/career_session.hpp" diff --git a/src/audio/container.cpp b/src/audio/container.cpp index 31594fb..ac2fc04 100644 --- a/src/audio/container.cpp +++ b/src/audio/container.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of container.hpp: parse_container() checks the FORM/ALPTRAUM header and +// walks the adjacent little-endian chunks (no alignment byte) with bounds checks, filling +// a Container of offsets; decode_sample() and decode_original_cue() convert the bounded +// sample data to PCM. Pure functions on byte spans, no state; failures are reported through +// the std::string& error argument and a false result. #include "container.hpp" #include diff --git a/src/audio/container.hpp b/src/audio/container.hpp index c0fa09b..179016c 100644 --- a/src/audio/container.hpp +++ b/src/audio/container.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reader for the original sound container (a FORM/ALPTRAUM chunk wrapper) and for the PCM +// samples inside it. A Container only lists chunk ids and payload offsets; the payload bytes +// stay in the caller's buffer, which must outlive any use of the offsets. decode_sample() +// turns unsigned 8-bit samples into signed 16-bit mono PCM; decode_original_cue() resolves +// only the PCM-backed effects (original ids 17..22). Pairs with container.cpp; the PCM types +// are shared by mixer, playback, semantic cues and the music fallback. #pragma once #include diff --git a/src/audio/mixer.cpp b/src/audio/mixer.cpp index dc3ac4f..adb3985 100644 --- a/src/audio/mixer.cpp +++ b/src/audio/mixer.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of Mixer (mixer.hpp). Incoming PCM is resampled to the output rate with +// range and overflow checks and a total/per-voice byte ceiling (2 MiB overall, an eighth of +// that per voice); mix_block() sums music and active voices into the output block, applies +// the volume and advances the cursors (the music loops). #include "mixer.hpp" #include diff --git a/src/audio/mixer.hpp b/src/audio/mixer.hpp index c3d45c6..63a5ed3 100644 --- a/src/audio/mixer.hpp +++ b/src/audio/mixer.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Small PCM mixer used by the software (non-original) playback path: one looping music +// buffer plus up to 8 one-shot voices, all converted to the output rate when added. +// start_music_loop()/add_voice() may allocate; mix_block() only reads the prepared buffers +// and writes into caller-owned storage, so it is safe to call from the audio path. Owned +// by Playback (playback.hpp); the byte limits are in mixer.cpp. #pragma once #include "container.hpp" diff --git a/src/audio/music_fallback.cpp b/src/audio/music_fallback.cpp index bb65e65..08fb4a5 100644 --- a/src/audio/music_fallback.cpp +++ b/src/audio/music_fallback.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the synthetic matchday loop (music_fallback.hpp): a fixed 22050 Hz, +// 108 bpm, 8-bar sequence of bass, chord and lead notes defined by constant MIDI tables, +// rendered to mono PCM16. No game state or randomness is involved, so the output is the +// same on every run. #include "music_fallback.hpp" #include diff --git a/src/audio/music_fallback.hpp b/src/audio/music_fallback.hpp index 5c4d0e2..2fc56cb 100644 --- a/src/audio/music_fallback.hpp +++ b/src/audio/music_fallback.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Synthetic fallback matchday music: a deterministic 8-bar loop generated in code. It is +// presentation filler, not decoded original music and not tied to any original sound id. +// The result is a PcmSample that Playback::start_music_loop() can play; implemented in +// music_fallback.cpp. #pragma once #include "container.hpp" diff --git a/src/audio/original.cpp b/src/audio/original.cpp index 41fff6a..404bcc4 100644 --- a/src/audio/original.cpp +++ b/src/audio/original.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of OriginalSynth (original.hpp). The hidden State holds the parsed +// songs, tracks, channels, sample banks and the Nuked-OPL3 chip core (src/audio/third_party); +// tick() runs one sequencer step of the original timer interrupt, render() produces output +// samples from the chip and the PCM channel. load() validates every input and fails +// cleanly on malformed data; the register and sample observers exist only for offline +// validation (original_validation.cpp, sound_driver.cpp). #include "original.hpp" #include "container.hpp" #include "third_party/nuked-opl3/opl3.h" diff --git a/src/audio/original.hpp b/src/audio/original.hpp index dc8a8ef..cd163c2 100644 --- a/src/audio/original.hpp +++ b/src/audio/original.hpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Emulation of the original game's sound system (MIDI-style sequencer, OPL FM instruments +// and one Sound Blaster PCM channel) as OriginalSynth. The application reads the sound +// containers (S/2000..2003) and the frequency/operator tables from the user's executable +// and hands them in as OriginalAssets; this module knows nothing about game state, file +// layout, the simulation clock or random generators. command() takes the original sound ids +// (0 title, 1 desk, 2 intro, 3 crowd, 8 stop, 10..22 effects); render() fills PCM blocks +// without allocating. Implemented in original.cpp, driven by Playback and the audio tools. #pragma once #include diff --git a/src/audio/original_validation.cpp b/src/audio/original_validation.cpp index 30bdda6..f9c1b83 100644 --- a/src/audio/original_validation.cpp +++ b/src/audio/original_validation.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Validation executable for the original-sound emulation (original.hpp, playback.hpp). It +// needs the user's game data directory as its single argument, loads the executable tables +// and sound containers from it, and runs oracle checks on song/effect output, transitions, +// malformed input, option and mute handling, effect priorities and the audio callback +// lifecycle. With an empty argument it prints SKIP and exits with 77 (test skipped). +// Contains no game assets itself. #include "formats/executable_layout.hpp" #include "original.hpp" #include "playback.hpp" diff --git a/src/audio/playback.cpp b/src/audio/playback.cpp index 98d6468..69ea33d 100644 --- a/src/audio/playback.cpp +++ b/src/audio/playback.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of Playback (playback.hpp): opens the SDL audio device, feeds either the +// OriginalSynth from the SDL callback (original mode) or bounded blocks from the Mixer via +// pump() (software mode), and maps original ids and semantic cues to sound played on the +// device. Duplicate or out-of-order event ids are rejected before anything is played; +// shutdown() releases the device. #include "playback.hpp" #include diff --git a/src/audio/playback.hpp b/src/audio/playback.hpp index 9c6fc17..b453f94 100644 --- a/src/audio/playback.hpp +++ b/src/audio/playback.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Audio output device wrapper (SDL) and the single audio object the application uses. +// Playback owns the SDL device, a software Mixer (PCM effects, optional music loop) and the +// OriginalSynth (the full original driver, streamed from SDL's audio callback so modal +// windows cannot starve it). Cue requests carry a session id and an increasing event id +// chosen by the controller; submit() consumes each event once and returns a CueStatus. +// Mute and volume apply to both paths. Pairs with playback.cpp and app/audio.hpp. #pragma once #include "container.hpp" diff --git a/src/audio/semantic_cues.cpp b/src/audio/semantic_cues.cpp index 6b07735..f6b6e08 100644 --- a/src/audio/semantic_cues.cpp +++ b/src/audio/semantic_cues.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of synthesize_semantic_cue() (semantic_cues.hpp): builds each cue in code +// (the whistles from frequency sweeps with attack and release shaping) at 22050 Hz and +// clamps the result to 16-bit PCM. Pure and deterministic. #include "semantic_cues.hpp" #include diff --git a/src/audio/semantic_cues.hpp b/src/audio/semantic_cues.hpp index 6a9cba6..e54f912 100644 --- a/src/audio/semantic_cues.hpp +++ b/src/audio/semantic_cues.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Semantic sound cues (kickoff whistle, goal, full-time whistle) synthesized in code for +// use when no verified original effect is available. They are labels of intent, never +// original sound ids. The generator is deterministic mono PCM16 at 22050 Hz and has no +// dependency on game state, randomness or rendering; implemented in semantic_cues.cpp. #pragma once #include "container.hpp" diff --git a/src/audio/sound_driver.cpp b/src/audio/sound_driver.cpp index eef3b7c..14aeadb 100644 --- a/src/audio/sound_driver.cpp +++ b/src/audio/sound_driver.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Command line tool openbmh_sound for the audio module. It works either on one sound +// container file (play or export a sample, a test tone, or an original effect id as WAV) or, +// with --original DATA_DIR, on the user's game data through OriginalSynth (export a song or +// effect to WAV, or play ids through the real device). It also plays or exports the +// synthetic semantic cues and the fallback music loop. Own state only: parsed arguments. +// Bounds on seconds, loops and ids are checked before anything runs. #include "formats/executable_layout.hpp" #include "container.hpp" #include "music_fallback.hpp" diff --git a/src/audio/validation.cpp b/src/audio/validation.cpp index 150ddcb..eae04bd 100644 --- a/src/audio/validation.cpp +++ b/src/audio/validation.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Self-contained checks for the audio module that need no game data: container parsing +// against authored fixtures, sample and cue decoding, the mixer, the playback request +// rules and the synthetic music fallback. The fixtures are built in code and are not +// copied from any game asset. Returns non-zero on the first failed CHECK; companion of +// original_validation.cpp, which covers the original-driver emulation. #include "container.hpp" #include "music_fallback.hpp" #include "playback.hpp" diff --git a/src/cli/console/parser.cpp b/src/cli/console/parser.cpp index 7e6ea7f..2773d2a 100644 --- a/src/cli/console/parser.cpp +++ b/src/cli/console/parser.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the console line parser (parser.hpp): trimming, top-level splitting of +// the argument list (commas inside quotes or brackets do not split), parsing of one +// argument (positional or name=value), canonical name comparison that ignores case, '.' and +// '_', line classification, and the integer/bool converters for arguments. Pure functions; +// no console state. The console (console.cpp, windows_*.cpp) checks the argument types. #include "cli/console/parser.hpp" #include diff --git a/src/cli/json.cpp b/src/cli/json.cpp index c179b67..aacd0ac 100644 --- a/src/cli/json.cpp +++ b/src/cli/json.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of parse_json()/dump_json() (json.hpp): a small recursive-descent Parser +// over a string_view that reports the byte position in JsonError messages, UTF-8 handling +// for string escapes, and a serializer for the Json variant. No state beyond the parser's +// position in the input. #include "cli/json.hpp" #include diff --git a/src/cli/json.hpp b/src/cli/json.hpp index 149f65b..ff2d71f 100644 --- a/src/cli/json.hpp +++ b/src/cli/json.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Minimal JSON value type for the CLI protocol (no external library). A Json holds null, +// bool, a 64-bit integer, string, array or object (std::map) in one std::variant; the +// accessors return null pointers when the type does not match, so callers must check. +// Numbers are integers only. parse_json() throws JsonError on bad input; dump_json() writes +// compact text. Used by protocol.*, seat_hub.cpp and main.cpp; implemented in json.cpp. #pragma once #include diff --git a/src/cli/main.cpp b/src/cli/main.cpp index a1dfbac..1a585f0 100644 --- a/src/cli/main.cpp +++ b/src/cli/main.cpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Entry point of openbmh_cli, the headless front end without a window. Besides parsing the +// command line (Arguments) it offers several modes on top of the same engine: the JSON +// protocol on stdin/stdout (protocol.hpp) with --log/--replay, the console language +// (docs/CLI_CONCEPT) as plain session, replay, mailbox server (--serve), multi-seat server +// (--seats, SeatHub), TCP listener on 127.0.0.1 (--listen), and --send to hand one block to +// a running mailbox session. --data may be a game directory, the game's EXE or an archive +// (src/launch resolves it). All game logic stays in the engine; this file only moves lines. #include "cli/protocol.hpp" #include "cli/console/console.hpp" #include "cli/seat_hub.hpp" diff --git a/src/cli/protocol.cpp b/src/cli/protocol.cpp index a2fec6d..667793b 100644 --- a/src/cli/protocol.cpp +++ b/src/cli/protocol.cpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the JSON protocol (protocol.hpp). Protocol::handle() validates the +// request keys per command (check_keys / check_command_keys), then calls the CareerSession +// and the same projection functions the SDL front end uses (desk, table, mail, tactics, +// training, camp, bank, stadium, kickoff, save/load, ...), and wraps the result with the +// current revision. Errors are returned as {"ok": false, "error": ...}, never thrown to the +// caller. The "replay" flag lets a logged session be played again (saves may overwrite). +// text_request()/text_response() implement the one-line text form of the protocol. #include "formats/executable_layout.hpp" #include "cli/protocol.hpp" diff --git a/src/cli/protocol.hpp b/src/cli/protocol.hpp index d02b6d3..522230b 100644 --- a/src/cli/protocol.hpp +++ b/src/cli/protocol.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// The JSON line protocol of openbmh_cli (the non-console mode): one request object with a +// "cmd" field in, one response object ("ok", "revision", result or error) out. Protocol owns +// one app::CareerSession (created by "new" or "load") and the revision counter that every +// state-changing command must echo back, so stale requests are refused like in the UI +// flow. text_request()/text_response() translate a simple one-line text form to and from the +// same JSON. Implemented in protocol.cpp; Protocol::help() lists the commands. #pragma once #include "cli/json.hpp" diff --git a/src/cli/seat_hub.cpp b/src/cli/seat_hub.cpp index 5343d1a..3b97ee4 100644 --- a/src/cli/seat_hub.cpp +++ b/src/cli/seat_hub.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of SeatHub (seat_hub.hpp): routes the blocks of several clients into one +// console::Console. It runs a block as the seat's manager ("@k"), classifies each output +// line with Console::LineInfo, queues lines that concern other seats as their "meanwhile" +// feed, holds WaitTurn blocks until they can be answered, and holds the Run/Step of a live +// match until every seat has sent one. State per seat is a small Seat record; the game +// itself lives in the console. #include "cli/seat_hub.hpp" #include diff --git a/src/formats/badge_policy.hpp b/src/formats/badge_policy.hpp index 086fe09..7374424 100644 --- a/src/formats/badge_policy.hpp +++ b/src/formats/badge_policy.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Decides which club badge tokens the original draws as a fallback instead of an individual +// crest. The cut-off for foreign clubs differs between game editions, so it is read from one +// instruction in the loaded executable (layout::ForeignBadgeGateInstruction) and stored in the +// process-wide original_foreign_badge_end by install_original_badge_policy(). An executable +// that does not match the verified pattern falls back to 138. Header-only; the club +// selectors themselves stay in the database and savegame data. #pragma once #include "formats/executable_layout.hpp" diff --git a/src/formats/binary.cpp b/src/formats/binary.cpp index 81f5054..5fb51fe 100644 --- a/src/formats/binary.cpp +++ b/src/formats/binary.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the basic file helpers declared in binary.hpp: read_file() loads a whole +// file into a Bytes vector (FormatError if it cannot be opened) and iso646de_to_utf8() +// converts the game's ISO 646-DE strings ([ \ ] { | } ~ stand for the umlauts and the sharp s) +// to UTF-8. No state. #include "formats/binary.hpp" #include diff --git a/src/formats/fbm.cpp b/src/formats/fbm.cpp index a74240b..294b304 100644 --- a/src/formats/fbm.cpp +++ b/src/formats/fbm.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the .FBM savegame container (fbm.hpp): fbm_encrypt()/fbm_decrypt() are the +// stream cipher whose key changes by 0x29 per byte, and load_savegame() finds the "KRON_FBM" +// magic, splits the plain header from the encrypted stream, decrypts it and verifies the +// one-byte checksum, which is reported in Savegame::checksum_ok (not thrown). The decrypted +// stream is interpreted by savestate.cpp. Pure functions, no state. #include "formats/fbm.hpp" #include diff --git a/src/formats/font.cpp b/src/formats/font.cpp index 156755a..6c6c62b 100644 --- a/src/formats/font.cpp +++ b/src/formats/font.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the .FNT bitmap font loader and renderer (font.hpp): load_font() reads +// the header, the 1-bit glyph bitmap and the per-character location (and spacing) tables and +// checks that the file size matches exactly; Font::glyph(), text_width() and draw() look up +// glyphs (out-of-range characters use the last glyph) and draw them into an indexed Image. +// No state beyond the Font object. #include "formats/font.hpp" namespace bmh { diff --git a/src/formats/le.cpp b/src/formats/le.cpp index dd2091d..dd74b11 100644 --- a/src/formats/le.cpp +++ b/src/formats/le.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the executable image loader (le.hpp): load_le() reads the original +// DOS/4GW LE executable, places its objects at their link addresses and applies the internal +// fixups (FormatError for other files or external fixups). It also accepts the OpenBMH image +// format written by save_image(), so a translated image can replace the executable. +// LeImage::cstring() reads NUL-terminated strings from the image. No global state. #include "formats/le.hpp" #include diff --git a/src/formats/league_visibility.hpp b/src/formats/league_visibility.hpp index fd3c88c..143fa14 100644 --- a/src/formats/league_visibility.hpp +++ b/src/formats/league_visibility.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reads from the loaded executable how many league levels a player can see; the original +// separates internal domestic league slots from these visible levels. Throws +// std::invalid_argument when the stored constants fail the sanity check. Header-only, +// stateless; the address comes from executable_layout.hpp and the image from le.hpp. #pragma once #include "formats/executable_layout.hpp" #include "formats/le.hpp" diff --git a/src/formats/m3d.cpp b/src/formats/m3d.cpp index 402150a..bf4ef2f 100644 --- a/src/formats/m3d.cpp +++ b/src/formats/m3d.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the M3D.MAN master database loader (m3d.hpp). load_database() reads the +// file sequentially with a bounds-checked Reader: first the lengths of the four string pools +// (clubs, players, referees, stadiums), then the pools, the name offset tables and the raw +// record blocks, whose sizes depend on the DbCounts passed in. Several blocks are kept as raw +// bytes in the Database (raw_* fields). Throws FormatError on a truncated file. #include "formats/m3d.hpp" #include diff --git a/src/formats/native_save_version.hpp b/src/formats/native_save_version.hpp index 00ae626..e04fbfe 100644 --- a/src/formats/native_save_version.hpp +++ b/src/formats/native_save_version.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Accepted savegame version markers for the native (original-layout) save format. The FBM +// container (fbm.hpp) carries a version string; V2.24 and V3.7 share the same block order, +// while expanded careers use their own marker (O1.1) and layout. require_native_savegame() +// throws FormatError on a bad checksum or an unsupported marker; callers still validate the +// full state layout afterwards (savestate.hpp). Header-only. #pragma once #include "formats/fbm.hpp" #include diff --git a/src/formats/palette.cpp b/src/formats/palette.cpp index bbe9b1a..3e86298 100644 --- a/src/formats/palette.cpp +++ b/src/formats/palette.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the palette loader (palette.hpp). load_palette() reads a 256-entry, +// 6 bits per channel RGB file and converts it to 32-bit ARGB via vga_dac_rgb8(); +// load_optional_embedded_palette() reads the palette that may follow the RLE data of a VGA +// image file (std::nullopt if there is none); Palette::nearest() returns the index of the +// closest colour by squared RGB distance. FormatError on short or inconsistent files. #include "formats/palette.hpp" #include "formats/binary.hpp" diff --git a/src/formats/savestate.cpp b/src/formats/savestate.cpp index 47a0c61..e14d6ca 100644 --- a/src/formats/savestate.cpp +++ b/src/formats/savestate.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the savegame stream layout (savestate.hpp). save_layout() lists the +// blocks in the exact order the original wrote them, with sizes that are constants or depend +// on DbCounts; the SaveState constructor splits a decrypted stream along that list, reads +// the four string-pool trailer blocks and the optional OpenBMH extension, and throws +// FormatError if the sizes do not add up. append_save_extension() writes that extension. #include "formats/executable_layout.hpp" #include "formats/savestate.hpp" diff --git a/src/formats/textd.cpp b/src/formats/textd.cpp index 3362c7f..fef27f4 100644 --- a/src/formats/textd.cpp +++ b/src/formats/textd.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the TEXTD.BLK loader (textd.hpp): skips the 7-byte header, keeps the whole +// blob and splits it into NUL-terminated strings, recording each string's offset. Exactly +// TEXT_COUNT strings must be found, otherwise FormatError. No state. #include "formats/textd.hpp" #include "formats/binary.hpp" diff --git a/src/formats/vga.cpp b/src/formats/vga.cpp index 71ee2bd..b7a0682 100644 --- a/src/formats/vga.cpp +++ b/src/formats/vga.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the .VGA image support (vga.hpp): Image::blit() copies one indexed image +// into another with clipping, decode_vga() unpacks the run-length data (a byte of 0x80 or +// more is a run, below that a literal block) and checks the length fields and the single +// trailing byte, and load_vga() reads a file and decodes it. FormatError on malformed data. #include "formats/vga.hpp" namespace bmh { diff --git a/src/game/balance_plan.cpp b/src/game/balance_plan.cpp index feafc77..317f9e8 100644 --- a/src/game/balance_plan.cpp +++ b/src/game/balance_plan.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Business plan (balance plan) screen of a human manager: builds a draft of the plan rows +// (income, running costs, shares and loans, catering, ticket price), checks per-row maxima when +// the player edits a row and writes the accepted plan back on close. +// Reads and writes the manager records in GameState (manager_records); reads schedule, table and +// prediction data for the forecast. Draws no random numbers. +// Interface in balance_plan.hpp; monthly bookings of similar figures live in month.cpp / week.cpp. #include "formats/executable_layout.hpp" #include "game/environment.hpp" #include "game/balance_plan.hpp" diff --git a/src/game/bank_credit.cpp b/src/game/bank_credit.cpp index 33648c1..12f0679 100644 --- a/src/game/bank_credit.cpp +++ b/src/game/bank_credit.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Bank credit dialog: loans from the bank or from another manager, held in the per-manager loan +// matrix of the manager records. Implements the amount/fee/monthly-payment arithmetic (with the +// original's extended-precision rounding emulated in integers), draft editing with bounds, and +// the interest-rate change. Reads the manager records and executable tables via BankCreditContext; +// only change_bank_credit_interest writes GameState here. Draws no random numbers. +// Types are declared in bank_credit.hpp. #include "formats/executable_layout.hpp" #include "game/bank_credit.hpp" diff --git a/src/game/bank_credit.hpp b/src/game/bank_credit.hpp index 0e6ca4a..f2610d6 100644 --- a/src/game/bank_credit.hpp +++ b/src/game/bank_credit.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the bank credit dialog: context (rate table, liquidity, saved loan row), draft, +// edit and bounds types plus the projection/edit functions implemented in bank_credit.cpp. +// Case "bank" and case "another manager lends" share these types; projection and draft editing +// are read-only with respect to GameState. No random numbers are drawn. #pragma once #include diff --git a/src/game/bank_robbery.hpp b/src/game/bank_robbery.hpp index a72af0d..ceff38a 100644 --- a/src/game/bank_robbery.hpp +++ b/src/game/bank_robbery.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Per-manager guard against repeated bank robbery events: one blocked month key per manager, +// stored in an OpenBMH-owned extension block of the static memory in GameState (not in the +// original save fields). The month key function is implemented in week.cpp. +// Header-only accessors; no random numbers are drawn. #pragma once #include "game/state.hpp" #include diff --git a/src/game/calendar.cpp b/src/game/calendar.cpp index b49dabf..477f254 100644 --- a/src/game/calendar.cpp +++ b/src/game/calendar.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Calendar epoch (start year and weekday of the season calendar), read from the date setup code +// of the loaded executable image. Unknown or unverified setups are rejected with FormatError. +// Holds one process-wide installed epoch; reads no GameState and draws no random numbers. +// Declared in calendar.hpp. #include "game/calendar.hpp" #include "formats/executable_layout.hpp" #include "formats/le.hpp" diff --git a/src/game/calendar.hpp b/src/game/calendar.hpp index 6087ddd..e0b6f68 100644 --- a/src/game/calendar.hpp +++ b/src/game/calendar.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface for the calendar epoch (start year and weekday) used for date calculations. +// calendar_epoch_from_executable validates the loaded executable, install_calendar_rules makes it +// active, calendar_epoch returns it (a synthetic default for isolated test states). +// Implemented in calendar.cpp; no GameState access and no random numbers. #pragma once namespace bmh { class LeImage; diff --git a/src/game/career.cpp b/src/game/career.cpp index 8c77e8a..e3831d1 100644 --- a/src/game/career.cpp +++ b/src/game/career.cpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Start of a new career: league strength ranges read from the executable, generation of players +// (startup squads, the extra and market players), initial club moods and markets, the starting +// state built from the data files, plus new-manager setup (stadium, sponsors, competition blocks). +// Writes most of GameState (players, squad_slots, memory, manager records). +// Draws from both generators: WatcomRandom for attributes and levels, GameRandom for the +// reseeding done by stir_random and the mood reset. +// Interface in career.hpp; the season-wide steps follow in season.cpp. #include "formats/executable_layout.hpp" #include "game/career.hpp" #include "game/lineup.hpp" diff --git a/src/game/club_info.cpp b/src/game/club_info.cpp index b355162..bcfd4e8 100644 --- a/src/game/club_info.cpp +++ b/src/game/club_info.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Club information screen preparation: sets the line-up markers (first eleven / bench) in the +// club's squad_slots, clears markers of injured players and applies the chosen player category. +// Reads players and squad ranges, writes squad_slots in GameState. Draws no random numbers. +// Interface in club_info.hpp; line-up rules themselves are in lineup.cpp. #include "formats/executable_layout.hpp" #include "game/club_info.hpp" #include diff --git a/src/game/club_player_detail.cpp b/src/game/club_player_detail.cpp index 0f1666a..4dbb0fd 100644 --- a/src/game/club_player_detail.cpp +++ b/src/game/club_player_detail.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Player detail screen opened from a club squad or the market pool: resolves the selection to a +// squad slot, builds the context (loans, national nomination mode, pending offers) and runs the +// actions the screen offers (market value, add to national squad, offers). +// Reads and writes players, squad_slots and manager data in GameState. +// Draws from WatcomRandom (market value, adding to a squad) and reseeds both generators via +// stir_random. Interface in club_player_detail.hpp; related code in national.cpp and weekly.cpp. #include "formats/executable_layout.hpp" #include "game/club_player_detail.hpp" diff --git a/src/game/club_player_detail.hpp b/src/game/club_player_detail.hpp index b8a5126..cc971c8 100644 --- a/src/game/club_player_detail.hpp +++ b/src/game/club_player_detail.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the player detail screen: selection and context types (squad vs market pool row, +// loan data, national mode) and the functions implemented in club_player_detail.cpp. +// Context building is read-only; actions take both generators (GameRandom, WatcomRandom) and +// a MinuteReport, as documented at each declaration below. #pragma once #include diff --git a/src/game/cup.cpp b/src/game/cup.cpp index 9ff2caa..2bad8e7 100644 --- a/src/game/cup.cpp +++ b/src/game/cup.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Cup competitions: Masters qualification, replay lists, group tables and qualifiers, friendly +// preparation, national tournament end and the draw/advance step advance_cup for each round. +// Works on the cup entries in the static memory of GameState and on MatchGroup results. +// Draws from WatcomRandom (tie ordering) and GameRandom (shuffling the Masters field). +// Interface in cup.hpp; matchday_setup.cpp creates the matches, driver.cpp and season.cpp are neighbours. #include "formats/executable_layout.hpp" #include "game/cup.hpp" diff --git a/src/game/desk.cpp b/src/game/desk.cpp index eac27e6..34072cf 100644 --- a/src/game/desk.cpp +++ b/src/game/desk.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Entering a human manager's desk: desk button table per game mode, the random stir, the table +// prediction messages, the autosave hook and the manager's prestige (weighted sum of ratings and +// money). Reads and writes manager records and the mailbox in GameState. +// Draws from WatcomRandom (the four save draws) and reseeds both generators via stir_random. +// Interface in desk.hpp; called from turn.cpp before each desk. #include "formats/executable_layout.hpp" #include "game/desk.hpp" diff --git a/src/game/desk.hpp b/src/game/desk.hpp index 54a3d7b..cc88928 100644 --- a/src/game/desk.hpp +++ b/src/game/desk.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface for entering a human manager's desk (the part before the desk screen appears): +// enter_desk, the draws made when saving, and the prestige update. +// Implemented in desk.cpp; uses both generators (GameRandom, WatcomRandom) as documented below. #pragma once // Entering a human manager's desk (DeskDate, the part before the desk screen). diff --git a/src/game/desk_actions.cpp b/src/game/desk_actions.cpp index 4c4fcd7..90ad913 100644 --- a/src/game/desk_actions.cpp +++ b/src/game/desk_actions.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Actions a human manager can take at the desk: friendly match quotes and booking (including +// the national team variant), training camp configuration, and the transfer offer editor +// with bids and market previews. +// Reads and writes manager records, memory (friendly plan, calendar), players and squad_slots. +// Quotes draw from WatcomRandom on a staged copy that is committed only when accepted; booking +// also handles GameRandom. Interface in desk_actions.hpp; bids are settled in weekly.cpp. #include "formats/executable_layout.hpp" #include "game/desk_actions.hpp" diff --git a/src/game/driver.cpp b/src/game/driver.cpp index 8dc1be3..eced18e 100644 --- a/src/game/driver.cpp +++ b/src/game/driver.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Match day driver: plays the minutes of all match groups of a matchday in phases (first half, +// second half, extra phases), shows or hides screens per button table and handles the phase end +// (cup tie decisions, results, reseeding via stir_random). +// Works on MatchGroup lists, GameState and the MatchEngine of match_engine.cpp. +// Passes both generators on to the engine; itself only reseeds them at phase end. +// Interface in driver.hpp; neighbours are matchday_setup.cpp and season.cpp. #include "game/driver.hpp" #include diff --git a/src/game/environment.cpp b/src/game/environment.cpp index dbd36dd..1ae08a6 100644 --- a/src/game/environment.cpp +++ b/src/game/environment.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Club environment budgets of a human manager (youth teams, academy, co-trainer, doctor, +// physiotherapist): monthly cost per level, setting a level, and the youth team results and +// season handover. Reads and writes the budget and youth blocks in the static memory of GameState. +// advance_youth_teams draws from WatcomRandom; setting levels draws nothing. +// Interface in environment.hpp. #include "formats/executable_layout.hpp" #include "game/environment.hpp" #include diff --git a/src/game/environment.hpp b/src/game/environment.hpp index 9f99e66..73fa508 100644 --- a/src/game/environment.hpp +++ b/src/game/environment.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface for the club environment budgets (youth teams, academy, co-trainer, doctor, +// physiotherapist): item enum, monthly cost steps, state view and the functions implemented in +// environment.cpp. Setting a level draws no random number; youth match results use WatcomRandom. #pragma once #include #include diff --git a/src/game/highscore.cpp b/src/game/highscore.cpp index b85669f..8cebd5e 100644 --- a/src/game/highscore.cpp +++ b/src/game/highscore.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// High-score table of the game: computes a manager's score from his record (assets, history, +// titles), builds projections of the ranked table and reads/writes the five-row score file bytes. +// Reads manager records in GameState; the file images are passed in and out as bytes. +// Draws no random numbers. Interface in highscore.hpp. #include "formats/executable_layout.hpp" #include "game/highscore.hpp" diff --git a/src/game/highscore.hpp b/src/game/highscore.hpp index 4f99215..43a138c 100644 --- a/src/game/highscore.hpp +++ b/src/game/highscore.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the high-score table: row/table/projection types and the scoring and file +// functions implemented in highscore.cpp. Names keep the original text encoding. +// Reads GameState only; no random numbers are drawn. #pragma once #include diff --git a/src/game/human_buyer_sale.hpp b/src/game/human_buyer_sale.hpp index 145afca..5967d92 100644 --- a/src/game/human_buyer_sale.hpp +++ b/src/game/human_buyer_sale.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Types for completing the sale of a player to a human buyer (allocator gate, direct mode, +// result status). The unsaved observations named here are supplied by the caller; missing +// evidence means "unsupported", never an implicit default. +// The matching settle_human_buyer_sale function is implemented in weekly.cpp and takes WatcomRandom. #pragma once #include diff --git a/src/game/league_pairings.cpp b/src/game/league_pairings.cpp index 212d3de..11b66b4 100644 --- a/src/game/league_pairings.cpp +++ b/src/game/league_pairings.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// League pairings screen: the fixture view of a league round (filtered, postponed and per team), +// paging preferences and the computer tip (predicted results) for the shown round. +// Reads and writes GameState (memory preferences, squad data) through the screen owner struct. +// Computer tips use the game generator; closing the screen reseeds both generators via +// stir_random. Interface in league_pairings.hpp; the tip arithmetic is shared with source_tip.cpp. #include "formats/executable_layout.hpp" #include "game/league_pairings.hpp" diff --git a/src/game/league_pairings.hpp b/src/game/league_pairings.hpp index 698da0a..e2cd11d 100644 --- a/src/game/league_pairings.hpp +++ b/src/game/league_pairings.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the league pairings screen: constants, owner state, tip result and view types +// and the open/move/close functions implemented in league_pairings.cpp. No mutator here calls a +// presenter, advances a day or saves; generators are passed in by the caller where needed. #pragma once #include diff --git a/src/game/lineup.cpp b/src/game/lineup.cpp index 9152c95..f1c4d94 100644 --- a/src/game/lineup.cpp +++ b/src/game/lineup.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Line-up rules: position types per formation depth, player suitability values, automatic +// line-up for computer teams and the optimizer for human boards, plus preparing the line-up +// entry of a team. Reads players, formations and tactics boards; writes squad_slots and boards. +// Draws from WatcomRandom in two places of the automatic selection (see the rand calls below). +// Interface in lineup.hpp. #include "formats/executable_layout.hpp" #include "game/lineup.hpp" #include "formats/le.hpp" diff --git a/src/game/long_career.cpp b/src/game/long_career.cpp index dac20c5..ce7360a 100644 --- a/src/game/long_career.cpp +++ b/src/game/long_career.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Long-career extension: per-club player statistics (appearances, goals, assists) and title +// history archives kept in an OpenBMH extension block outside the original save fields, with +// encoding to and decoding from bytes for saving. +// Reads and writes GameState (memory extension, manager records). Draws no random numbers. +// Interface in long_career.hpp. #include "game/long_career.hpp" #include "game/state.hpp" #include "formats/executable_layout.hpp" diff --git a/src/game/long_career.hpp b/src/game/long_career.hpp index 0b10873..6042ec1 100644 --- a/src/game/long_career.hpp +++ b/src/game/long_career.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the long-career extension block (extension id, statistics and title history +// archive types, record/reset/swap functions and encode/decode) implemented in long_career.cpp. +// No random numbers are drawn. #pragma once #include #include diff --git a/src/game/match.cpp b/src/game/match.cpp index 565449f..923ccf0 100644 --- a/src/game/match.cpp +++ b/src/game/match.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Per-match environment values of the match engine: weather and temperature by month and region, +// crowd bonus for the home side, and the start-of-match tactics choice for computer teams. +// Reads GameState (clubs, month, spectators); the match state is filled by the caller. +// Draws from WatcomRandom (weather, crowd, substitution mode); the minute simulation itself is +// match_engine.cpp. Interface in match.hpp. #include "game/match.hpp" #include diff --git a/src/game/match_engine.cpp b/src/game/match_engine.cpp index 806c557..bf66b50 100644 --- a/src/game/match_engine.cpp +++ b/src/game/match_engine.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Minute-by-minute match simulation: chances and goals, shooter/assistant/taker picking, +// fouls, cards, injuries, substitutions and tactics changes, producing a MinuteReport per minute. +// Reads and writes the match state in GameState and the MatchGroup fixtures it was built with. +// Draws from both generators (WatcomRandom and GameRandom); the draw counts are compared with +// recordings in regression tests. +// MatchEngine is declared in match_engine.hpp; driver.cpp calls it. #include "formats/executable_layout.hpp" #include "game/match_engine.hpp" diff --git a/src/game/matchday.cpp b/src/game/matchday.cpp index 6740179..8d572e9 100644 --- a/src/game/matchday.cpp +++ b/src/game/matchday.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Matchday processing shared by all competitions: match results into club tables, cards and +// statistics, bonus payments, morale and player development after a match, league screens +// and rating of the manager, plus stir_random (reseeding both generators). +// Reads and writes GameState (players, tables, manager records, memory). +// Draws from GameRandom and WatcomRandom as named at each use below. +// Interface in matchday.hpp; the matches are set up in matchday_setup.cpp and played in driver.cpp. #include "formats/executable_layout.hpp" #include "game/environment.hpp" #include "game/matchday.hpp" diff --git a/src/game/matchday_setup.cpp b/src/game/matchday_setup.cpp index a266d50..826c262 100644 --- a/src/game/matchday_setup.cpp +++ b/src/game/matchday_setup.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Matchday setup: builds the match groups of a calendar day (descriptors, teams, weather, +// attendance and catering income, winter postponements, indoor tournament, live match choice, +// kick-off) and the football pools coupon. +// Reads and writes GameState (memory descriptors, squad_slots, manager records). +// Draws heavily from WatcomRandom and also from GameRandom (see the calls below). +// Interface in matchday_setup.hpp; results are handled in matchday.cpp and driver.cpp. #include "formats/executable_layout.hpp" #include "game/matchday_setup.hpp" #include "game/trace.hpp" diff --git a/src/game/messages.cpp b/src/game/messages.cpp index 0236187..d267f7c 100644 --- a/src/game/messages.cpp +++ b/src/game/messages.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Mailbox and text helpers: posting messages to managers, looking up message texts and +// formatting numbers with the original's flag conventions. +// Reads and writes the mailbox of GameState and reads the text tables installed from the +// executable. Draws no random numbers. Interface in messages.hpp. #include "formats/executable_layout.hpp" #include "game/messages.hpp" #include "game/schedule.hpp" diff --git a/src/game/month.cpp b/src/game/month.cpp index 71b4e61..65b55b0 100644 --- a/src/game/month.cpp +++ b/src/game/month.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Monthly processing: new transfer list entries and free agents, return of loans, monthly expenses +// and income, shares and loans, market value and contract demands/offers/bonuses, and the +// month change itself. +// Reads and writes GameState (transfer list in memory, squad_slots, players, manager records). +// Draws from WatcomRandom (list generation, demands); no GameRandom draws are made here. +// Interface in month.hpp; called from turn.cpp, weekly steps are in weekly.cpp. #include "formats/executable_layout.hpp" #include "game/environment.hpp" #include "game/month.hpp" diff --git a/src/game/national.cpp b/src/game/national.cpp index 5b36dcf..721032c 100644 --- a/src/game/national.cpp +++ b/src/game/national.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// National team: nomination of players, swapping the national coach record into the spare +// manager slot on international days, adding players to a squad and creating board entries. +// Reads and writes GameState (manager records, tactics boards, squad_slots, static bytes). +// Draws from WatcomRandom when creating board entries and values. Interface in national.hpp; +// called from turn.cpp. #include "formats/executable_layout.hpp" #include "game/national.hpp" diff --git a/src/game/other_games.cpp b/src/game/other_games.cpp index ff97713..622db65 100644 --- a/src/game/other_games.cpp +++ b/src/game/other_games.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// "Other games" desk view: rows of the results and fixtures of a competition round (group or +// knockout), linked pages and club metadata for display. A read-only projection of GameState +// and the loaded texts; the parameter named game is the GameState, not a random generator. +// Draws no random numbers. Interface in other_games.hpp. #include "formats/executable_layout.hpp" #include "game/other_games.hpp" diff --git a/src/game/other_games.hpp b/src/game/other_games.hpp index a42892b..e174fc1 100644 --- a/src/game/other_games.hpp +++ b/src/game/other_games.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the "other games" view: row, club metadata and page types and the const +// projection functions implemented in other_games.cpp. Read-only; no random numbers are drawn. #pragma once #include diff --git a/src/game/pending_offer.hpp b/src/game/pending_offer.hpp index a0bc2b3..4d6b6ce 100644 --- a/src/game/pending_offer.hpp +++ b/src/game/pending_offer.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Types for answering pending transfer offers manually (yes / no / unsupported answers, the +// question and dispatch context, allocator gate). Absence of an answer never means "no". +// Declarations only; the generators are passed in by the caller as shown below. #pragma once #include diff --git a/src/game/poach.cpp b/src/game/poach.cpp index bdc2c73..cb194b4 100644 --- a/src/game/poach.cpp +++ b/src/game/poach.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Poaching a player from another club: asking percentage of the club, remaining attempts per +// manager and the start and finish of a poach attempt. +// Reads and writes GameState (manager records attempt list, transfer list in memory, squad_slots). +// Draws from WatcomRandom. Interface in poach.hpp. #include "formats/executable_layout.hpp" #include "game/poach.hpp" diff --git a/src/game/prediction.cpp b/src/game/prediction.cpp index 17c3dfb..8dc86c4 100644 --- a/src/game/prediction.cpp +++ b/src/game/prediction.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Table prediction and season bonus: predicted final league position of a team, the season +// bonus paid to a manager and the expected bonus for players. +// Reads GameState (tables, tactics boards, manager records); season_bonus can book the payment. +// Draws no random numbers. Interface in prediction.hpp; included by desk.cpp and balance_plan.cpp. #include "formats/executable_layout.hpp" #include "game/prediction.hpp" diff --git a/src/game/rating.cpp b/src/game/rating.cpp index 9e554d0..33824d7 100644 --- a/src/game/rating.cpp +++ b/src/game/rating.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Player and team ratings: player_value weighs selected attributes (condition, technique, +// skills, form) and team_rating adds corrections for human managers' players and per-position terms. +// Reads players and tactics boards in GameState; the generators come from the RatingContext. +// Draws from WatcomRandom through that context in the human-board corrections and for teams +// without squads. Interface in rating.hpp. #include "game/rating.hpp" #include diff --git a/src/game/reality_ball.cpp b/src/game/reality_ball.cpp index 1505606..5ad8520 100644 --- a/src/game/reality_ball.cpp +++ b/src/game/reality_ball.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene, ball decisions: shot or pass choice and scoring, blockers on a path, duel and +// dribble outcomes and applying the result to the scene. +// Reads GameState (players, tactics) and the RealitySetup; mutates the owned scene structures. +// Draws from WatcomRandom (and takes GameRandom as a parameter). Interface in reality_ball.hpp; +// driven by reality_scene.cpp. #include "game/reality_ball.hpp" #include "game/reality_duel.hpp" diff --git a/src/game/reality_ball.hpp b/src/game/reality_ball.hpp index 0adab03..3b7a4d4 100644 --- a/src/game/reality_ball.hpp +++ b/src/game/reality_ball.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene ball logic: ball history, decision and outcome types and the +// decide/apply functions implemented in reality_ball.cpp. The functions take WatcomRandom (and +// GameRandom where declared). #pragma once #include "game/rating.hpp" diff --git a/src/game/reality_duel.cpp b/src/game/reality_duel.cpp index c8f9ce9..2498945 100644 --- a/src/game/reality_duel.cpp +++ b/src/game/reality_duel.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene, fouls and duels: decides whether a duel ends in a foul, whistle, card or +// injury, and the follow-up steps of the scene. Executes the forced event callback supplied by the +// caller instead of substituting a default. +// Reads GameState and the RealitySetup; draws from WatcomRandom. Interface in reality_duel.hpp. #include "game/reality_duel.hpp" #include diff --git a/src/game/reality_duel.hpp b/src/game/reality_duel.hpp index 5d5eadf..e316c67 100644 --- a/src/game/reality_duel.hpp +++ b/src/game/reality_duel.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene foul/duel logic: forced-event and sound callbacks, foul cue and +// result types, implemented in reality_duel.cpp. Draws use WatcomRandom as declared below. #pragma once #include diff --git a/src/game/reality_match.cpp b/src/game/reality_match.cpp index c58ccdc..cc96fa3 100644 --- a/src/game/reality_match.cpp +++ b/src/game/reality_match.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Bridge between one real match of the match engine and the Reality scene: validates that the +// engine, generators and fixture still own the scene, advances the scene and settles deferred +// substitution requests when it ends. +// Works on the MatchEngine state and its two generators; the draws are made by the scene code +// it calls (reality_scene.cpp). Interface in reality_match.hpp. #include "formats/executable_layout.hpp" #include "game/reality_match.hpp" diff --git a/src/game/reality_match.hpp b/src/game/reality_match.hpp index 6b13189..2771a4b 100644 --- a/src/game/reality_match.hpp +++ b/src/game/reality_match.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality match bridge: deferred request and RealityMatchScene types and the +// settle function implemented in reality_match.cpp. Requests survive scene end and run later. #pragma once #include "game/match_engine.hpp" diff --git a/src/game/reality_motion.cpp b/src/game/reality_motion.cpp index e3e9fed..0461575 100644 --- a/src/game/reality_motion.cpp +++ b/src/game/reality_motion.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene geometry and motion: direction quantisation on the pitch grid, projection to +// screen positions from the executable's tables, per-figure motion, paths and grid placement. +// Independent of GameState and draws no random numbers. Interface in reality_motion.hpp. #include "formats/executable_layout.hpp" #include "game/reality_motion.hpp" diff --git a/src/game/reality_motion.hpp b/src/game/reality_motion.hpp index 19f2eb3..71bba28 100644 --- a/src/game/reality_motion.hpp +++ b/src/game/reality_motion.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene motion layer: figure motion and path types, grid and the +// functions of reality_motion.cpp. Deliberately independent of GameState and both generators. #pragma once #include diff --git a/src/game/reality_movement.cpp b/src/game/reality_movement.cpp index da89bfb..967aadc 100644 --- a/src/game/reality_movement.cpp +++ b/src/game/reality_movement.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene, player movement: speed of a figure, movement context for the ball decision, +// attacker and defender moves and the defensive push. +// Reads GameState (players) and the RealitySetup; draws from WatcomRandom. +// Interface in reality_movement.hpp; driven by reality_scene.cpp. #include "game/reality_movement.hpp" #include diff --git a/src/game/reality_movement.hpp b/src/game/reality_movement.hpp index 381b6c5..bb3edd6 100644 --- a/src/game/reality_movement.hpp +++ b/src/game/reality_movement.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene movement layer: per-iteration move context and the attacker/ +// defender move functions implemented in reality_movement.cpp (WatcomRandom as declared below). #pragma once #include "game/reality_space.hpp" diff --git a/src/game/reality_reporter.cpp b/src/game/reality_reporter.cpp index 11373fc..299ee55 100644 --- a/src/game/reality_reporter.cpp +++ b/src/game/reality_reporter.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene, live reporter text: parses the reporter text templates (selectable variants +// and nested expressions) and evaluates them into commentary lines for the current action. +// Parsing draws nothing; evaluation draws from WatcomRandom. +// Reads the RealitySetup and executable text pools. Interface in reality_reporter.hpp. #include "formats/executable_layout.hpp" #include "game/reality_reporter.hpp" diff --git a/src/game/reality_reporter.hpp b/src/game/reality_reporter.hpp index 2730115..5b66297 100644 --- a/src/game/reality_reporter.hpp +++ b/src/game/reality_reporter.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality reporter: frame and state types and the initialise/report functions +// implemented in reality_reporter.cpp. The scene owner supplies the frame values. #pragma once #include diff --git a/src/game/reality_scene.cpp b/src/game/reality_scene.cpp index c7e5dac..024f3c6 100644 --- a/src/game/reality_scene.cpp +++ b/src/game/reality_scene.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene control loop: creates a scene from a fixture, advances it tick by tick +// (ball decision, reporter, movement of attackers and defenders), detects stop conditions +// (goal mouth, shot, boundary, forced event, user exit) and finishes it. +// Reads GameState and the RealitySetup; draws from WatcomRandom and passes both generators on to +// its parts. Interface in reality_scene.hpp; builds on reality_ball.cpp, reality_movement.cpp, +// reality_duel.cpp and reality_reporter.cpp. #include "formats/executable_layout.hpp" #include "game/reality_scene.hpp" diff --git a/src/game/reality_scene.hpp b/src/game/reality_scene.hpp index 77ad669..ed8303e 100644 --- a/src/game/reality_scene.hpp +++ b/src/game/reality_scene.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene: caller-owned context, stop reasons, scene, result and tick +// types and the create/advance/exit functions implemented in reality_scene.cpp. #pragma once #include "game/reality_duel.hpp" diff --git a/src/game/reality_setup.cpp b/src/game/reality_setup.cpp index 32349d7..84497b6 100644 --- a/src/game/reality_setup.cpp +++ b/src/game/reality_setup.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene setup: finds the manager of a team, derives the formations on the pitch grid and +// places the players of both teams with their positions, card values and movement limits. +// Reads GameState (tactics, formations, players). The setup function takes both generators as +// parameters. Interface in reality_setup.hpp; used by reality_scene.cpp. #include "formats/executable_layout.hpp" #include "game/reality_setup.hpp" diff --git a/src/game/reality_setup.hpp b/src/game/reality_setup.hpp index 39aae44..943393c 100644 --- a/src/game/reality_setup.hpp +++ b/src/game/reality_setup.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene setup: formations, placement and RealitySetup types and the +// functions implemented in reality_setup.cpp. #pragma once #include "game/reality_motion.hpp" diff --git a/src/game/reality_space.cpp b/src/game/reality_space.cpp index 9fc7400..7c04f00 100644 --- a/src/game/reality_space.cpp +++ b/src/game/reality_space.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality scene spatial decisions: paths in the penalty box, whether a cell is on a path, +// offside, nearby players and penalty area occupancy, with side and bounds validation. +// Reads the RealitySetup; sampling among line occupants uses WatcomRandom, not GameRandom. +// Interface in reality_space.hpp. #include "formats/executable_layout.hpp" #include "game/reality_space.hpp" diff --git a/src/game/reality_space.hpp b/src/game/reality_space.hpp index b911df9..2eefe4b 100644 --- a/src/game/reality_space.hpp +++ b/src/game/reality_space.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the Reality scene spatial helpers (path, offside, nearby, penalty area, line +// occupants) implemented in reality_space.cpp. #pragma once #include "game/reality_setup.hpp" diff --git a/src/game/reschedule.cpp b/src/game/reschedule.cpp index 1112eac..d83c655 100644 --- a/src/game/reschedule.cpp +++ b/src/game/reschedule.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Rescheduling a home league match of a human manager on the calendar screen: which days are +// offered, conflicts with the friendly plan and replays, and moving the match. +// Reads and writes the competition calendar, postponed list and friendly plan in the static +// memory of GameState. Draws no random numbers. Interface in reschedule.hpp; uses schedule.cpp +// and matchday_setup.hpp. #include "formats/executable_layout.hpp" #include "game/reschedule.hpp" diff --git a/src/game/save.cpp b/src/game/save.cpp index 213446a..e826dbe 100644 --- a/src/game/save.cpp +++ b/src/game/save.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Savegame writing: serialises GameState into the save file layout (header, stream, date text, +// check bytes) and builds the Savegame record. +// Reads GameState; make_savegame draws from WatcomRandom (savegame id and two bytes), the same +// draws counted by save_game_draws in desk.cpp. Interface in save.hpp. #include "formats/executable_layout.hpp" #include "game/save.hpp" #include "game/bank_robbery.hpp" diff --git a/src/game/schedule.cpp b/src/game/schedule.cpp index b56d090..123a8a6 100644 --- a/src/game/schedule.cpp +++ b/src/game/schedule.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// League scheduling: fixture round tables per league size installed from the loaded +// executable, league sizes and calendar groups, team to league mapping and generation of the +// fixtures of a matchday. +// Process-wide tables, no GameState writes and no random numbers. Interface in schedule.hpp; +// used by table_forecast.cpp, reschedule.cpp and others. #include "game/schedule.hpp" #include "formats/executable_layout.hpp" #include "formats/le.hpp" diff --git a/src/game/season.cpp b/src/game/season.cpp index fa28827..44d4645 100644 --- a/src/game/season.cpp +++ b/src/game/season.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Season-wide steps: offers, club moods and balances, European qualification and cup fields, +// annual accounts and profit tax, season awards, promotion/relegation, league shuffling, player +// regeneration and release, and the first-season setup of a career. +// Reads and writes most of GameState (memory, players, squad_slots, manager records). +// Draws from WatcomRandom and GameRandom (see the calls below). Interface in season.hpp. #include "formats/executable_layout.hpp" #include "game/environment.hpp" #include "game/season.hpp" diff --git a/src/game/source_tip.cpp b/src/game/source_tip.cpp index da80b09..a27e33c 100644 --- a/src/game/source_tip.cpp +++ b/src/game/source_tip.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Score arithmetic of the computer's league table forecast tip: from team ratings and secondary +// values it produces one predicted result using the game generator. +// A pure function of its arguments; each call consumes a fixed pattern of GameRandom draws. +// Interface in source_tip.hpp; used by table_forecast.cpp. #include "game/source_tip.hpp" #include diff --git a/src/game/source_tip.hpp b/src/game/source_tip.hpp index e5d1450..ba9af02 100644 --- a/src/game/source_tip.hpp +++ b/src/game/source_tip.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the computer tip score function implemented in source_tip.cpp. It consumes +// GameRandom draws, including the final goal-cap draw, and touches no GameState. #pragma once #include diff --git a/src/game/sportschau_awards.cpp b/src/game/sportschau_awards.cpp index 06e1c36..7b734f7 100644 --- a/src/game/sportschau_awards.cpp +++ b/src/game/sportschau_awards.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Sportschau (TV sports show) support: the matchday intro view built from the match groups +// and the competition title of a group. +// Read-only projection of GameState and the groups. Draws no random numbers. +// Declared in sportschau_presentation.hpp; sportschau_rating.cpp and sportschau_replay.cpp are siblings. #include "formats/executable_layout.hpp" #include "game/sportschau_presentation.hpp" #include diff --git a/src/game/sportschau_rating.cpp b/src/game/sportschau_rating.cpp index bf44bd5..6222cf9 100644 --- a/src/game/sportschau_rating.cpp +++ b/src/game/sportschau_rating.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Sportschau ratings: reads the rating tables from the executable and derives the player ratings +// of a match group from the logged events of a fixture. +// Reads the fixture view and writes ratings into the MatchGroup; draws from WatcomRandom +// (score offsets). Declared in sportschau_presentation.hpp; siblings are sportschau_awards.cpp +// and sportschau_replay.cpp. #include "formats/executable_layout.hpp" #include "game/sportschau_presentation.hpp" diff --git a/src/game/sportschau_replay.cpp b/src/game/sportschau_replay.cpp index 8ec1b30..c1dc25d 100644 --- a/src/game/sportschau_replay.cpp +++ b/src/game/sportschau_replay.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Sportschau replay: converts the logged events of a fixture into the timed steps of the report +// and re-runs a fixture with a MatchEngine on a copy of the state for the replay. +// The engine takes the caller's GameRandom and WatcomRandom. Declared in +// sportschau_presentation.hpp; siblings are sportschau_awards.cpp and sportschau_rating.cpp. #include "formats/executable_layout.hpp" #include "game/sportschau_presentation.hpp" diff --git a/src/game/stadium_blocks.cpp b/src/game/stadium_blocks.cpp index d287989..4974312 100644 --- a/src/game/stadium_blocks.cpp +++ b/src/game/stadium_blocks.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Stadium block expansion (blocks A-H): reads the edition's price/duration/limit constants, +// quotes an expansion bound to the record values it depends on, and commits the construction +// order and payment. +// Reads and writes the manager records in GameState; the commit path takes WatcomRandom and a +// notice hook for the payment. Interface in stadium_blocks.hpp. #include "game/stadium_blocks.hpp" #include "game/matchday.hpp" diff --git a/src/game/stadium_blocks.hpp b/src/game/stadium_blocks.hpp index 8da2a94..bb37885 100644 --- a/src/game/stadium_blocks.hpp +++ b/src/game/stadium_blocks.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the stadium block expansion: slots A-H, constants, immutable quote and the +// quote/commit functions implemented in stadium_blocks.cpp. Block slots are distinct from the +// stadium facilities used by the business plan. #pragma once #include "game/desk_actions.hpp" diff --git a/src/game/state.cpp b/src/game/state.cpp index 748b821..59046dc 100644 --- a/src/game/state.cpp +++ b/src/game/state.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// GameState construction and accessors: building the state from a loaded save and the database +// counts, manager of a team, club and player names, formation and formation positions. +// Squad table layout constants are defined here. Draws no random numbers. +// Interface in state.hpp; every other file in this directory works on GameState. #include "formats/executable_layout.hpp" #include "game/state.hpp" #include "game/bank_robbery.hpp" diff --git a/src/game/table.cpp b/src/game/table.cpp index e7a936b..8dbd0a1 100644 --- a/src/game/table.cpp +++ b/src/game/table.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// League table computation: adding results with win bonus, sort keys and sorting, and +// compute_league_table over a range of matchdays for a league. +// Reads GameState (fixtures and results); returns a LeagueTable. Draws no random numbers. +// Interface in table.hpp. #include "game/table.hpp" #include diff --git a/src/game/table_forecast.cpp b/src/game/table_forecast.cpp index 50761d3..3e783fc 100644 --- a/src/game/table_forecast.cpp +++ b/src/game/table_forecast.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Table screen forecast: combines the played table with predicted results of the remaining +// matchdays (computer tips from source_tip.cpp) into a league table projection. +// Reads GameState; works on a copy of the game generator and returns it in the result, so +// callers commit it only with the accepted transition. Interface in table_forecast.hpp. #include "formats/executable_layout.hpp" #include "game/table_forecast.hpp" diff --git a/src/game/table_forecast.hpp b/src/game/table_forecast.hpp index d233230..a1816e3 100644 --- a/src/game/table_forecast.hpp +++ b/src/game/table_forecast.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the table forecast: the LeagueTableForecast result (table plus the game generator +// state after all draws) and compute_league_table_forecast, implemented in table_forecast.cpp. +// Never changes the native results or the current matchday. #pragma once #include diff --git a/src/game/top_scorers.cpp b/src/game/top_scorers.cpp index 22ffb47..f7f7ada 100644 --- a/src/game/top_scorers.cpp +++ b/src/game/top_scorers.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Top scorers view: ranks players of a league or of the human managers by goals, assists or +// scorer score and determines the owning manager of each club. +// Read-only projection of GameState; invalid input throws FormatError. Draws no random numbers. +// Interface in top_scorers.hpp. #include "game/top_scorers.hpp" #include diff --git a/src/game/top_scorers.hpp b/src/game/top_scorers.hpp index a8fd951..03fbb10 100644 --- a/src/game/top_scorers.hpp +++ b/src/game/top_scorers.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the top scorers view: metric and scope enums, row type and the ranking function +// implemented in top_scorers.cpp. Read-only; no random numbers are drawn. #pragma once #include diff --git a/src/game/transfer_bid.hpp b/src/game/transfer_bid.hpp index 73bbb5f..3f53b7b 100644 --- a/src/game/transfer_bid.hpp +++ b/src/game/transfer_bid.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Request/result types for rating a transfer bid (source slot, list entry and ownership are +// supplied by the caller, which owns the career-mode decisions). +// Header only; the functions that use these types take WatcomRandom and a MinuteReport as shown below. #pragma once #include diff --git a/src/game/turn.cpp b/src/game/turn.cpp index 56af58d..f74951f 100644 --- a/src/game/turn.cpp +++ b/src/game/turn.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Day-by-day turn processing: plain days, empty event days, month step, stock market day, +// season end day and the preparation and finish of an event with its desk. +// Reads and writes GameState and calls into month.cpp, weekly.cpp, week.cpp, season.cpp and the +// matchday code. Takes both generators (GameRandom, WatcomRandom) and reseeds via stir_random at +// league screens. Interface in turn.hpp; the calendar loop around it is in turn_driver.cpp. #include "formats/executable_layout.hpp" #include "game/turn.hpp" #include "game/trace.hpp" diff --git a/src/game/turn_driver.cpp b/src/game/turn_driver.cpp index fb2d3f7..08c38a4 100644 --- a/src/game/turn_driver.cpp +++ b/src/game/turn_driver.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Turn driver: walks the calendar day by day to the next desk, starts event passes, runs the +// current matchday through the MatchEngine and reports audio events and desk results. +// Reads and writes GameState and the TurnDriver state; passes GameRandom and WatcomRandom to +// everything it calls (setup, matches, daily interest). Interface in turn_driver.hpp. #include "formats/executable_layout.hpp" #include "game/turn_driver.hpp" diff --git a/src/game/turn_driver.hpp b/src/game/turn_driver.hpp index 3723dc5..5845b58 100644 --- a/src/game/turn_driver.hpp +++ b/src/game/turn_driver.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interface of the turn driver: audio event, desk kind, advance request/result and result +// snapshot types and the TurnDriver runtime state kept between a desk and the next one. +// The caller owns the generators; implemented in turn_driver.cpp. #pragma once #include diff --git a/src/game/week.cpp b/src/game/week.cpp index f48f325..f0018d5 100644 --- a/src/game/week.cpp +++ b/src/game/week.cpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Daily and weekly bookkeeping: daily interest on balances, player training and attribute +// changes, familiarity decay, auto training, the stock market and the bank robbery month key. +// Reads and writes GameState (manager records, players, memory). +// Draws from WatcomRandom (daily interest, familiarity, training) and GameRandom (training). +// Interface in week.hpp; larger weekly steps are in weekly.cpp. #include "formats/executable_layout.hpp" #include "game/week.hpp" #include "game/calendar.hpp" diff --git a/src/game/weekly.cpp b/src/game/weekly.cpp index 6b0ad96..3561a0c 100644 --- a/src/game/weekly.cpp +++ b/src/game/weekly.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Weekly processing: manager offers, season ticket compensation, facility ageing and damage, +// club attraction, advertising, transfer bids and offers (evaluate, execute, pending offers, +// human buyer sale) and the transfer list countdown. +// Reads and writes most of GameState (transfer list, squad_slots, players, manager records). +// Draws heavily from WatcomRandom and also from GameRandom. +// Interface in weekly.hpp; monthly steps are in month.cpp, daily ones in week.cpp. #include "formats/executable_layout.hpp" #include "game/weekly.hpp" #include "game/desk_actions.hpp" diff --git a/src/launch/archive.cpp b/src/launch/archive.cpp index 64f25df..45a99ba 100644 --- a/src/launch/archive.cpp +++ b/src/launch/archive.cpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of archive.hpp. The archive file is read into memory once (refused above +// 512 MB) and then parsed by miniz (ZIP) or the LZMA SDK's C decoder (7z) through an in-memory +// stream; entry names are normalised to UTF-8 with '/' (ZIP names without the UTF-8 flag are +// taken as DOS code page 437). The file also holds the UTF-8 <-> filesystem path helpers and +// the UTF-8 program arguments (the wide command line on Windows). Archive::Impl is private +// to this file; failures throw ArchiveError. #include "launch/archive.hpp" #include diff --git a/src/launch/file_dialog.cpp b/src/launch/file_dialog.cpp index 88dac73..8e0ef31 100644 --- a/src/launch/file_dialog.cpp +++ b/src/launch/file_dialog.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of choose_game_file() (file_dialog.hpp) with the native file dialog +// library (nfd): one filter for ZIP, 7z and EXE files. Returns std::nullopt when the user +// cancels and throws std::runtime_error when no dialog can be shown. It only picks a path; +// whether the file is a usable game is decided later by game_data.cpp. #include "launch/file_dialog.hpp" #include diff --git a/src/launch/fltd.cpp b/src/launch/fltd.cpp index 0bfb5c5..757e915 100644 --- a/src/launch/fltd.cpp +++ b/src/launch/fltd.cpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of fltd.hpp. translate_fltd() builds the German-layout image of the English +// FLTD.EXE: a table of entries (generated include launch/fltd_map.inc) says for every German +// data object whether to copy it from its English address, keep the German values, fill +// pointers with an empty string, or use one of OpenBMH's own English texts (kOwnTexts, which +// must fit the German text's room); the English data segment is also placed at its own +// addresses. prepare_english_game() writes that image and copies the text, database and +// other data files into the target directory. Addresses come from formats/executable_layout.hpp. #include "formats/executable_layout.hpp" #include "launch/fltd.hpp" diff --git a/src/launch/game_data.cpp b/src/launch/game_data.cpp index db24889..8852d20 100644 --- a/src/launch/game_data.cpp +++ b/src/launch/game_data.cpp @@ -1,4 +1,11 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of game_data.hpp: recognises the game family from the EXE name and size +// (German BMH.EXE, English FLTD.EXE, the 1994 disk version as unsupported), checks that +// the required data files exist with the expected sizes (tables of pictures, badges and +// common files in this file; file names matched without regard to case), unpacks an archive +// into the cache directory under a content hash, and resolves directory/EXE/archive input to +// a ResolvedGame. The English game is converted via fltd.hpp. Problems are collected as text +// in GameCheck::problems rather than thrown; describe() formats them for message boxes. #include "launch/game_data.hpp" #include diff --git a/src/ui/achievements.cpp b/src/ui/achievements.cpp index ba4b2e6..ed7cbde 100644 --- a/src/ui/achievements.cpp +++ b/src/ui/achievements.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the achievements screen declared in achievements.hpp: achievements_from_game() builds the +// read-only per-season state (league, cup and Europe result text and graph position) from the game, and +// AchievementsScreen renders it over the supplied underlay and answers pointer input. +// The only request it can raise is a close request; it never writes game state. #include "formats/executable_layout.hpp" #include "ui/achievements.hpp" diff --git a/src/ui/achievements.hpp b/src/ui/achievements.hpp index fdf6a6f..38afe78 100644 --- a/src/ui/achievements.hpp +++ b/src/ui/achievements.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Achievements screen (manager career history): one league/cup/Europe result triple per season, up to 50 seasons. +// Owns AchievementsState (copied from the game by achievements_from_game, plus the captured desktop underlay) +// and AchievementsScreen, which renders it and only reports a close request through pending(). +// The implementation is in achievements.cpp. #pragma once #include diff --git a/src/ui/achievements_tests.cpp b/src/ui/achievements_tests.cpp index ab070c5..3523a8d 100644 --- a/src/ui/achievements_tests.cpp +++ b/src/ui/achievements_tests.cpp @@ -1,3 +1,4 @@ +// Tests for the achievements projection and screen (ui/achievements.hpp). #include "../../tests/test_inputs.hpp" // SPDX-License-Identifier: GPL-3.0-only #include "formats/executable_layout.hpp" diff --git a/src/ui/advertising.cpp b/src/ui/advertising.cpp index f01b1f4..acd403f 100644 --- a/src/ui/advertising.cpp +++ b/src/ui/advertising.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the advertising screen declared in advertising.hpp: building AdvertisingState from the game +// (contracts, offers, spending, texts), rendering, and turning clicks into AdvertisingRequest values. +// Also holds the monthly finance preview formulas that finance_totals.cpp reuses through +// original_finance_preview(). Game changes happen only when the session accepts a request. #include "formats/executable_layout.hpp" #include "game/environment.hpp" #include "ui/advertising.hpp" diff --git a/src/ui/advertising.hpp b/src/ui/advertising.hpp index d11564c..7cb5071 100644 --- a/src/ui/advertising.hpp +++ b/src/ui/advertising.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Advertising (sponsor) screen: board contracts, shirt sponsor, television rights, offers and spending. +// Owns AdvertisingState (a read-only copy built by advertising_from_game, tagged with a revision) and the +// AdvertisingRequest values the screen raises (accept offer, set spending, check renewal). +// Also exposes original_finance_preview(), the monthly income/expense preview shared with the statistics +// pages and finance_totals.hpp. Implementation: advertising.cpp. +// Request/acknowledge flow: a request carries manager, club and revision so the session can reject stale input. #pragma once #include diff --git a/src/ui/advertising_tests.cpp b/src/ui/advertising_tests.cpp index 0bbd935..07fbc72 100644 --- a/src/ui/advertising_tests.cpp +++ b/src/ui/advertising_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the advertising projection, rendering and request handling (ui/advertising.hpp). #include "formats/executable_layout.hpp" #include "ui/advertising.hpp" #include "ui/source_notice_test_helpers.hpp" diff --git a/src/ui/alltime_table.cpp b/src/ui/alltime_table.cpp index 37e5eb2..d59ff23 100644 --- a/src/ui/alltime_table.cpp +++ b/src/ui/alltime_table.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the all-time table declared in alltime_table.hpp: alltime_table_from_game() collects and sorts +// the per-club records for the chosen nation, and AllTimeTableScreen draws the table and buttons and queues +// requests for the owning screen. It does not modify game state. #include "formats/executable_layout.hpp" #include "alltime_table.hpp" #include diff --git a/src/ui/alltime_table.hpp b/src/ui/alltime_table.hpp index 8458474..f493f4a 100644 --- a/src/ui/alltime_table.hpp +++ b/src/ui/alltime_table.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// All-time table screen (cumulative points and goals per club, selectable by nation, absolute or relative). +// Owns AllTimeTableState (copied from the game, with the parent underlay) and AllTimeTableScreen, which +// raises AllTimeRequest values (close, select nation, toggle relative) through pending(). +// The owning screen applies them and rebuilds the state. Implementation: alltime_table.cpp. #pragma once #include #include diff --git a/src/ui/alltime_table_tests.cpp b/src/ui/alltime_table_tests.cpp index 7864b68..6fbccd4 100644 --- a/src/ui/alltime_table_tests.cpp +++ b/src/ui/alltime_table_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the all-time table projection and ordering (ui/alltime_table.hpp). #include "formats/executable_layout.hpp" #include "alltime_table.hpp" #include "game/table.hpp" diff --git a/src/ui/analytics.cpp b/src/ui/analytics.cpp index d299d52..32f644a 100644 --- a/src/ui/analytics.cpp +++ b/src/ui/analytics.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the analytics page declared in analytics.hpp: analytics_from_game() copies the six series and +// the saved flag byte, and AnalyticsScreen draws the chart over the parent underlay and handles the metric +// and scale buttons. A flag change is only a pending request until the owner acknowledges it. #include "formats/executable_layout.hpp" #include "ui/analytics.hpp" diff --git a/src/ui/analytics.hpp b/src/ui/analytics.hpp index 0e772e7..e355675 100644 --- a/src/ui/analytics.hpp +++ b/src/ui/analytics.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Analytics statistics page: six data series with per-metric toggles and an absolute/relative scale switch. +// Owns AnalyticsState (values copied from the game, never simulated, plus the parent underlay) and +// AnalyticsScreen. Toggles raise AnalyticsRequest values carrying expected and target flag bytes; +// the owner persists the flags and calls acknowledge(), or reject() to drop the request. +// Implementation: analytics.cpp. #pragma once #include diff --git a/src/ui/analytics_tests.cpp b/src/ui/analytics_tests.cpp index d316ba6..e3d88bd 100644 --- a/src/ui/analytics_tests.cpp +++ b/src/ui/analytics_tests.cpp @@ -1,3 +1,4 @@ +// Tests for the analytics projection, toggles and acknowledgement (ui/analytics.hpp). #include "../../tests/test_inputs.hpp" // SPDX-License-Identifier: GPL-3.0-only #include "formats/executable_layout.hpp" diff --git a/src/ui/balance_plan.cpp b/src/ui/balance_plan.cpp index 59faa62..f00985b 100644 --- a/src/ui/balance_plan.cpp +++ b/src/ui/balance_plan.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the balance plan screen declared in balance_plan.hpp: balance_from_game() builds the state from +// the game and a plan draft, and BalanceScreen renders rows, calculator and notice dialogs, handles pointer, +// key and text input, and queues BalanceRequest values for the session instead of editing the plan itself. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/balance_plan.hpp" diff --git a/src/ui/balance_plan.hpp b/src/ui/balance_plan.hpp index 7bcc0eb..8bec47d 100644 --- a/src/ui/balance_plan.hpp +++ b/src/ui/balance_plan.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Balance plan (budget) screen with its calculator dialog and notices. +// Owns BalanceState (a BalancePlanDraft copy plus captured desktop underlay) and BalanceScreen. +// Actions (edit row, cycle view, take actuals, close, confirm close) become BalanceRequest values tagged with +// a BalanceIdentity (revision, scope, sequence); the session applies them, and reject_action() reports refusal. +// Time-driven parts (notice timer, calculator flash) are fed by the caller through millisecond tick calls. +// Implementation: balance_plan.cpp. #pragma once #include diff --git a/src/ui/balance_plan_tests.cpp b/src/ui/balance_plan_tests.cpp index 702baeb..64f6171 100644 --- a/src/ui/balance_plan_tests.cpp +++ b/src/ui/balance_plan_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the balance plan projection, calculator and requests (ui/balance_plan.hpp). #include "formats/executable_layout.hpp" #include "ui/balance_plan.hpp" #include "ui/setup.hpp" diff --git a/src/ui/bank.cpp b/src/ui/bank.cpp index 2df336d..88cd49b 100644 --- a/src/ui/bank.cpp +++ b/src/ui/bank.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the bank screen declared in bank.hpp: bank_from_game() builds the state (including formatted +// number texts and credit lender candidates) from the game, and BankScreen draws the finance, share, fund +// and credit views and converts input into BankRequest values. State changes happen only after the session +// accepts a request. #include "formats/executable_layout.hpp" #include "ui/bank.hpp" #include "ui/game_end.hpp" diff --git a/src/ui/bank.hpp b/src/ui/bank.hpp index caca0f5..69a0beb 100644 --- a/src/ui/bank.hpp +++ b/src/ui/bank.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Bank screen: account and fixed deposit, stock and fund trading, stock tips, and bank or inter-manager credit. +// Owns BankState (a read-only copy of balances, prices, holdings and credit offers built by bank_from_game, +// tagged with a revision) and BankScreen. Money-moving actions are BankRequest values (kind, amount, asset +// index, expected credit terms) that the session validates against the revision before applying. +// Implementation: bank.cpp. #pragma once #include diff --git a/src/ui/bank_tests.cpp b/src/ui/bank_tests.cpp index 2c258dc..7c7f06b 100644 --- a/src/ui/bank_tests.cpp +++ b/src/ui/bank_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the bank projection, rendering and request validation (ui/bank.hpp). #include "formats/executable_layout.hpp" #include "ui/bank.hpp" #include "ui/source_notice_test_helpers.hpp" diff --git a/src/ui/calendar.cpp b/src/ui/calendar.cpp index 9cce4d5..77f50d1 100644 --- a/src/ui/calendar.cpp +++ b/src/ui/calendar.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements CalendarScreen from calendar.hpp: draws the July-to-June calendar grid and day information from +// a CalendarState, tracks the selected day, and turns clicks in reschedule mode into RescheduleAction requests. +// It pairs with calendar_state.cpp, which builds the state; this file changes no game data. #include "formats/executable_layout.hpp" #include "ui/calendar.hpp" #include "game/schedule.hpp" diff --git a/src/ui/calendar.hpp b/src/ui/calendar.hpp index 2240df8..4ee2789 100644 --- a/src/ui/calendar.hpp +++ b/src/ui/calendar.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Season calendar screen (July to June grid) including the reschedule-match mode. +// CalendarScreen renders a CalendarState (built in calendar_state.cpp) and raises a RescheduleAction +// (move or undo a league match to a target day) through pending_reschedule(); the owner applies it and +// answers with acknowledge_reschedule() or reject_reschedule(). calendar_cell() gives the cell geometry. +// Implementation: calendar.cpp; the read-only projection lives in calendar_state.hpp/calendar_state.cpp. #pragma once #include "formats/font.hpp" diff --git a/src/ui/calendar_state.cpp b/src/ui/calendar_state.cpp index 791a3d0..3946785 100644 --- a/src/ui/calendar_state.cpp +++ b/src/ui/calendar_state.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements calendar_from_game() and reschedule_calendar_from_game() declared in calendar_state.hpp. +// They project the saved season into CalendarState (dates, competition bitmaps, matchday ordinals, +// reschedule options) without preparing fixtures, advancing the date or consuming random numbers. +// The projection feeds CalendarScreen in calendar.cpp. #include "formats/executable_layout.hpp" #include "ui/calendar_state.hpp" diff --git a/src/ui/calendar_state.hpp b/src/ui/calendar_state.hpp index ace416e..947b790 100644 --- a/src/ui/calendar_state.hpp +++ b/src/ui/calendar_state.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Read-only projection of the saved season calendar for the calendar screen (calendar.hpp). +// CalendarState holds one CalendarDayProjection per display day (starting on July 1, with leading days +// bridging to the saved calendar words) and, in reschedule mode, the movable matches and their target days. +// Built by calendar_from_game() and reschedule_calendar_from_game() in calendar_state.cpp. #pragma once #include diff --git a/src/ui/club_info.cpp b/src/ui/club_info.cpp index 81c11b9..8f6a1b6 100644 --- a/src/ui/club_info.cpp +++ b/src/ui/club_info.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the club info screen declared in club_info.hpp: club_info_from_game() builds the player rows +// (including loan projections and manager board data for human clubs), and ClubInfoScreen renders both data +// views and converts button and row clicks into ClubInfoRequest values. It does not change the game itself. #include "formats/executable_layout.hpp" #include "ui/club_info.hpp" diff --git a/src/ui/club_info.hpp b/src/ui/club_info.hpp index 465cb0c..bfe98f2 100644 --- a/src/ui/club_info.hpp +++ b/src/ui/club_info.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Club info screen: the squad list of a club with two data views, statistics, category change and a jump +// into the player detail card. ClubInfoProjection is the owned, read-only input built by club_info_from_game(); +// the screen raises ClubInfoRequest values (close, toggle view, statistics, category, player detail) that the +// session or flow handles. The same projection is also used for the lineup screen. +// Implementation: club_info.cpp. #pragma once #include diff --git a/src/ui/club_player_detail.cpp b/src/ui/club_player_detail.cpp index b5ac4a4..e7ef8b0 100644 --- a/src/ui/club_player_detail.cpp +++ b/src/ui/club_player_detail.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the player detail card declared in club_player_detail.hpp: club_player_detail_from_game() copies +// club, nationality and offer data into the projection, and ClubPlayerDetailScreen renders the card over the +// parent frame and turns presses and releases into ClubPlayerDetailRequest values for the caller to handle. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/club_player_detail.hpp" diff --git a/src/ui/club_player_detail.hpp b/src/ui/club_player_detail.hpp index dbaf7c4..e25d957 100644 --- a/src/ui/club_player_detail.hpp +++ b/src/ui/club_player_detail.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Club player detail card shown above a club info page. +// ClubPlayerDetailProjection is built by club_player_detail_from_game() from a redraw produced by the engine +// once per card rebuild; render, move, press and release never touch game state or the random generators. +// ClubPlayerDetailScreen raises ClubPlayerDetailRequest values (close, redraw card, national action, offer +// action) and keeps the parent frame it is drawn over. Implementation: club_player_detail.cpp. #pragma once #include "game/club_player_detail.hpp" diff --git a/src/ui/contracts.cpp b/src/ui/contracts.cpp index 2ab9f1d..ab251e7 100644 --- a/src/ui/contracts.cpp +++ b/src/ui/contracts.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the contracts screen declared in contracts.hpp: contracts_from_game() builds the player rows +// and premiums from the game, and ContractsScreen renders list, negotiation and insurance views and converts +// input into ContractRequest values. Applying an offer or insurance is left to the session. #include "formats/executable_layout.hpp" #include "ui/contracts.hpp" #include "ui/game_end.hpp" diff --git a/src/ui/contracts.hpp b/src/ui/contracts.hpp index ee87de4..56f104f 100644 --- a/src/ui/contracts.hpp +++ b/src/ui/contracts.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Contracts screen: player list with remaining months, salary demands, offers, bonuses and insurance. +// ContractsState is a read-only copy built by contracts_from_game() (tagged with revision and request id base); +// ContractsScreen raises ContractRequest values (request demands, submit offer, submit bonuses, insure player) +// that carry request id, revision and quote id so the session can reject stale input. +// Implementation: contracts.cpp. #pragma once #include diff --git a/src/ui/contracts_tests.cpp b/src/ui/contracts_tests.cpp index 2c491fd..d0a89e8 100644 --- a/src/ui/contracts_tests.cpp +++ b/src/ui/contracts_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the contracts projection and request flow (ui/contracts.hpp). #include "ui/contracts.hpp" #include "ui/source_notice_test_helpers.hpp" #include "ui/manager.hpp" diff --git a/src/ui/cup_draw.cpp b/src/ui/cup_draw.cpp index 87c88d1..741d6fe 100644 --- a/src/ui/cup_draw.cpp +++ b/src/ui/cup_draw.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the cup draw screen declared in cup_draw.hpp: cup_draw_from_game() copies the drawn clubs +// or group table rows into a CupDrawProjection, and CupDrawScreen draws it. It is presentation only and +// does not change cup or game state. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/cup_draw.hpp" diff --git a/src/ui/cup_draw.hpp b/src/ui/cup_draw.hpp index 5cd17d8..94b31ba 100644 --- a/src/ui/cup_draw.hpp +++ b/src/ui/cup_draw.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Cup draw screen: shows a cup round draw (or group overview) as captured at a hook of the season engine. +// CupDrawProjection is an owned snapshot (entry order, heading, footer, group rows); the renderer never +// advances cup state or consumes either game random generator. Built by cup_draw_from_game(), +// presented by CupDrawScreen. Implementation: cup_draw.cpp. #pragma once #include diff --git a/src/ui/desk_drawers.cpp b/src/ui/desk_drawers.cpp index 62a06c4..d02f65d 100644 --- a/src/ui/desk_drawers.cpp +++ b/src/ui/desk_drawers.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements DeskDrawerRenderer and source_drawer_team() declared in desk_drawers.hpp: loads the drawer icons +// and font and draws each drawer kind from the read-only DeskState. It is used by DesktopScreen +// (desktop.cpp) and writes only into the target image. #include "formats/executable_layout.hpp" #include "ui/desk_drawers.hpp" diff --git a/src/ui/desk_drawers.hpp b/src/ui/desk_drawers.hpp index 4b056c5..1e03cd8 100644 --- a/src/ui/desk_drawers.hpp +++ b/src/ui/desk_drawers.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Drawer content for the manager desk (desktop.hpp): folder, rank curve, recent matches, head-to-head, +// rank/strength, opponent name and badge views. +// DeskDrawerRenderer draws only the content; the caller keeps the native drawer frame. The paired-drawer +// selection helper source_drawer_team() maps a drawer kind to a team from the DeskState. +// Implementation: desk_drawers.cpp. #pragma once #include diff --git a/src/ui/desk_records.cpp b/src/ui/desk_records.cpp index e5793cd..594569d 100644 --- a/src/ui/desk_records.cpp +++ b/src/ui/desk_records.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the desk record pages declared in desk_records.hpp: fair_play_state_from_game() projects the +// fair play rows for a league, and DeskRecordsScreen renders the fair play or highscore page and forwards +// input to the embedded alternate score calculator (game_end_alternate.hpp) when that variant is active. #include "formats/executable_layout.hpp" #include "ui/desk_records.hpp" diff --git a/src/ui/desk_records.hpp b/src/ui/desk_records.hpp index f9cc79b..093cb66 100644 --- a/src/ui/desk_records.hpp +++ b/src/ui/desk_records.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Desk record pages: the fair play table and the highscore view, with a calculator variant for the alternate +// score screen. DeskRecordsState is built from the game (fair_play_state_from_game) or supplied with a +// highscore projection; the highscore file update is done by the caller before constructing the state. +// DeskRecordsScreen only renders and reports closed(). Implementation: desk_records.cpp. #pragma once #include diff --git a/src/ui/desk_state.cpp b/src/ui/desk_state.cpp index 6caaae1..a4e7bfd 100644 --- a/src/ui/desk_state.cpp +++ b/src/ui/desk_state.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the DeskState builders declared in desk_state.hpp (desk_from_game, desk_from_save, +// load_reference_desk, desk_json) and the validation of profile and state. It projects saved blocks, +// the club roster, calendar date, table position and automation formation into the read-only structure +// rendered by DesktopScreen. #include "formats/native_save_version.hpp" #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" diff --git a/src/ui/desk_state.hpp b/src/ui/desk_state.hpp index 8e1e121..d9f924a 100644 --- a/src/ui/desk_state.hpp +++ b/src/ui/desk_state.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// DeskState: the copyable, read-only state the manager desk (desktop.hpp) renders, including setup options, +// managers, dates, opponent history, rank curves and the saved desk layout. +// Built by desk_from_game()/desk_from_save() in desk_state.cpp. Engine changes are never made here; +// the desk raises explicit DeskRequest values instead. Runtime club ids are not master database ids. #pragma once #include diff --git a/src/ui/desktop.cpp b/src/ui/desktop.cpp index a263a20..930b3a7 100644 --- a/src/ui/desktop.cpp +++ b/src/ui/desktop.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements DesktopScreen declared in desktop.hpp: loads the desk art and fonts, renders icons and drawers +// (via desk_drawers.cpp), handles pointer, key and timer events, queues DeskRequest values, and applies +// acknowledged DeskState updates. It also provides desk_request_json() and desk_menu_name(). #include "formats/executable_layout.hpp" #include "ui/desktop.hpp" diff --git a/src/ui/desktop.hpp b/src/ui/desktop.hpp index e7832f4..ebeedb7 100644 --- a/src/ui/desktop.hpp +++ b/src/ui/desktop.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Manager desk screen: the main hub with icons, drawers, folders and the quickbar. +// DesktopScreen renders a DeskState and turns input into a single DeskRequest (open menu, advance turn, +// change layout/option/ticket price, end session). A request waits for acknowledge() with a strictly newer +// revision, so repeated input never advances time twice; reject_action() changes nothing. +// Sound ids are handed out through take_sound_ids(); the application owns playback. Implementation: desktop.cpp. #pragma once #include diff --git a/src/ui/desktop_tests.cpp b/src/ui/desktop_tests.cpp index 84c1816..a0da6f2 100644 --- a/src/ui/desktop_tests.cpp +++ b/src/ui/desktop_tests.cpp @@ -1,3 +1,4 @@ +// Tests for the desk state projection, DesktopScreen input and request flow (ui/desktop.hpp, ui/desk_state.hpp). #include "../../tests/runtime_fixture_tables.hpp" // SPDX-License-Identifier: GPL-3.0-only #include "formats/executable_layout.hpp" diff --git a/src/ui/environment.cpp b/src/ui/environment.cpp index c8a42da..1282fc0 100644 --- a/src/ui/environment.cpp +++ b/src/ui/environment.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the environment screen declared in environment.hpp: environment_from_game() fills the view and +// the formatted costs, EnvironmentScreen renders it over the underlay and converts clicks and keys into +// EnvironmentRequest values; environment_notice_dialog() builds the accompanying notice projection. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/environment.hpp" diff --git a/src/ui/environment.hpp b/src/ui/environment.hpp index afbd3bd..5e6c980 100644 --- a/src/ui/environment.hpp +++ b/src/ui/environment.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Environment screen (stadium surroundings and youth work): levels for several cost items with formatted costs. +// EnvironmentView is a read-only copy built by environment_from_game(), tagged with a revision and owner +// request. EnvironmentScreen raises EnvironmentRequest values (set item level) that the session applies and +// confirms through acknowledge() or refuses with reject_action(). environment_notice_dialog() builds a +// notice dialog projection. Implementation: environment.cpp. #pragma once #include diff --git a/src/ui/environment_tests.cpp b/src/ui/environment_tests.cpp index da5a7f2..433f4ff 100644 --- a/src/ui/environment_tests.cpp +++ b/src/ui/environment_tests.cpp @@ -1,3 +1,4 @@ +// Tests for the environment view, rendering and requests (ui/environment.hpp). #include "../../tests/runtime_fixture_tables.hpp" // SPDX-License-Identifier: GPL-3.0-only #include "formats/executable_layout.hpp" diff --git a/src/ui/finance_totals.cpp b/src/ui/finance_totals.cpp index 52e4b7a..d71fdaf 100644 --- a/src/ui/finance_totals.cpp +++ b/src/ui/finance_totals.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the finance totals page declared in finance_totals.hpp: finance_totals_from_game() collects the +// row values and formats them with the game's currency settings, and FinanceTotalsScreen draws them. +// Row 4 is a group separator without a value. Presentation only. #include "formats/executable_layout.hpp" #include "finance_totals.hpp" diff --git a/src/ui/finance_totals.hpp b/src/ui/finance_totals.hpp index e9beeea..2f652c6 100644 --- a/src/ui/finance_totals.hpp +++ b/src/ui/finance_totals.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Finance totals page (eleven rows of club income and expenses with formatted amounts). +// finance_totals_from_game() builds the read-only FinanceTotals; the monthly values reuse the finance preview +// from advertising.cpp. FinanceTotalsScreen only renders over the supplied underlay and raises no requests. +// Implementation: finance_totals.cpp. #pragma once #include diff --git a/src/ui/finance_totals_tests.cpp b/src/ui/finance_totals_tests.cpp index 479410f..491d131 100644 --- a/src/ui/finance_totals_tests.cpp +++ b/src/ui/finance_totals_tests.cpp @@ -1,3 +1,4 @@ +// Tests for the finance totals projection (ui/finance_totals.hpp). #include "../../tests/runtime_fixture_tables.hpp" // SPDX-License-Identifier: GPL-3.0-only #include "formats/executable_layout.hpp" diff --git a/src/ui/flow.cpp b/src/ui/flow.cpp index ed60966..11b0449 100644 --- a/src/ui/flow.cpp +++ b/src/ui/flow.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements StartupFlow declared in flow.hpp: owns the currently open screen objects, forwards clicks, keys, +// text, holds and timer events to the active one, and converts their pending requests into FlowResult values +// for the session. Which screen is shown next is decided here. #include "ui/flow.hpp" #include "ui/source_hold.hpp" diff --git a/src/ui/flow.hpp b/src/ui/flow.hpp index 3a5bb83..b8690a5 100644 --- a/src/ui/flow.hpp +++ b/src/ui/flow.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// StartupFlow: the screen controller that routes input to the setup, manager, desktop and submenu screens +// and returns one FlowResult per event. FlowResult carries the FlowRequest kind plus the typed request of +// whichever screen raised it (desk, contracts, advertising, league family, statistics and others). +// It is a value boundary for the engine adapter: it uses no random numbers and writes no saves; +// the session performs the action and calls the matching acknowledge or reject method. Implementation: flow.cpp. #pragma once #include diff --git a/src/ui/friendly_match.cpp b/src/ui/friendly_match.cpp index ca17164..03594c2 100644 --- a/src/ui/friendly_match.cpp +++ b/src/ui/friendly_match.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements FriendlyMatchScreen and friendly_calendar_cell() declared in friendly_match.hpp: renders the +// stages from opponent list to booking, handles input, and builds FriendlyMatchRequest values for the +// controller to validate and execute. #include "ui/friendly_match.hpp" #include diff --git a/src/ui/friendly_match.hpp b/src/ui/friendly_match.hpp index 5e98daf..0953144 100644 --- a/src/ui/friendly_match.hpp +++ b/src/ui/friendly_match.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Friendly match booking screen: opponent choice, venue, quote and cost confirmation, calendar date choice, +// owner approval and booking. FriendlyStage tracks the progress; FriendlyMatchRequest (quote or book) is a +// controller-facing value to which the app adds and validates revision, manager and request id before calling +// the engine helpers. The screen itself does not change game state. Implementation: friendly_match.cpp. #pragma once #include diff --git a/src/ui/friendly_match_tests.cpp b/src/ui/friendly_match_tests.cpp index 5199894..5c6783c 100644 --- a/src/ui/friendly_match_tests.cpp +++ b/src/ui/friendly_match_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the friendly match screen stages and requests (ui/friendly_match.hpp). #include "formats/executable_layout.hpp" #include "ui/friendly_match.hpp" diff --git a/src/ui/game_end.cpp b/src/ui/game_end.cpp index 93c8b37..7afed44 100644 --- a/src/ui/game_end.cpp +++ b/src/ui/game_end.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the end-of-career screens declared in game_end.hpp (highscore, final messages, tax dialog, +// program error screen) and wrap_source_text(). Each screen loads its own art and font and renders from +// values supplied by the caller; nothing here changes game state. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/game_end.hpp" diff --git a/src/ui/game_end.hpp b/src/ui/game_end.hpp index 2476f88..b885854 100644 --- a/src/ui/game_end.hpp +++ b/src/ui/game_end.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// End-of-career presentation: highscore list, final messages, tax dialog and program error screen. +// The highscore and final screens are drawing-only: values and order are resolved by the caller and no career +// state is mutated; acknowledgement is owned by the application loop. Also exposes wrap_source_text(), the +// word and hyphen wrapping of the original text routine (optionally justified), reusable by text-only UI code. +// Implementation: game_end.cpp. #pragma once #include diff --git a/src/ui/game_end_alternate.cpp b/src/ui/game_end_alternate.cpp index 63f51b6..316cb8a 100644 --- a/src/ui/game_end_alternate.cpp +++ b/src/ui/game_end_alternate.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the alternate score screen declared in game_end_alternate.hpp: loading assets, the calculator +// buttons and presets, text and mouse input, the point-by-point drawing phase and rendering of each phase. +// It reports state through phase(), value() and accepted_value(); the caller decides what to do with them. #include "formats/executable_layout.hpp" #include "ui/game_end_alternate.hpp" diff --git a/src/ui/game_end_alternate.hpp b/src/ui/game_end_alternate.hpp index 78c6e42..b79b425 100644 --- a/src/ui/game_end_alternate.hpp +++ b/src/ui/game_end_alternate.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Alternate score screen at the end of a career: a calculator dialog to choose a value, then the points are +// drawn one pixel at a time and acknowledged. The screen owns its assets (load_game_end_alternate_score_assets) +// and has no GameState or random generator access. The caller owns presentation timing, source waits and the +// career lifecycle, and calls advance_point()/finish_points() between presented frames. +// Implementation: game_end_alternate.cpp; embedded by desk_records.hpp. #pragma once #include diff --git a/src/ui/game_end_tax_animation.cpp b/src/ui/game_end_tax_animation.cpp index 36e4e5e..b704013 100644 --- a/src/ui/game_end_tax_animation.cpp +++ b/src/ui/game_end_tax_animation.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the tax animation declared in game_end_tax_animation.hpp: decoding the animation script bytes +// into steps, loading the art, and advancing the screen one step at a time (copy rectangles, present by +// swapping buffers, optional full-frame copy). Timing is only reported, never waited on here. #include "formats/executable_layout.hpp" #include "ui/game_end_tax_animation.hpp" diff --git a/src/ui/game_end_tax_animation.hpp b/src/ui/game_end_tax_animation.hpp index cb0c330..363b86e 100644 --- a/src/ui/game_end_tax_animation.hpp +++ b/src/ui/game_end_tax_animation.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tax animation shown at the end of a career: a script of rectangle copies and waits decoded from executable +// data (decode_tax_animation_script) and played step by step by GameEndTaxAnimationScreen. +// The renderer has no game state, random generator or event loop; callers present each frame and wait the +// reported milliseconds. It keeps two buffers so the next dialog can use the correct backdrop. +// Implementation: game_end_tax_animation.cpp. #pragma once #include diff --git a/src/ui/game_end_tests.cpp b/src/ui/game_end_tests.cpp index 42c7bf4..807c364 100644 --- a/src/ui/game_end_tests.cpp +++ b/src/ui/game_end_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for source text wrapping and end-of-career rendering (ui/game_end.hpp). #include "ui/game_end.hpp" #include diff --git a/src/ui/host_path.hpp b/src/ui/host_path.hpp index 05f4dee..71ac7a8 100644 --- a/src/ui/host_path.hpp +++ b/src/ui/host_path.hpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tiny helper for showing host directory paths in the UI. The legacy font has no usable backslash glyph, +// so save_directory_label() always formats paths with portable forward separators. #pragma once #include diff --git a/src/ui/incoming_transfer.cpp b/src/ui/incoming_transfer.cpp index c6dbb96..25feec0 100644 --- a/src/ui/incoming_transfer.cpp +++ b/src/ui/incoming_transfer.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the incoming transfer screen declared in incoming_transfer.hpp: building the decision view from +// the game (including the pending-decision variant), rendering bids, player data and notices, and converting +// input into requests. The transfer itself is performed only by the session. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/incoming_transfer.hpp" diff --git a/src/ui/incoming_transfer.hpp b/src/ui/incoming_transfer.hpp index 717e86a..507d04f 100644 --- a/src/ui/incoming_transfer.hpp +++ b/src/ui/incoming_transfer.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Incoming transfer offers: the decision screen where a manager reviews bids on a listed player (four raw +// bid slots) and accepts or declines. IncomingTransferDecisionView is a read-only copy built from the game; +// each UI row keeps the engine's bid slot index. The screen raises requests for the session, which applies +// the transaction. Implementation: incoming_transfer.cpp. #pragma once #include diff --git a/src/ui/incoming_transfer_tests.cpp b/src/ui/incoming_transfer_tests.cpp index 6573032..76b54a4 100644 --- a/src/ui/incoming_transfer_tests.cpp +++ b/src/ui/incoming_transfer_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the incoming transfer decision view and requests (ui/incoming_transfer.hpp). #include "formats/executable_layout.hpp" #include "ui/incoming_transfer.hpp" #include "ui/source_notice_test_helpers.hpp" diff --git a/src/ui/indoor_standings.cpp b/src/ui/indoor_standings.cpp index a3fb447..b6a46aa 100644 --- a/src/ui/indoor_standings.cpp +++ b/src/ui/indoor_standings.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the indoor standings page declared in indoor_standings.hpp: indoor_standings_from_game() copies +// the ranking and title holders from the game, and IndoorStandingsScreen draws the table, footer and prizes. +// Presentation only; it changes no game state. #include "formats/executable_layout.hpp" #include "ui/indoor_standings.hpp" diff --git a/src/ui/indoor_standings.hpp b/src/ui/indoor_standings.hpp index f147d68..d43a12d 100644 --- a/src/ui/indoor_standings.hpp +++ b/src/ui/indoor_standings.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Indoor tournament standings page: a copied ranking of clubs by points, title holders and prize texts. +// indoor_standings_from_game() builds the read-only IndoorStandingsState; IndoorStandingsScreen only +// renders it and raises no requests. No draw or qualification is written here. +// Implementation: indoor_standings.cpp. #pragma once #include diff --git a/src/ui/league_family_request.hpp b/src/ui/league_family_request.hpp index d2af25a..ff3c4e0 100644 --- a/src/ui/league_family_request.hpp +++ b/src/ui/league_family_request.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Shared request types for the family of league screens (table, pairings and the strengths page). +// StrengthsIdentity is the ownership token (manager, club, league, revision, scope, sequence, family +// nonce) that guards against stale requests; LeagueFamilyRequest describes navigation, close, team info, +// control, league selection and table dialog replies. league_table.hpp and league_pairings.hpp use these +// types to talk to the session. #pragma once #include diff --git a/src/ui/league_pairings.cpp b/src/ui/league_pairings.cpp index 950457a..23ee942 100644 --- a/src/ui/league_pairings.cpp +++ b/src/ui/league_pairings.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the league pairings screen declared in league_pairings.hpp: league_pairings_from_game() formats +// the rows and button texts from the game, and LeaguePairingsScreen renders them and queues requests for the +// session. It also defines the constants and time conversion helper declared in the header. #include "formats/executable_layout.hpp" #include "ui/league_pairings.hpp" diff --git a/src/ui/league_pairings.hpp b/src/ui/league_pairings.hpp index 3b7779c..7152953 100644 --- a/src/ui/league_pairings.hpp +++ b/src/ui/league_pairings.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// League pairings screen: the matches of a round with names, results, first legs, dates and temperature, +// and an active-match packet. LeaguePairingsState is built by league_pairings_from_game() and tagged with +// a LeaguePairingsIdentity (revision, scope, sequence). The screen raises LeaguePairingsRequest values, and +// in family mode shares an identity with the league family (league_family_request.hpp). +// Implementation: league_pairings.cpp. #pragma once #include diff --git a/src/ui/league_table.cpp b/src/ui/league_table.cpp index 37bf4a4..432d111 100644 --- a/src/ui/league_table.cpp +++ b/src/ui/league_table.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the league table declared in league_table.hpp: league_table_from_game() and +// league_tables_from_game() project engine tables into rows (ranks, form bits, highlight colours), +// and LeagueTableScreen renders them and the control buttons, handles input, and acknowledges family +// selector changes. Requests go to the session; no game state is written here. #include "formats/executable_layout.hpp" #include "ui/league_table.hpp" diff --git a/src/ui/league_table.hpp b/src/ui/league_table.hpp index dd67348..75b323e 100644 --- a/src/ui/league_table.hpp +++ b/src/ui/league_table.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// League table screen: rank, record, goals, points, previous rank and form per club, with round-range, +// forecast and league selection controls. LeagueTableState is built by league_table_from_game() from an +// explicit LeagueTableProjectionContext; the screen raises LeagueFamilyRequest values and, in family mode, +// shares an identity with the other league family screens (league_family_request.hpp). +// Implementation: league_table.cpp; the numeric dialog lives in league_table_range_dialog.hpp. #pragma once #include diff --git a/src/ui/league_table_range_dialog.cpp b/src/ui/league_table_range_dialog.cpp index 8293484..1954b56 100644 --- a/src/ui/league_table_range_dialog.cpp +++ b/src/ui/league_table_range_dialog.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements LeagueTableRangeDialog declared in league_table_range_dialog.hpp: draws the calculator-style +// numeric dialog over its backdrop, handles pointer, key and text input, and produces a +// TableRangeDialogOutcome. It requires an explicit text mode from the caller instead of guessing a setting. #include "formats/executable_layout.hpp" #include "ui/league_table_range_dialog.hpp" diff --git a/src/ui/league_table_range_dialog.hpp b/src/ui/league_table_range_dialog.hpp index 687969f..a60c4c4 100644 --- a/src/ui/league_table_range_dialog.hpp +++ b/src/ui/league_table_range_dialog.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Numeric dialog used by the league table to pick a start or end matchday, plus the stake dialog profile. +// LeagueTableRangeDialog is an isolated presenter: the caller supplies the already rendered frame under the +// modal, and the object owns that backdrop and its resources. It has no GameState, random generator, save +// writer or mutation callback; the result (accept or cancel, value, position) is returned to the caller. +// Implementation: league_table_range_dialog.cpp. #include "formats/executable_layout.hpp" #pragma once diff --git a/src/ui/league_table_tests.cpp b/src/ui/league_table_tests.cpp index 3d74f18..b6f0a1e 100644 --- a/src/ui/league_table_tests.cpp +++ b/src/ui/league_table_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the league table projection, controls and family requests (ui/league_table.hpp). #include "formats/executable_layout.hpp" #include "ui/league_table.hpp" diff --git a/src/ui/lineup.cpp b/src/ui/lineup.cpp index 91eb238..42a3ee3 100644 --- a/src/ui/lineup.cpp +++ b/src/ui/lineup.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the lineup screen declared in lineup.hpp: lineup_from_game() and lineup_from_save() project +// the squad, and LineupScreen renders both data views and converts clicks into LineupRequest values. +// Swapping or preparing is done by the session, not here. #include "formats/executable_layout.hpp" #include "ui/lineup.hpp" diff --git a/src/ui/lineup.hpp b/src/ui/lineup.hpp index 3558a66..58e5dc7 100644 --- a/src/ui/lineup.hpp +++ b/src/ui/lineup.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Lineup screen: the squad list of the human club with two data views and the actions swap players, +// prepare lineup, open player info and open pitch. LineupState is a read-only copy built by lineup_from_game() +// or lineup_from_save(), tagged with a revision. LineupScreen raises LineupRequest values that the session +// applies; LineupPlayer rows are also reused by the contracts and live intervention headers. +// Implementation: lineup.cpp. #pragma once #include diff --git a/src/ui/lineup_tests.cpp b/src/ui/lineup_tests.cpp index e1a0015..2520bff 100644 --- a/src/ui/lineup_tests.cpp +++ b/src/ui/lineup_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the lineup projection, rendering and request flow (ui/lineup.hpp). #include "formats/executable_layout.hpp" #include "../../tests/test_inputs.hpp" #include "ui/lineup.hpp" diff --git a/src/ui/live_intervention.cpp b/src/ui/live_intervention.cpp index 86d29e7..fdc34ce 100644 --- a/src/ui/live_intervention.cpp +++ b/src/ui/live_intervention.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the live intervention helpers and dialog declared in live_intervention.hpp: building and +// validating substitution, formation, position and tactic proposals against the copied context, serialising +// a proposal to JSON, and rendering the lineup, formation and tactics pages. Proposals are descriptive only. #include "ui/live_intervention.hpp" #include "formats/binary.hpp" diff --git a/src/ui/live_intervention.hpp b/src/ui/live_intervention.hpp index 03f07c0..629166f 100644 --- a/src/ui/live_intervention.hpp +++ b/src/ui/live_intervention.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Manager intervention while a watched match is paused: substitutions, formation, player position and +// tactic changes. LiveInterventionContext is a copied view; the propose_live_* helpers only turn an existing +// preparation request into a LiveInterventionProposal (accepted or rejected with a reason) and never write +// GameState or draw random numbers. LiveInterventionDialog presents the pages and reports resume or +// proposal events. Implementation: live_intervention.cpp. #pragma once #include diff --git a/src/ui/live_intervention_tests.cpp b/src/ui/live_intervention_tests.cpp index 2a13b3e..795f96c 100644 --- a/src/ui/live_intervention_tests.cpp +++ b/src/ui/live_intervention_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for live intervention proposals (ui/live_intervention.hpp). #include "ui/live_intervention.hpp" #include diff --git a/src/ui/live_matchday.cpp b/src/ui/live_matchday.cpp index 7928ca0..3c14470 100644 --- a/src/ui/live_matchday.cpp +++ b/src/ui/live_matchday.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements the live matchday overview declared in live_matchday.hpp: LiveMatchdayScreen and the live +// projection functions declared there. It only observes engine data copied into frames and does not change +// the running match. #include "formats/executable_layout.hpp" #include "ui/live_matchday.hpp" diff --git a/src/ui/live_matchday.hpp b/src/ui/live_matchday.hpp index 0e75a2c..47f250e 100644 --- a/src/ui/live_matchday.hpp +++ b/src/ui/live_matchday.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Live matchday overview: all matches of the day with minute, scores, statistics, attendance and weather, +// plus chance, booking and shoot-out projections. LiveMatchdayFrame is an owned copy made synchronously from +// the engine's observation hook. LiveScoreReveal keeps preview scores until the result hook so simulation is +// not delayed. LiveMatchdayScreen renders frames. Implementation: live_matchday.cpp. #pragma once #include diff --git a/src/ui/live_reality.cpp b/src/ui/live_reality.cpp index 48a53f9..1ef3657 100644 --- a/src/ui/live_reality.cpp +++ b/src/ui/live_reality.cpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements RealityFieldScreen declared in live_reality.hpp: loads the ball and digit atlases for the chosen +// ball style and renders a RealityMotionFrame over the supplied backdrop. Drawing only. #include "ui/live_reality.hpp" #include "ui/setup.hpp" diff --git a/src/ui/live_reality.hpp b/src/ui/live_reality.hpp index 4e75801..9921e80 100644 --- a/src/ui/live_reality.hpp +++ b/src/ui/live_reality.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Reality field renderer: only the lower pitch field of the live reality view, drawn from a motion frame +// and a backdrop. Header and reporter text are owned by the caller; this renderer cannot select a pass, +// a player or a match result. Implementation: live_reality.cpp. #pragma once #include diff --git a/src/ui/live_score_reveal_tests.cpp b/src/ui/live_score_reveal_tests.cpp index fa08bbe..fbfeb53 100644 --- a/src/ui/live_score_reveal_tests.cpp +++ b/src/ui/live_score_reveal_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for LiveScoreReveal keeping preview scores until the result hook (ui/live_matchday.hpp). #include "ui/live_matchday.hpp" #include using namespace bmh::ui; diff --git a/src/ui/live_set_piece.cpp b/src/ui/live_set_piece.cpp index d507098..922833b 100644 --- a/src/ui/live_set_piece.cpp +++ b/src/ui/live_set_piece.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements live_set_piece_frames() declared in live_set_piece.hpp: derives the camera and sprite +// placement of a set-piece scene from the event data and the executable layout, using only values that the +// engine has already drawn. #include "formats/executable_layout.hpp" #include "ui/live_set_piece.hpp" diff --git a/src/ui/live_set_piece.hpp b/src/ui/live_set_piece.hpp index e400330..108470e 100644 --- a/src/ui/live_set_piece.hpp +++ b/src/ui/live_set_piece.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Set-piece animation frames: live_set_piece_frames() converts the values already drawn by the match engine +// for a set piece into camera positions and sprites. It rejects missing, mismatched or surplus draws instead +// of inventing a scene. Implementation: live_set_piece.cpp. #pragma once #include "formats/le.hpp" diff --git a/src/ui/live_timing.hpp b/src/ui/live_timing.hpp index 13cfaf7..3e0a306 100644 --- a/src/ui/live_timing.hpp +++ b/src/ui/live_timing.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Timing helpers for the live match views: live_delay_milliseconds() converts the saved delay setting into +// milliseconds (values below six are halved, zero disables the pause), and kOriginalRefreshHz records the +// fixed 70 Hz mode 13h timing that is independent of the host monitor. #pragma once #include diff --git a/src/ui/mailbox_screen.cpp b/src/ui/mailbox_screen.cpp index 9c503e7..36e0341 100644 --- a/src/ui/mailbox_screen.cpp +++ b/src/ui/mailbox_screen.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements MailboxScreen declared in mailbox_screen.hpp: validates the state, lays out and renders the +// message pages and buttons, handles clicks and keys, and queues keep or delete requests for the app. +// It pairs with mailbox_state.cpp, which builds the state it displays. #include "formats/executable_layout.hpp" #include "ui/mailbox_screen.hpp" diff --git a/src/ui/mailbox_screen.hpp b/src/ui/mailbox_screen.hpp index b076322..64925f1 100644 --- a/src/ui/mailbox_screen.hpp +++ b/src/ui/mailbox_screen.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Mailbox screen: paged view of the manager's messages with keep and delete actions. +// MailboxScreen renders a MailboxState (see mailbox_state.hpp) over the desktop background. Article actions +// are requests (MailboxActionRequest) held in pending(); only the app adapter writes recipient and keep +// bits, then calls acknowledge() with the new state or reject(). Navigation changes neither the +// notification flag nor random generators. Implementation: mailbox_screen.cpp. #pragma once #include diff --git a/src/ui/mailbox_screen_tests.cpp b/src/ui/mailbox_screen_tests.cpp index 8124260..b5a641d 100644 --- a/src/ui/mailbox_screen_tests.cpp +++ b/src/ui/mailbox_screen_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for MailboxScreen paging, rendering and request handling (ui/mailbox_screen.hpp). #include "ui/mailbox_screen.hpp" #include diff --git a/src/ui/mailbox_state.cpp b/src/ui/mailbox_state.cpp index f2d4b04..7b28c9c 100644 --- a/src/ui/mailbox_state.cpp +++ b/src/ui/mailbox_state.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements mailbox_state_from_game() declared in mailbox_state.hpp: filters the mailbox entries for one +// manager, decodes their text and orders them for the reader. It does not modify messages or the date. +// The result feeds MailboxScreen in mailbox_screen.cpp. #include "ui/mailbox_state.hpp" #include diff --git a/src/ui/mailbox_state.hpp b/src/ui/mailbox_state.hpp index 5bb9227..b7cd2a4 100644 --- a/src/ui/mailbox_state.hpp +++ b/src/ui/mailbox_state.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Read-only projection of the mailbox for one manager. MailboxMessage keeps the exact raw entry, recipient and +// keep masks and the decoded text; MailboxState lists them in reader order (date, then physical slot). +// mailbox_state_from_game() never marks, deletes or keeps messages. MailboxActionRequest describes a keep or +// delete action together with the expected raw entry for stale-state checks. Used by mailbox_screen.hpp. #pragma once #include diff --git a/src/ui/mailbox_state_tests.cpp b/src/ui/mailbox_state_tests.cpp index 18496d6..a9fa899 100644 --- a/src/ui/mailbox_state_tests.cpp +++ b/src/ui/mailbox_state_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the mailbox projection: filtering, ordering and identity (ui/mailbox_state.hpp). #include "ui/mailbox_state.hpp" #include diff --git a/src/ui/manager.cpp b/src/ui/manager.cpp index 618e098..977796f 100644 --- a/src/ui/manager.cpp +++ b/src/ui/manager.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements ManagerScreen and load_selection_context() declared in manager.hpp: renders the selection, +// name entry, club picker and confirmation dialogs, handles click, move and text input and keeps the +// current ManagerChoice. The flow applies the confirmed choice; this file does not initialise a career. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/manager.hpp" diff --git a/src/ui/manager.hpp b/src/ui/manager.hpp index 5872650..f5c3193 100644 --- a/src/ui/manager.hpp +++ b/src/ui/manager.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Manager selection screens: selection, name edit, club picker, confirmation and accepted view for one +// manager slot. ManagerScreen owns only UI choices (ManagerChoice) and works with a SelectionContext, the +// club order loaded by load_selection_context(). ManagerChoice uses master database club ids, not the remapped +// team ids of an initialised career; the roster revision guards against applying an id to a later club order. +// Implementation: manager.cpp. #pragma once #include diff --git a/src/ui/manager_tests.cpp b/src/ui/manager_tests.cpp index 01daa25..179e83e 100644 --- a/src/ui/manager_tests.cpp +++ b/src/ui/manager_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for ManagerScreen selection, name entry and confirmation (ui/manager.hpp). #include #include #include diff --git a/src/ui/matchday_results.cpp b/src/ui/matchday_results.cpp index 725cb6a..56542b1 100644 --- a/src/ui/matchday_results.cpp +++ b/src/ui/matchday_results.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements matchday_results_from_snapshot() declared in matchday_results.hpp: converts a turn result +// snapshot and the game state into MatchdayResults groups (names, scores, status, cup decision), without +// modifying either. The result is displayed by matchday_results_screen.cpp. #include "formats/executable_layout.hpp" #include "ui/matchday_results.hpp" diff --git a/src/ui/matchday_results.hpp b/src/ui/matchday_results.hpp index 8d499d5..461e1df 100644 --- a/src/ui/matchday_results.hpp +++ b/src/ui/matchday_results.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Immutable UI copy of the results of one matchday, grouped by competition. MatchResultStatus and +// MatchdayResultMatch carry UTF-8 names and goals (a cup match also records whether it was decided in +// extra time or on penalties), plus league or cup ids. It owns no engine references. +// Built by matchday_results_from_snapshot() in matchday_results.cpp and shown by MatchdayResultsScreen. #pragma once #include diff --git a/src/ui/matchday_results_screen.cpp b/src/ui/matchday_results_screen.cpp index fd841c4..f624622 100644 --- a/src/ui/matchday_results_screen.cpp +++ b/src/ui/matchday_results_screen.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements MatchdayResultsScreen declared in matchday_results_screen.hpp: lays the groups and matches out +// into rows and pages, draws names and scores with the original font, and handles paging and close input. +// Presentation only; the data comes from matchday_results.cpp. #include "ui/matchday_results_screen.hpp" #include diff --git a/src/ui/matchday_results_screen.hpp b/src/ui/matchday_results_screen.hpp index 30ae487..7deaa05 100644 --- a/src/ui/matchday_results_screen.hpp +++ b/src/ui/matchday_results_screen.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Paged screen listing the matchday results held in a MatchdayResults copy (matchday_results.hpp). +// MatchdayResultsScreen renders pages, handles click and key input and reports close_requested(); it also +// offers state_json(). It holds no engine access. Implementation: matchday_results_screen.cpp. #pragma once #include diff --git a/src/ui/matchday_results_tests.cpp b/src/ui/matchday_results_tests.cpp index 4fcc254..eac7789 100644 --- a/src/ui/matchday_results_tests.cpp +++ b/src/ui/matchday_results_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the matchday results projection and screen (ui/matchday_results.hpp, ui/matchday_results_screen.hpp). #include "formats/executable_layout.hpp" #include "ui/matchday_results_screen.hpp" diff --git a/src/ui/minute_statistics.cpp b/src/ui/minute_statistics.cpp index e811b17..5e998f1 100644 --- a/src/ui/minute_statistics.cpp +++ b/src/ui/minute_statistics.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implements minute_statistics_from_game() and MinuteStatisticsScreen declared in minute_statistics.hpp: +// copies the four stored series for a manager and draws the chart atlas and text over the supplied +// underlay. handle_source_event() sets the closed flag; no game state is written. #include "formats/executable_layout.hpp" #include "ui/minute_statistics.hpp" diff --git a/src/ui/minute_statistics.hpp b/src/ui/minute_statistics.hpp index 7a47fb6..88de1d2 100644 --- a/src/ui/minute_statistics.hpp +++ b/src/ui/minute_statistics.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Minute statistics page: an overlay chart of four stored 18-byte series from the manager record, drawn on +// top of the accepted underlay of the parent statistics page (page 8). MinuteStatisticsProjection keeps every +// stored byte. MinuteStatisticsScreen only renders and closes on a source event code; it adds no title or +// controls. Built by minute_statistics_from_game(). Implementation: minute_statistics.cpp. #pragma once #include diff --git a/src/ui/minute_statistics_tests.cpp b/src/ui/minute_statistics_tests.cpp index 4eb5757..7d497cb 100644 --- a/src/ui/minute_statistics_tests.cpp +++ b/src/ui/minute_statistics_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the minute statistics projection and overlay (ui/minute_statistics.hpp). #include "ui/minute_statistics.hpp" #include diff --git a/src/ui/national_friendly_ui.cpp b/src/ui/national_friendly_ui.cpp index 36397f9..9c47109 100644 --- a/src/ui/national_friendly_ui.cpp +++ b/src/ui/national_friendly_ui.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the national-team friendly stage machine declared in national_friendly_ui.hpp. +// Builds the cost and payer question dialogs from the GameState and returns the next action; it never books +// anything itself, the session answers the quote and booking requests. #include "formats/executable_layout.hpp" #include "national_friendly_ui.hpp" diff --git a/src/ui/national_friendly_ui.hpp b/src/ui/national_friendly_ui.hpp index b924a10..3734598 100644 --- a/src/ui/national_friendly_ui.hpp +++ b/src/ui/national_friendly_ui.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// National-team friendly flow: a stage machine (picker, venue question, quote, cost and payer questions, +// calendar, booking) that is only constructed by the verified menu-6 caller, never by the normal Desk menu 23. +// State: the caller-owned owner token, manager/opponent identities and the current stage. +// Every step returns an action (open picker, quote, show question, book, return) for the session to carry out; +// quotes and bookings come back from the session and are only accepted via accept_quote / accept_booking. +// Implemented in national_friendly_ui.cpp. #pragma once #include diff --git a/src/ui/opportunities.cpp b/src/ui/opportunities.cpp index cdab615..cf894bd 100644 --- a/src/ui/opportunities.cpp +++ b/src/ui/opportunities.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of StatisticsMenuScreen and OpportunitiesScreen (see opportunities.hpp): rendering from the +// original executable layout tables and art, pointer/key handling, and the pending-request/acknowledge flow. +// Drawing never changes the projection; only an acknowledged state replaces the displayed one. #include "formats/executable_layout.hpp" #include "ui/opportunities.hpp" diff --git a/src/ui/opportunities.hpp b/src/ui/opportunities.hpp index c535193..9d9270c 100644 --- a/src/ui/opportunities.hpp +++ b/src/ui/opportunities.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Two Desk statistics screens: the statistics menu (StatisticsMenuScreen) and the Opportunities screen +// (OpportunitiesScreen), which shows a rank ladder of reachable, possible and secured league positions. +// State: identity guards (manager, club, day counter, revision) plus the ladder projection and a captured +// underlay image. Input produces a pending request (mode A..D or close) that the session acknowledges with a +// new state or rejects; the menu returns a typed request naming the child page to open. #pragma once #include diff --git a/src/ui/opportunities_tests.cpp b/src/ui/opportunities_tests.cpp index 473dde1..6bac134 100644 --- a/src/ui/opportunities_tests.cpp +++ b/src/ui/opportunities_tests.cpp @@ -1,5 +1,6 @@ #include "../../tests/test_inputs.hpp" // SPDX-License-Identifier: GPL-3.0-only +// Tests for OpportunitiesScreen and StatisticsMenuScreen: mode buttons, rank strip clipping, owner refresh and request guards. #include "formats/executable_layout.hpp" #include "ui/opportunities.hpp" #include "ui/manager.hpp" diff --git a/src/ui/other_games.cpp b/src/ui/other_games.cpp index c4bf917..9025f24 100644 --- a/src/ui/other_games.cpp +++ b/src/ui/other_games.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of OtherGamesScreen (other_games.hpp): draws the source panel, selector, arrows and fixture +// rows with the original fonts, and hit-tests fixtures and buttons. It never writes game state; navigation is +// only requested through pending() and takes effect when the session returns a new state. #include "formats/executable_layout.hpp" #include "ui/other_games.hpp" diff --git a/src/ui/other_games.hpp b/src/ui/other_games.hpp index 2447418..bd3ed68 100644 --- a/src/ui/other_games.hpp +++ b/src/ui/other_games.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Other games Desk screen: competition selector, round arrows, fixture rows and a compact/full display toggle. +// Renders an OtherGamesState (see other_games_state.hpp) and owns only pressed-button and rejection state. +// Clicks become a pending OtherGamesRequest (selector slot, round change, team info, close) carrying the +// identity guards; the session applies it and supplies a new state or calls reject_action. Implemented in other_games.cpp. #pragma once #include diff --git a/src/ui/other_games_state.cpp b/src/ui/other_games_state.cpp index f13bca6..0076b02 100644 --- a/src/ui/other_games_state.cpp +++ b/src/ui/other_games_state.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of other_games_state_from_game(): builds fixture rows, selector labels, headings and table rows +// for one competition, linked page and round from the GameState and original text tables. Pure projection: +// it reads the game and executable data but does not mutate either. #include "formats/executable_layout.hpp" #include "ui/other_games_state.hpp" diff --git a/src/ui/other_games_state.hpp b/src/ui/other_games_state.hpp index a801a5c..23a18c6 100644 --- a/src/ui/other_games_state.hpp +++ b/src/ui/other_games_state.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Data model for the Other games screen: identity guards, typed request, display and table rows, and the +// projection struct. other_games_state_from_game() formats immutable game bytes into display strings while the +// GameState is available. Opening and navigation writes belong to the session, never to this value adapter. +// Paired with other_games.hpp/other_games.cpp (renderer) and other_games_state.cpp. #pragma once #include diff --git a/src/ui/outgoing_transfer.cpp b/src/ui/outgoing_transfer.cpp index 841614c..388d992 100644 --- a/src/ui/outgoing_transfer.cpp +++ b/src/ui/outgoing_transfer.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of OutgoingTransferScreen (outgoing_transfer.hpp): draws the bid rows and the money/mode-3 +// calculators, handles click, key and text input, and builds the request JSON used by tests and tooling. +// It reuses IncomingTransferScreen for the shared panel; the quote values are carried as owner context and +// never recomputed here. #include "formats/executable_layout.hpp" #include "ui/outgoing_transfer.hpp" diff --git a/src/ui/outgoing_transfer.hpp b/src/ui/outgoing_transfer.hpp index d912e8a..38362ec 100644 --- a/src/ui/outgoing_transfer.hpp +++ b/src/ui/outgoing_transfer.hpp @@ -1,4 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-only +// Interactive editor for an outgoing transfer bid (fee, monthly salary, contract years, seven bonus fields +// and a loan quote toggle) with the original number calculator. State: OutgoingTransferEditorState wrapping the +// shared incoming-transfer panel, plus a confirmed copy. Edits become typed OutgoingTransferRequests (edit field, +// quote change, team/player info, submit, cancel) with identity guards; the session acknowledges with a new +// state or rejects. The renderer must not invent calculator limits: they are supplied by the caller. +// Implemented in outgoing_transfer.cpp. #pragma once #include diff --git a/src/ui/outgoing_transfer_tests.cpp b/src/ui/outgoing_transfer_tests.cpp index f43a526..e957d22 100644 --- a/src/ui/outgoing_transfer_tests.cpp +++ b/src/ui/outgoing_transfer_tests.cpp @@ -1,5 +1,6 @@ #include "../../tests/test_inputs.hpp" // SPDX-License-Identifier: GPL-3.0-only +// Tests for OutgoingTransferScreen: calculator typing and cancellation, process-timer expiry, and the submit/cancel/info requests. #include "ui/outgoing_transfer.hpp" #include diff --git a/src/ui/pending_offer.cpp b/src/ui/pending_offer.cpp index 04b689c..5137e87 100644 --- a/src/ui/pending_offer.cpp +++ b/src/ui/pending_offer.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the presenters declared in pending_offer.hpp: composes dialog bodies from original text +// templates and GameState values, and resolves the owning team for a manager, including the restored +// post-national-desk owner. Read-only with respect to the GameState. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/pending_offer.hpp" diff --git a/src/ui/pending_offer.hpp b/src/ui/pending_offer.hpp index e55cb2c..a17c1ad 100644 --- a/src/ui/pending_offer.hpp +++ b/src/ui/pending_offer.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Pure presenters that turn pending club/player events (transfer offers, loan returns, advertising renewals, +// stadium construction notices, season-ticket compensation) into TaxDialogProjection dialogs, plus the +// transfer-decision panel projection. Text stays in the original single-byte encoding until drawn. +// No state is owned and no game state is changed; the session shows the dialogs and applies the answers. +// Implemented in pending_offer.cpp. #pragma once #include diff --git a/src/ui/pitch.cpp b/src/ui/pitch.cpp index e4fc8c0..3fa2b41 100644 --- a/src/ui/pitch.cpp +++ b/src/ui/pitch.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of PitchScreen and the pitch_extras_from_save/game projections (pitch.hpp): board geometry, +// drag-and-drop, formation and set-piece editors, and request construction. Rendering does not mutate the +// authoritative positions; changes only appear after the session acknowledges a new lineup and extras. #include "formats/executable_layout.hpp" #include "ui/pitch.hpp" diff --git a/src/ui/pitch.hpp b/src/ui/pitch.hpp index 5035e3a..1397521 100644 --- a/src/ui/pitch.hpp +++ b/src/ui/pitch.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Pitch / team-sheet screen: drag and swap players on the formation board, choose formations, automatic +// weights, set-piece takers, player order and marking. State: the lineup projection plus PitchExtras (indoor +// flag, formations, set-piece takers, live opponent players), which is owned context outside the squad data. +// Every placement emits a PitchRequest with revision guards; only an acknowledged projection updates the rows. +// The indoor flag is transient and never inferred from a saved file. Implemented in pitch.cpp. #pragma once #include "ui/lineup.hpp" diff --git a/src/ui/pitch_tests.cpp b/src/ui/pitch_tests.cpp index f8beccb..2cbc040 100644 --- a/src/ui/pitch_tests.cpp +++ b/src/ui/pitch_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for PitchScreen: drag/swap requests, rendering without mutating positions, hover and affinity colors, set-piece editor and team-sheet actions. #include "formats/executable_layout.hpp" #include "ui/pitch.hpp" #include "ui/source_hold.hpp" diff --git a/src/ui/player_card.cpp b/src/ui/player_card.cpp index 31a4026..8a9641e 100644 --- a/src/ui/player_card.cpp +++ b/src/ui/player_card.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of PlayerCardScreen and its projections (player_card.hpp): portrait, attribute and loan +// rendering, the statistics graph (player_statistics_points), and the market-value helper. Rendering is +// deterministic and uses no engine RNG. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/player_card.hpp" diff --git a/src/ui/player_card.hpp b/src/ui/player_card.hpp index 188c09e..a5d4077 100644 --- a/src/ui/player_card.hpp +++ b/src/ui/player_card.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Player card screen for a player of the active manager squad, with the monthly statistics curves sub-view. +// State: PlayerCardState (lineup row, club/nationality names, optional loan and statistics context) and local +// UI flags. Unsupported cases (loan, negotiation) are reported in the state, and no request is sent to the +// engine. player_card_market_value() deliberately returns unknown where the original draws random numbers. +// Implemented in player_card.cpp. #pragma once #include "ui/lineup.hpp" diff --git a/src/ui/player_card_tests.cpp b/src/ui/player_card_tests.cpp index 4039126..c10592a 100644 --- a/src/ui/player_card_tests.cpp +++ b/src/ui/player_card_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for PlayerCardScreen: deterministic rendering, club/nationality text, statistics plot coordinates and closed-card navigation. #include "formats/executable_layout.hpp" #include "ui/player_card.hpp" diff --git a/src/ui/preparation.cpp b/src/ui/preparation.cpp index 39bd0ae..6e43f78 100644 --- a/src/ui/preparation.cpp +++ b/src/ui/preparation.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of preparation_from_game(), load_preparation_reference(), validate_preparation_context() and +// preparation_request_json() declared in preparation.hpp: assembles each sub-screen projection for the active +// manager and checks that the parts are consistent. #include "formats/native_save_version.hpp" #include "formats/executable_layout.hpp" #include "ui/preparation.hpp" diff --git a/src/ui/preparation.hpp b/src/ui/preparation.hpp index 7032f8d..c71449c 100644 --- a/src/ui/preparation.hpp +++ b/src/ui/preparation.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Aggregate pre-match state: PreparationState bundles the Desk, lineup, training, training camp, bank, stadium, +// toto, transfer market, tactics, pitch extras and player cards under one revision, and PreparationRequest is +// the variant of all their requests. preparation_from_game() builds it without executing the engine. +// Used by the startup flow (flow.hpp, preparation_flow.cpp); implemented in preparation.cpp. #pragma once #include diff --git a/src/ui/preparation_flow.cpp b/src/ui/preparation_flow.cpp index b4e2336..cd1ba31 100644 --- a/src/ui/preparation_flow.cpp +++ b/src/ui/preparation_flow.cpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Part of StartupFlow (declared in flow.hpp): the show_*/finish_*/acknowledge_*/close_* methods that open and +// close the Desk child pages (strengths, top scorers, opportunities, statistics menu and rankings, other games, +// league tables, calendar, mailbox, settings, advertising and more). Handlers check the new state against the +// owning Desk request before swapping the current screen; screens only emit requests, the flow forwards them. #include "formats/executable_layout.hpp" #include "ui/flow.hpp" diff --git a/src/ui/preparation_tests.cpp b/src/ui/preparation_tests.cpp index 29b6e7c..65338f3 100644 --- a/src/ui/preparation_tests.cpp +++ b/src/ui/preparation_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the pre-match preparation flow: owner handling, pending acknowledgements, and expiry/close behaviour of the stadium, balance and advertising pages. #include "formats/executable_layout.hpp" #include "ui/flow.hpp" diff --git a/src/ui/process_timer.cpp b/src/ui/process_timer.cpp index b66b982..df4bb62 100644 --- a/src/ui/process_timer.cpp +++ b/src/ui/process_timer.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of ProcessTimer (process_timer.hpp): countdown arithmetic from host timestamps and the paint routine using the executable layout data. #include "formats/executable_layout.hpp" #include "ui/process_timer.hpp" #include diff --git a/src/ui/reality_reporter.cpp b/src/ui/reality_reporter.cpp index 9a77f06..b3d9aa2 100644 --- a/src/ui/reality_reporter.cpp +++ b/src/ui/reality_reporter.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of RealityReporterPanel (reality_reporter.hpp): hyphenation rules from the executable, justified line drawing and scrolling of the report area. #include "formats/executable_layout.hpp" #include "ui/reality_reporter.hpp" diff --git a/src/ui/reality_reporter.hpp b/src/ui/reality_reporter.hpp index 25213c4..0e23c06 100644 --- a/src/ui/reality_reporter.hpp +++ b/src/ui/reality_reporter.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Text layout panel for the live reality reporter commentary: appends already selected original-byte text to a +// 320x240 surface, with word wrapping, justification and syllable hyphenation. State: RealityReporterLayoutState +// (next baseline, pending text, recorded word ends), kept by the caller between calls. +// No template evaluation, GameState access, timer or RNG here. Implemented in reality_reporter.cpp. #pragma once #include diff --git a/src/ui/save_load.cpp b/src/ui/save_load.cpp index 7723ff9..456576d 100644 --- a/src/ui/save_load.cpp +++ b/src/ui/save_load.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of SaveLoadScreen (save_load.hpp): lists matching files, draws the list, filename box and +// footer, handles double-click, keyboard and text editing, and arms the overwrite confirmation before +// emitting a request. Picker interaction alone never writes a file. #include "formats/native_save_version.hpp" #include "formats/executable_layout.hpp" #include "ui/save_load.hpp" diff --git a/src/ui/save_load.hpp b/src/ui/save_load.hpp index 5ccb851..bd58f91 100644 --- a/src/ui/save_load.hpp +++ b/src/ui/save_load.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// File picker screen for loading and saving games, menu layouts and settings files. State: directory listing, +// selection and scroll, typed filename, overwrite confirmation and info popup. It never reads or writes the +// chosen file itself: a click or key produces a pending SaveLoadRequest (action, path, overwrite flag) that the +// session performs and then confirms with acknowledge() or reject(). Implemented in save_load.cpp. #pragma once #include diff --git a/src/ui/save_load_tests.cpp b/src/ui/save_load_tests.cpp index 76a1f25..ee992bd 100644 --- a/src/ui/save_load_tests.cpp +++ b/src/ui/save_load_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for SaveLoadScreen: no writes from picker input, overwrite confirmation, cancel paths, and filename editing. #include "ui/save_load.hpp" #include "ui/flow.hpp" diff --git a/src/ui/season_entrants.cpp b/src/ui/season_entrants.cpp index 03c3dff..cd3c871 100644 --- a/src/ui/season_entrants.cpp +++ b/src/ui/season_entrants.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of season_entrants_from_game() and SeasonEntrantsScreen (season_entrants.hpp): placement tables from the executable, badge atlas drawing and footer text. #include "formats/executable_layout.hpp" #include "ui/season_entrants.hpp" diff --git a/src/ui/season_entrants.hpp b/src/ui/season_entrants.hpp index 0f48670..1530ea1 100644 --- a/src/ui/season_entrants.hpp +++ b/src/ui/season_entrants.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Season-start pages listing the German entrants of the UEFA, Champions League and Cup Winners Cup +// competitions with their badges. season_entrants_from_game() projects those pages (empty when the original +// guards suppress them) and SeasonEntrantsScreen draws one page. Draw-only: no input, request or engine state. +// Implemented in season_entrants.cpp. #pragma once #include diff --git a/src/ui/season_entrants_tests.cpp b/src/ui/season_entrants_tests.cpp index 5354177..da6137d 100644 --- a/src/ui/season_entrants_tests.cpp +++ b/src/ui/season_entrants_tests.cpp @@ -1,5 +1,6 @@ #include "../../tests/test_inputs.hpp" // SPDX-License-Identifier: GPL-3.0-only +// Tests for season_entrants_from_game(): footer order, untouched competition pools, and suppression in non-league mode. #include "formats/executable_layout.hpp" #include "ui/season_entrants.hpp" diff --git a/src/ui/season_promotion.cpp b/src/ui/season_promotion.cpp index 1b00886..d204670 100644 --- a/src/ui/season_promotion.cpp +++ b/src/ui/season_promotion.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of SeasonPromotionScreen and season_promotion_from_game() (season_promotion.hpp): club columns, badges, league footer and the scanline exchange frames. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/season_promotion.hpp" diff --git a/src/ui/season_promotion.hpp b/src/ui/season_promotion.hpp index a10cf3f..6500d78 100644 --- a/src/ui/season_promotion.hpp +++ b/src/ui/season_promotion.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Season-end promotion/relegation page: SeasonPromotionProjection lists relegated and promoted clubs for one +// league group and SeasonPromotionScreen draws it, including the scanline transition steps (0 to 38). +// Draw-only; the caller owns transition order, waits and whether the animation is suppressed. +// season_promotion_from_game() builds the projection from a SeasonPromotionEvent. Implemented in season_promotion.cpp. #pragma once #include diff --git a/src/ui/series_records.cpp b/src/ui/series_records.cpp index 76e5129..a9e10ef 100644 --- a/src/ui/series_records.cpp +++ b/src/ui/series_records.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of series_records_from_game() and SeriesRecordsScreen (series_records.hpp): record decoding, streak tables and text drawing with the original font. #include "formats/executable_layout.hpp" #include "series_records.hpp" diff --git a/src/ui/series_records.hpp b/src/ui/series_records.hpp index 2d29121..ae6df31 100644 --- a/src/ui/series_records.hpp +++ b/src/ui/series_records.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Series records page (streaks and best series per league view) opened from a Desk statistics page. +// series_records_from_game() projects the saved records, league tables and streak bytes of one manager; +// SeriesRecordsScreen draws them over the accepted parent frame. Draw-only: no request or acknowledge flow. +// Implemented in series_records.cpp. #pragma once #include diff --git a/src/ui/series_records_tests.cpp b/src/ui/series_records_tests.cpp index b15e51a..74e863c 100644 --- a/src/ui/series_records_tests.cpp +++ b/src/ui/series_records_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the series records projection: independent source flag columns and the combined home/away column. #include "formats/executable_layout.hpp" #include "series_records.hpp" diff --git a/src/ui/settings.cpp b/src/ui/settings.cpp index d658811..5853157 100644 --- a/src/ui/settings.cpp +++ b/src/ui/settings.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of SettingsScreen, SettingsReadmeScreen and settings_from_game() (settings.hpp): row/column +// layout from the executable, toggle and arrow handling, availability rules, and the readme text viewer. +// Raw bytes are preserved; availability bits and the value 2 are not treated as booleans. #include "formats/executable_layout.hpp" #include "ui/settings.hpp" diff --git a/src/ui/settings.hpp b/src/ui/settings.hpp index b0e5c6b..4fafe98 100644 --- a/src/ui/settings.hpp +++ b/src/ui/settings.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Settings screen over the 180 saved setting bytes of a manager, plus the in-settings readme viewer +// (SettingsReadmeScreen). SettingsState keeps the raw bytes unmodified; the display copy with entry-time +// availability is derived by project_settings_availability(). An edit becomes a SettingsWriteRequest holding the +// expected raw bytes; file actions use SaveLoadRequest. The session answers with acknowledge()/reject(). +// Implemented in settings.cpp. #pragma once #include diff --git a/src/ui/settings_tests.cpp b/src/ui/settings_tests.cpp index 8cd6822..0159e28 100644 --- a/src/ui/settings_tests.cpp +++ b/src/ui/settings_tests.cpp @@ -1,5 +1,6 @@ #include "../../tests/runtime_fixture_tables.hpp" // SPDX-License-Identifier: GPL-3.0-only +// Tests for the settings screen: availability rules, edit requests, sound capabilities and the readme viewer paging. #include "formats/executable_layout.hpp" #include "ui/settings.hpp" diff --git a/src/ui/setup.cpp b/src/ui/setup.cpp index 2fb490b..02b57f8 100644 --- a/src/ui/setup.cpp +++ b/src/ui/setup.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of SetupScreen (setup.hpp): layout tables read from the executable, shared render and hit-testing, and the limits between managers and league/world options. #include "formats/executable_layout.hpp" #include "ui/setup.hpp" diff --git a/src/ui/setup.hpp b/src/ui/setup.hpp index f34f961..2a0323c 100644 --- a/src/ui/setup.hpp +++ b/src/ui/setup.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Start-up setup screen: season duration, difficulty, number of managers, game mode and league/world options, +// with buttons to start a new game or load one. State: SetupOptions in the original representation (duration 5 = +// unlimited, difficulty 0..9 shown as 1..10). It mutates only its own options; a click can return a +// SetupRequest (new or load) for the caller to act on. Implemented in setup.cpp. #pragma once #include diff --git a/src/ui/source_notice_test_helpers.hpp b/src/ui/source_notice_test_helpers.hpp index 0bdf31a..722cbb3 100644 --- a/src/ui/source_notice_test_helpers.hpp +++ b/src/ui/source_notice_test_helpers.hpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Test helper shared by UI tests: checks that a notice dialog uses the original red exclamation-mark art. #pragma once #include #include "formats/vga.hpp" diff --git a/src/ui/sportschau.cpp b/src/ui/sportschau.cpp index d8382a2..d34fd18 100644 --- a/src/ui/sportschau.cpp +++ b/src/ui/sportschau.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the Sportschau renderers declared in sportschau.hpp: frame composition from the original image atlases, position tables, and text drawing. No GameState writes. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/sportschau.hpp" diff --git a/src/ui/sportschau.hpp b/src/ui/sportschau.hpp index 5640ceb..0c5cc5e 100644 --- a/src/ui/sportschau.hpp +++ b/src/ui/sportschau.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Sportschau (sports show) presentation screens: competition winner page, the intro animation, the matchday +// intro, the eleven-player selection, team info and the matchday report. All are pure renderers over owned +// inputs and original art; they hold no match or engine state. Timing, input pumping and audio belong to the +// caller, and palette overrides are exposed for the caller to install. Implemented in sportschau.cpp. #pragma once #include diff --git a/src/ui/sprite_font.cpp b/src/ui/sprite_font.cpp index 7251569..455f04f 100644 --- a/src/ui/sprite_font.cpp +++ b/src/ui/sprite_font.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of SpriteFont (sprite_font.hpp): glyph interval lookup, width measurement and seven-pixel row blitting from the atlas. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/sprite_font.hpp" diff --git a/src/ui/sprite_font.hpp b/src/ui/sprite_font.hpp index 06110f0..361bb40 100644 --- a/src/ui/sprite_font.hpp +++ b/src/ui/sprite_font.hpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Sprite font that draws text from the glyph atlas of the original executable (modes 5 and 6); stateless apart from the loaded atlas and shared by any screen using that font. #pragma once #include diff --git a/src/ui/sprite_font_tests.cpp b/src/ui/sprite_font_tests.cpp index d28137c..399c705 100644 --- a/src/ui/sprite_font_tests.cpp +++ b/src/ui/sprite_font_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for SpriteFont: mode-5 text width, space advance and title centering. #include "formats/executable_layout.hpp" #include "ui/sprite_font.hpp" diff --git a/src/ui/stadium.cpp b/src/ui/stadium.cpp index f20fc59..48ada72 100644 --- a/src/ui/stadium.cpp +++ b/src/ui/stadium.cpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of StadiumScreen and stadium_data_from_game()/stadium_data_points() (stadium.hpp): rendering of +// the scene, investment dialogs, block calculator and data page, pointer and key handling, and request +// construction. Source-tick timing for the calculator is advanced by the caller. #include "formats/executable_layout.hpp" #include "ui/stadium.hpp" diff --git a/src/ui/stadium.hpp b/src/ui/stadium.hpp index 56203ee..c9047a6 100644 --- a/src/ui/stadium.hpp +++ b/src/ui/stadium.hpp @@ -1,4 +1,9 @@ // SPDX-License-Identifier: GPL-3.0-only +// Stadium screen family: investment list, block expansion editor, data charts, panorama scene and the +// construction tip/notice dialogs with the money calculator. State: StadiumState with investment rows, +// block overviews and a data projection. Actions become StadiumRequests with revision guards; edits stay +// presentation state until the session returns an accepted projection via acknowledge() or reject_action(). +// Implemented in stadium.cpp. #pragma once #include diff --git a/src/ui/statistics_rankings.cpp b/src/ui/statistics_rankings.cpp index d6925cb..96cb853 100644 --- a/src/ui/statistics_rankings.cpp +++ b/src/ui/statistics_rankings.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of statistics_rankings_from_game() and StatisticsRankingsScreen (statistics_rankings.hpp): season paging, category buttons with press/cancel handling, and list drawing. #include "formats/executable_layout.hpp" #include "ui/statistics_rankings.hpp" diff --git a/src/ui/statistics_rankings.hpp b/src/ui/statistics_rankings.hpp index e500ec5..4fedffb 100644 --- a/src/ui/statistics_rankings.hpp +++ b/src/ui/statistics_rankings.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Historical title rankings page (nine title lists across seasons) opened as a child of the statistics menu. +// StatisticsRankingState holds title holders, club names and colors per category plus the visible page; +// statistics_rankings_from_game() builds it. Clicking a category yields a typed request for the parent menu +// (select_category or close). Implemented in statistics_rankings.cpp. #pragma once #include diff --git a/src/ui/statistics_rankings_tests.cpp b/src/ui/statistics_rankings_tests.cpp index 5d481fa..c89e285 100644 --- a/src/ui/statistics_rankings_tests.cpp +++ b/src/ui/statistics_rankings_tests.cpp @@ -1,5 +1,6 @@ #include "../../tests/test_inputs.hpp" // SPDX-License-Identifier: GPL-3.0-only +// Tests for StatisticsRankingsScreen: category selection requests, pressed-state cancel on move-off, and reachability of the oldest archived rows. #include "formats/executable_layout.hpp" #include "ui/statistics_rankings.hpp" #include "ui/setup.hpp" diff --git a/src/ui/strengths.cpp b/src/ui/strengths.cpp index 44275fe..c2131ae 100644 --- a/src/ui/strengths.cpp +++ b/src/ui/strengths.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of StrengthsScreen (strengths.hpp): column and selector drawing, button hit-testing and construction of the pending requests. #include "formats/executable_layout.hpp" #include "ui/strengths.hpp" diff --git a/src/ui/strengths.hpp b/src/ui/strengths.hpp index 1186ada..1bbf620 100644 --- a/src/ui/strengths.hpp +++ b/src/ui/strengths.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Team strengths screen for one league: sortable columns (condition, technique, form, morale and position +// averages), league selector and group toggle, with links to pairings, table and team info. Renders a +// StrengthsState; clicks become a pending StrengthsRequest with identity guards that the session acknowledges +// or rejects. The projection and control-word rules live in strengths_state.hpp. Implemented in strengths.cpp. #pragma once #include "formats/font.hpp" diff --git a/src/ui/strengths_state.cpp b/src/ui/strengths_state.cpp index 94ac81c..ac3e38e 100644 --- a/src/ui/strengths_state.cpp +++ b/src/ui/strengths_state.cpp @@ -1,4 +1,6 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the strengths projection and settings-word helpers (strengths_state.hpp). Pure projection: +// throws FormatError for incomplete save state and uses no RNG; settings words are returned, never stored. #include "formats/executable_layout.hpp" #include "ui/strengths_state.hpp" diff --git a/src/ui/strengths_state.hpp b/src/ui/strengths_state.hpp index 12e41a1..2092081 100644 --- a/src/ui/strengths_state.hpp +++ b/src/ui/strengths_state.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Data model for the strengths screen: control enum, identity guards, row and projection types, and the age +// scratch cache. strengths_from_game() projects one manager league; the *_source helpers reproduce the +// original settings-word handling (draw words, control words, family word) and only return values, the owner +// decides whether to persist them. Paired with strengths.hpp/strengths.cpp. #pragma once #include diff --git a/src/ui/tactics.cpp b/src/ui/tactics.cpp index f6cc070..fab5219 100644 --- a/src/ui/tactics.cpp +++ b/src/ui/tactics.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of TacticsScreen and the tactics_from_save/game projections (tactics.hpp): option arrow cycling, board drawing and request JSON; changes are never committed locally. #include "formats/executable_layout.hpp" #include "ui/tactics.hpp" diff --git a/src/ui/tactics.hpp b/src/ui/tactics.hpp index dcb1b3a..722df9f 100644 --- a/src/ui/tactics.hpp +++ b/src/ui/tactics.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tactics screen: board of ten outfield positions (depth and lane) and the tactic option arrows, including the +// assistant attitude. State: TacticsState projected from a save or the live game. A click or key returns a +// TacticsRequest (set_tactic with the desired value, and optionally a new assistant attitude) carrying revision +// guards; the session applies it and calls acknowledge() or reject_action(). Implemented in tactics.cpp. #pragma once #include diff --git a/src/ui/tactics_tests.cpp b/src/ui/tactics_tests.cpp index eb8b35d..af878b4 100644 --- a/src/ui/tactics_tests.cpp +++ b/src/ui/tactics_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for TacticsScreen: projection of board and options, wrap-around of arrows and wings, and that requests do not fake committed state. #include "formats/executable_layout.hpp" #include "ui/tactics.hpp" diff --git a/src/ui/team_statistics.cpp b/src/ui/team_statistics.cpp index adeb4f0..fc39e1d 100644 --- a/src/ui/team_statistics.cpp +++ b/src/ui/team_statistics.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the team statistics projection and screen (team_statistics.hpp): league calculations, record and head-to-head panels, badge drawing and the position-history chart. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/team_statistics.hpp" diff --git a/src/ui/team_statistics.hpp b/src/ui/team_statistics.hpp index 06408cb..2efc102 100644 --- a/src/ui/team_statistics.hpp +++ b/src/ui/team_statistics.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Team statistics page (home, away or combined) for one club in a league: table figures, strength averages, +// season record, head-to-head against the active manager and position history. TeamStatisticsProjection is an +// owned, read-only input built from the league table model; the screen draws it. Implemented in team_statistics.cpp. #pragma once #include diff --git a/src/ui/tests.cpp b/src/ui/tests.cpp index 08217e3..06a9926 100644 --- a/src/ui/tests.cpp +++ b/src/ui/tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Test driver for the setup screen: needs the original data directory as its single argument and checks defaults, limits, requests and rendering size. #include #include diff --git a/src/ui/top_scorers.cpp b/src/ui/top_scorers.cpp index 3a70151..6ed118f 100644 --- a/src/ui/top_scorers.cpp +++ b/src/ui/top_scorers.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of TopScorersScreen (top_scorers.hpp): list and podium drawing, footer button handling including drag-off cancel, and request construction. #include "formats/executable_layout.hpp" #include "ui/top_scorers.hpp" diff --git a/src/ui/top_scorers.hpp b/src/ui/top_scorers.hpp index 2439cc7..4a2526e 100644 --- a/src/ui/top_scorers.hpp +++ b/src/ui/top_scorers.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Top scorers Desk screen: renders a TopScorersState (goals, assists or scorer metric; league or managers +// scope) with podium art and footer buttons. Owns only the pressed-button and rejection state. Button clicks +// become a pending TopScorersRequest with identity guards (see top_scorers_state.hpp) that the session +// acknowledges with a new state or rejects. Implemented in top_scorers.cpp. #pragma once #include diff --git a/src/ui/top_scorers_state.cpp b/src/ui/top_scorers_state.cpp index 7352923..2fd8fe9 100644 --- a/src/ui/top_scorers_state.cpp +++ b/src/ui/top_scorers_state.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the helpers declared in top_scorers_state.hpp, building the top scorers state from the GameState. #include "ui/top_scorers_state.hpp" #include diff --git a/src/ui/top_scorers_state.hpp b/src/ui/top_scorers_state.hpp index 045de2a..56e5003 100644 --- a/src/ui/top_scorers_state.hpp +++ b/src/ui/top_scorers_state.hpp @@ -1,4 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-only +// Data model for the top scorers screen: metric, scope and action enums, the identity guard binding every +// result to the active Desk owner, the request, and TopScorersState holding the game-side projection and a +// captured underlay frame. Paired with top_scorers.hpp (renderer) and top_scorers_state.cpp. #pragma once #include diff --git a/src/ui/top_scorers_tests.cpp b/src/ui/top_scorers_tests.cpp index b19d837..fa05db9 100644 --- a/src/ui/top_scorers_tests.cpp +++ b/src/ui/top_scorers_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for TopScorersScreen: rejection keeps the shown projection and dragging off a footer button cancels its pressed state. #include "ui/top_scorers.hpp" #include diff --git a/src/ui/toto.cpp b/src/ui/toto.cpp index 1fd266f..8f085ca 100644 --- a/src/ui/toto.cpp +++ b/src/ui/toto.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of TotoScreen and toto_from_game() (toto.hpp): match rows with ratings, stake handling, pick cycling and the JSON helpers for state and request. #include "formats/executable_layout.hpp" #include "ui/toto.hpp" diff --git a/src/ui/toto.hpp b/src/ui/toto.hpp index 3bea3be..cc1ea0c 100644 --- a/src/ui/toto.hpp +++ b/src/ui/toto.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Toto (football pools) screen: eleven matches with home/away picks, stake entry and the previous week tips +// and winnings. TotoState is projected from the GameState by toto_from_game(). Submitting produces a +// TotoRequest with the tips and stake plus revision guards; the session answers via acknowledge() or +// reject_action(). Implemented in toto.cpp. #pragma once #include diff --git a/src/ui/training.cpp b/src/ui/training.cpp index bec39d4..8ad0d46 100644 --- a/src/ui/training.cpp +++ b/src/ui/training.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of TrainingScreen and the training projections (training.hpp): initialization state, skill bars under the pointer, request construction and JSON output. #include "formats/executable_layout.hpp" #include "ui/training.hpp" diff --git a/src/ui/training.hpp b/src/ui/training.hpp index b2aeaf6..1a9bbbb 100644 --- a/src/ui/training.hpp +++ b/src/ui/training.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Training screen: team training types per position group, focus areas, per-player intensity and focus, and the +// automation flag. TrainingState is an owned projection of the squad and the manager training bytes (from a +// save or the live game). Every edit becomes a TrainingRequest with revision guards, and further input is +// blocked until the session calls acknowledge() or reject_action(). Implemented in training.cpp. #pragma once #include diff --git a/src/ui/training_camp.cpp b/src/ui/training_camp.cpp index 6de8565..b9d2266 100644 --- a/src/ui/training_camp.cpp +++ b/src/ui/training_camp.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of TrainingCampScreen and training_camp_from_game() (training_camp.hpp): resort rows with hover, price and star display, and booking/focus request construction. #include "formats/executable_layout.hpp" #include "ui/training_camp.hpp" diff --git a/src/ui/training_camp.hpp b/src/ui/training_camp.hpp index 6f7a981..38c55a4 100644 --- a/src/ui/training_camp.hpp +++ b/src/ui/training_camp.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Training camp booking screen: eight resorts with prices and quality values, focus selection and booking. +// TrainingCampState carries balance, currency conversion, stay counter (booked this week flag and visit count, +// limit three) and the last feedback. Focus changes and bookings become TrainingCampRequests with revision +// guards; a pending request blocks input until acknowledge() or reject_action(). Implemented in training_camp.cpp. #pragma once #include diff --git a/src/ui/training_camp_tests.cpp b/src/ui/training_camp_tests.cpp index 27c8b59..83f73a6 100644 --- a/src/ui/training_camp_tests.cpp +++ b/src/ui/training_camp_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for TrainingCampScreen: deterministic rendering, hover restore, duplicate-input blocking while pending, and acknowledged focus updates. #include "formats/executable_layout.hpp" #include "../../tests/test_inputs.hpp" #include "ui/training_camp.hpp" diff --git a/src/ui/training_tests.cpp b/src/ui/training_tests.cpp index da5dd7e..114e81e 100644 --- a/src/ui/training_tests.cpp +++ b/src/ui/training_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for TrainingScreen: squad projection, skill bars, blocking of input while a request is pending, rejection, and right-button return to the desktop. #include "formats/executable_layout.hpp" #include "ui/training.hpp" diff --git a/src/ui/transfer_history.cpp b/src/ui/transfer_history.cpp index 9efb2fc..af966e3 100644 --- a/src/ui/transfer_history.cpp +++ b/src/ui/transfer_history.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of transfer_history_from_game() and TransferHistoryScreen (transfer_history.hpp): row decoding, date formatting and row drawing over the underlay. #include "formats/executable_layout.hpp" #include "ui/transfer_history.hpp" diff --git a/src/ui/transfer_history.hpp b/src/ui/transfer_history.hpp index af1fa44..aa41f74 100644 --- a/src/ui/transfer_history.hpp +++ b/src/ui/transfer_history.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Transfer history page listing a manager saved transfers (sell, buy, lend, borrow) with date, fee and +// counterparty club. transfer_history_from_game() decodes the manager saved rows; TransferHistoryScreen +// overlays them on the accepted statistics page and closes on the original exit event supplied by the page owner. +// Read-only. Implemented in transfer_history.cpp. #pragma once #include diff --git a/src/ui/transfer_history_tests.cpp b/src/ui/transfer_history_tests.cpp index 516b8ed..d7b156e 100644 --- a/src/ui/transfer_history_tests.cpp +++ b/src/ui/transfer_history_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the transfer history projection: buyer rows and the special counterparty label are decoded from the saved bytes. #include "ui/transfer_history.hpp" #include diff --git a/src/ui/transfer_market.cpp b/src/ui/transfer_market.cpp index a57cc73..3ce3f92 100644 --- a/src/ui/transfer_market.cpp +++ b/src/ui/transfer_market.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of TransferMarketScreen and the market projection (transfer_market.hpp): list drawing and sorting, quote preview, view switching and request construction. #include "formats/badge_policy.hpp" #include "formats/executable_layout.hpp" #include "ui/transfer_market.hpp" diff --git a/src/ui/transfer_market.hpp b/src/ui/transfer_market.hpp index f671fd7..f552652 100644 --- a/src/ui/transfer_market.hpp +++ b/src/ui/transfer_market.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// Transfer market screen with three views: market listing, own-squad selling and offer review. TransferMarketState +// is an owned projection (items, squad, previews, club roster) so no GameState pointer is kept. Actions (bid, +// list player, open offer, quote preview, poach, review offers) become TransferMarketRequests that the caller +// applies through the desk actions, then it attaches a new projection or a rejection. Implemented in transfer_market.cpp. #pragma once #include diff --git a/src/ui/transfer_market_tests.cpp b/src/ui/transfer_market_tests.cpp index f40af27..79f050b 100644 --- a/src/ui/transfer_market_tests.cpp +++ b/src/ui/transfer_market_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for TransferMarketScreen: projection of native inputs, quote and bid requests, owner preview, feedback text and listing order. #include "formats/executable_layout.hpp" #include "ui/transfer_market.hpp" diff --git a/src/ui/world_cup_statistics.cpp b/src/ui/world_cup_statistics.cpp index 7c92029..6a16324 100644 --- a/src/ui/world_cup_statistics.cpp +++ b/src/ui/world_cup_statistics.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Implementation of the World Cup statistics projection, medal ordering, hit-testing and WorldCupStatisticsScreen (world_cup_statistics.hpp). #include "formats/executable_layout.hpp" #include "world_cup_statistics.hpp" diff --git a/src/ui/world_cup_statistics.hpp b/src/ui/world_cup_statistics.hpp index 2f9b2e6..9bcdbb0 100644 --- a/src/ui/world_cup_statistics.hpp +++ b/src/ui/world_cup_statistics.hpp @@ -1,4 +1,8 @@ // SPDX-License-Identifier: GPL-3.0-only +// World Cup statistics page: 18 editions of four placements, a medal ranking of 62 nations and a flag map. +// It is read-only from the Desk; only the Friendly Match nation picker owner enables selecting an opponent, +// which yields a select_opponent request for that caller. WorldCupStatisticsProjection is built by +// world_cup_statistics_from_game(). Implemented in world_cup_statistics.cpp. #pragma once #include diff --git a/src/ui/world_cup_statistics_tests.cpp b/src/ui/world_cup_statistics_tests.cpp index 628ffa9..de6770a 100644 --- a/src/ui/world_cup_statistics_tests.cpp +++ b/src/ui/world_cup_statistics_tests.cpp @@ -1,4 +1,5 @@ // SPDX-License-Identifier: GPL-3.0-only +// Tests for the World Cup statistics helpers: medal key and nation ordering and the selection request. #include "world_cup_statistics.hpp" #include