Add header comments to the source files
Every source file in ui, app, game, formats, cli, audio and launch that had none now starts with a short English comment: what it implements, what state it owns and how it relates to its neighbours (request/acknowledge flow, pairs of files, random generator use). Comment lines only; the full build and the runnable tests are unchanged. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
aa6ec96305
commit
287b5a9251
324 files changed
+1186
No files matched your search
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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 <chrono>
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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 <SDL.h>
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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 <SDL.h>
|
||||
|
||||
@@ -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 <SDL.h>
|
||||
|
||||
@@ -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 <SDL.h>
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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 <cstddef>
|
||||
namespace bmh::app {
|
||||
|
||||
@@ -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 <SDL.h>
|
||||
#include <stdexcept>
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
|
||||
Reference in new issue
Block a user