Files
Dreierpack-Manager/docs/ENGINE_SPLIT.md
T

17 KiB
Raw Permalink Blame History

Engine split: Classic, Classic Extended and Modern

Status: concept and migration plan. It prepares one shared match engine under the season engines of three game variants. Nothing in this document changes the behaviour of the current release.

1. Goal

OpenBMH will offer three game variants:

Variant Data Season engine Interface State
Classic Imported from the user's BMH or FLTD installation (OBW runtime:classic-v1) Classic: fixed calendar, 9 leagues, original competition structure and rules Classic 320×200 bitmap interface Essentially complete
Classic Extended Classic data, optionally extended where the classic screens can show it Working idea: Classic engine plus features backported from Modern, step by step (§4) Classic bitmap interface, extended by hand per feature Open; after Modern
Modern New OBW data set (imported and extended, or own worlds) Modern: generated calendar, data-driven leagues and competitions, playable foreign leagues, leagues larger than 12 teams New high-resolution interface (RmlUi), designed for many leagues Interface in progress

All three use the same match engine. A match between two given teams under the same rules is simulated by the same code in every variant; only what happens around it (calendar, competitions, finances, transfers, development) differs.

1.1 Where a change belongs

  • Classic receives changes that work with the imported original assets and the original data layout: bug fixes, quality of life, small rule corrections, menus such as the environment menu of a later DIAMOND release.
  • Modern is where new features are designed first, without the limits of the original screens or data layout: more leagues, foreign leagues with more than 12 teams, a free calendar, new competitions and systems.
  • Classic Extended takes Modern features back into the Classic engine one at a time, where the bitmap interface can present them with reasonable manual work. The classic screens were never designed for variable structures, so Classic Extended will never offer every Modern feature; each backport is a decision of its own (§4).

2. Target architecture

      Classic UI (bitmap)         Classic UI + extra screens        Modern UI (RmlUi)
              |                              |                              |
              +---------------- app / protocol layer (capabilities) -------+
              |                              |                              |
      season: classic          season: classic + backported features   season: modern
      (GameState image)        (GameState image + extension state)    (typed OBW model)
              |                              |   \                    /     |
              |                              |    shared feature modules    |
              |                              |    (bmh_features, ports)     |
              +------------------ match adapter (per engine) --------------+
                                             |
                              match engine (bmh_match: typed contract)
                                             |
                              random sources, attribute set bmh-classic@1

2.1 Libraries

Target Contents May depend on
bmh_match Minute simulation, events, chances, cards, injuries during the match, substitutions, live interventions, the Reality scene and reporter random, the match contract types; not GameState, calendar, finances
bmh_season_classic Today's src/game without the match core: turn driver, weekly/monthly/season processing, cups, transfers, finances, post-match effects bmh_match, bmhcore formats
bmh_season_classic_ext Classic Extended: registry of backported features, their state and hook points in the Classic turn (§4) bmh_season_classic, bmh_features
bmh_features Season features written once for Modern and reusable by Classic Extended, each against small ports (interfaces) instead of a concrete state model the match contract types only
bmh_season_modern New season engine on the typed OBW model (§5) bmh_match, bmh_features, bmh_world
bmh_world Typed OBW model, reader/writer, validator (src/content, src/import) bmhcore formats

The dependency rules: the match engine knows no season engine; no season engine reaches into the state of another; no season engine knows an interface; a feature in bmh_features knows neither GameState nor the OBW model, only its ports.

2.2 Writing Modern features so they can be backported

Backporting is cheap only if a feature is written for it from the start:

  • The rules of a feature (for example youth development, a staff system, sponsor negotiation) live in bmh_features and read and write the game only through a port: PlayerRoster, ClubFinance, Calendar, Mailbox, RandomSources and similar narrow interfaces.
  • Modern implements the ports on the typed model. Classic Extended implements the same ports as adapters on GameState plus its extension state.
  • A feature declares what it needs (ports, data fields, calendar events) and which presentation it needs (screens, messages). This declaration is the checklist for a backport: if the Classic adapter cannot provide a port, or no classic screen can show the result, the feature stays Modern-only.
  • Features that depend on Modern-only structures (generated calendar, generic competition stages, leagues of variable size) are marked as such and are not candidates.

3. The match contract

Today the match core reads and writes the memory image directly: MatchGroup holds raw descriptors, and matchday.cpp mixes the minute loop with season effects (finish_match, update_club_table, update_morale, develop_players, book_money, injure_player, rate_manager). The split replaces this with typed input and output.

3.1 Input: MatchdaySetup

The contract works per matchday batch, not per single match: the original walks all match groups and all matches every minute, so the random numbers of different matches are interleaved. A batch keeps that order exactly for Classic; Modern may pass a batch of one.

MatchdaySetup
  rules         per group: competition kind (league, cup, friendly, indoor),
                half length (45 / 20), stoppage, extra time, penalties,
                away-goals and away-penalty flags, leg and first-leg score
  groups[]      matches[]: home TeamSheet, away TeamSheet, venue, spectators
  random        RandomSources (see 3.3)
  live          optional LiveControl (see 3.4)

TeamSheet
  team id, side, players on the pitch and bench (player id, position, slot,
  attributes of set bmh-classic@1, condition, form, morale, cards already held),
  formation, tactic items, attitude, captain, penalty and free-kick takers,
  automation flags (computer-controlled tactics)

Everything a match needs is copied into the setup. The engine does not look anything up.

3.2 Output: MatchdayResult

per match: final score per phase (regular, extra time, penalties), end minute,
           event list (minute, kind, team, players: goal, assist, chance,
           card, injury with severity, substitution, tactical change),
           player ratings and statistics, side records (typed form of the
           18 legacy record bytes), live-intervention log

The engine reports facts. Consequences belong to the season engine: league tables, money, morale, player development, suspensions counted per competition, injury duration in days, manager ratings, mail and press. Classic applies them exactly as today; Modern applies its own rules to the same facts.

3.3 Random numbers

The match engine draws only through an injected RandomSources interface with the two streams the original uses (WatcomRandom, GameRandom, see docs/RNG.md).

  • Classic passes the session's global streams, so consumption order and regression results stay identical.
  • Modern passes streams seeded per matchday (or per match) from the world seed, so a match can be replayed on its own.

3.4 Live matches

LiveControl is the only channel for human influence during a match: pause points (half time, events that request a lineup), substitutions, tactic and attitude changes, and the minute clock barrier of multi-client sessions. The Reality scene (reality_*) is a presentation of the same simulation and moves with the match engine. Interfaces receive match progress as events; none of them calls into the minute loop directly.

3.5 Attribute set

The match engine consumes players in attribute set bmh-classic@1 (OBW §5.3). Classic already stores exactly this. Modern may keep richer attributes for its own systems, but provides a bmh-classic@1 projection for every player it sends into a match. A later, finer match model would be a new version of the match engine with its own attribute set, selectable per variant; it is not part of this plan.

3.6 Versioning

bmh_match carries a contract version (match@1). Saves record the version they were played with. A behavioural change to the match engine is a new version, noted in docs/DIFFERENCES.md, and is checked against all three variants before it lands.

4. Classic Extended

Working idea, not a decision. Backporting Modern features into the Classic engine is the current idea for Classic Extended; the variant may take a different shape. What does not depend on it: the shared match engine (§3), the Modern engine driven only through the protocol, and features written against ports (§2.2), which keep several options open.

Classic Extended is the Classic season engine plus backported Modern features, presented in the classic bitmap interface.

  • Invariant: with every backported feature switched off, Classic Extended produces exactly the Classic results. A test runs the Classic regression through the Extended engine with no features.
  • Each backported feature is a module with an id and version, its own state (x-extended/ in OBW saves), the Classic adapters for its ports and its classic-style screens. A career records which features it uses; features can be switched on at career start and, where safe, later.
  • Features hook into defined points of the Classic turn (start/end of day, week, month and season; before/after a matchday; desk actions), never into the middle of a Classic routine.
  • Data: Classic Extended starts from Classic data. A feature may bring additional data, but only in a shape the classic screens can show. Structures that change the size of what the screens list (more or larger leagues, new competitions) are Modern-only unless a specific screen is redesigned for them.
  • Interface cost per feature, the main factor in each backport decision:
    1. The result fits existing screens (a new value on the player card, a message, a desk action): small.
    2. A new screen of fixed size in the classic style (a staff or youth screen): medium, new own artwork needed.
    3. A screen whose content grows with the data (longer tables, more league selectors, calendar views): large, often not worth it.
  • Assets: the original bitmaps of the user's installation plus new classic-style artwork. New artwork must be the project's own.
  • Order of work: a feature is built and settled in Modern first, then backported if its ports and its presentation fit (§2.2).

5. Modern

Modern is a new season engine on the typed OBW model (docs/formats/OBW.md):

  • Data set: an OBW world that goes beyond the original structure, for example foreign leagues with more than 12 teams, more leagues (up to 32) and real-world competition formats. It can start from an imported Classic world and be extended, or be a world of its own.
  • Calendar: generated each season from world/calendar.json (series, windows, events) instead of a fixed day table; any season start, international windows, winter breaks per nation.
  • Competitions: the generic stage model (league, groups, league phase, knockout, playoff, final) with declarative slots and promotion/relegation; foreign leagues are playable, not only simulated.
  • Systems: finances, transfers, contracts, youth, staff and development are rewritten on the typed model, reusing Classic formulas where they fit and documenting where they differ.
  • Interface: the RmlUi client through the app/protocol layer only.
  • Matches always go through the shared match contract (§3).

Modern does not have to reproduce Classic results; its quality gate is plausibility (seasons simulated in bulk, agentic QA, fan expectations), not bit equality.

6. Variant selection and saves

  • The world or save manifest names the runtime: requires: ["runtime:classic-v1"], ["runtime:classic-extended-v1"] (with the list of active features and their versions) or ["runtime:modern-v1"], plus match@1.
  • CareerSession selects the season engine from the manifest; the protocol reports capabilities per engine and feature, so interfaces and console clients only offer supported actions.
  • Conversions are one-way: Classic → Classic Extended (switch features on), Classic or Classic Extended → Modern (convert to the typed model; backported feature state maps to the Modern original of the feature). There is no way back, and the original file is kept.
  • All variants save only in the OBW format (.obs). Legacy .FBM saves are an import source only: they are converted into a Classic .obs career and never written.

7. Migration plan

Each step keeps the game playable and the Classic regression (tools/regression/checkonly.sh, season simulations, long runs) unchanged.

Step Content Gate
0 Freeze the Classic baseline: tag, record regression outputs and long-run statistics as reference Reference recorded
1 Move the match core (match_engine, match, reality_*, reporter) into src/match and target bmh_match; no behaviour change Regression identical
2 Introduce RandomSources; the match core no longer touches the global streams directly Regression identical
3 Typed MatchdaySetup/MatchdayResult; Classic adapter builds the setup from MatchGroup/GameState and writes results back; move post-match effects out of the minute loop into bmh_season_classic Regression identical; match contract tests
4 Remove the remaining GameState dependencies from bmh_match (enforced by the build: bmh_match does not link GameState) Build rule; regression identical
5 Runtime field in manifests, engine selection in CareerSession, capability reporting in the protocol Classic unchanged; capability tests
6 bmh_features with the first ports; Modern season engine on bmh_world, first with one nation and the shared match engine, then the competition model, then foreign leagues and larger leagues Modern plausibility runs
7 Classic Extended skeleton: feature registry, hook points, x-extended state, Classic adapters for the first ports, "no features = Classic" test Regression identical through Extended
8 Backports one feature at a time, each with its interface cost assessed (§4) Per feature: Classic regression with the feature off, plausibility with it on
9 Classic → Modern conversion of worlds and careers Converted careers playable

Steps 1 to 4 are the actual split and the risky part; they are pure refactoring and must be done in small commits with the regression after each. Classic improvements continue in parallel on bmh_season_classic.

8. Tests

  • Match contract tests: a fixed MatchdaySetup with fixed seeds yields a fixed MatchdayResult (golden files with synthetic teams, public).
  • Classic regression: unchanged scripts and expected outputs; run after every step.
  • Extended identity: the Classic regression through the Extended engine with no features.
  • Feature tests: each module in bmh_features is tested once against fake ports, then through both adapters (Modern and Classic Extended).
  • Modern plausibility: bulk season simulations with goal, points and money distributions compared to Classic as a reference band.
  • Dependency checks: the build fails if bmh_match includes season or GameState headers, if bmh_features includes GameState or OBW model headers, or if a season engine includes interface headers.

9. Open decisions

  • Which features become the first backport candidates (proposal: features of interface cost 1 or 2 that do not change league structure).
  • Whether Modern keeps bmh-classic@1 as its only player attribute set at first (proposal: yes, richer attributes later as a new match engine version).
  • Ownership: the split and Classic (engine/integration), the Modern interface (UI), Modern features and their backports (shared, per feature).