164 lines
12 KiB
Markdown
164 lines
12 KiB
Markdown
# Engine split: Classic, Classic Extended and Modern
|
||
|
||
Status: **concept and migration plan**. It prepares one shared match engine under three season engines. 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`) | The current engine: fixed calendar, 9 leagues, original competition structure and rules | Classic 320×200 interface | Essentially complete |
|
||
| **Classic Extended** | Classic data plus extension data | Classic engine with optional, switchable extensions | Classic interface plus additional screens in the same style | Not started |
|
||
| **Modern** | Typed OBW worlds (imported or own) | New engine: generated calendar, data-driven leagues and competitions, playable foreign leagues | New high-resolution interface (RmlUi) | 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.
|
||
|
||
## 2. Target architecture
|
||
|
||
```
|
||
Classic UI Classic Extended UI Modern UI (RmlUi)
|
||
\ | /
|
||
+-------- app / protocol layer -------+ variant capabilities
|
||
/ | \
|
||
season: classic season: classic + extensions season: modern
|
||
(GameState image) (GameState image + ext state) (typed OBW model)
|
||
\ | /
|
||
+------ 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` | Extension modules on top of Classic (§4) | `bmh_season_classic` |
|
||
| `bmh_season_modern` | New season engine on the typed OBW model (§5) | `bmh_match`, `bmh_world` |
|
||
| `bmh_world` | Typed OBW model, reader/writer, validator, importers (`src/import`) | `bmhcore` formats |
|
||
|
||
The dependency rule: **the match engine knows no season engine**, and no season engine reaches into another one's state.
|
||
|
||
## 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 and Classic Extended already store 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
|
||
|
||
Classic Extended is **Classic plus switchable extensions**:
|
||
|
||
- It runs on the Classic season engine and the Classic save layout, plus one additional state block for extensions (`x-extended/` in OBW saves).
|
||
- Each extension is a module with an id, a version, its own state, its rules and its screens. A career records which extensions it uses.
|
||
- **Invariant:** with every extension switched off, Classic Extended produces exactly the Classic results. A test runs the Classic regression through the Extended engine with no extensions.
|
||
- Extensions hook into defined points of the Classic turn (start/end of day, week, month, season; before/after matchday; desk actions), never into the middle of a Classic routine.
|
||
- Its screens use the classic interface toolkit (`src/ui`), in the same resolution and style.
|
||
- Candidates for first extensions: the environment ("Umfeld") menu of a later DIAMOND release (reviewed against our rule base, documented as a deviation), more statistics and history screens, quality-of-life automation, configurable rule values (roadmap 0.3).
|
||
|
||
## 5. Modern
|
||
|
||
Modern is a new season engine on the typed OBW model (`docs/formats/OBW.md`):
|
||
|
||
- **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; up to 32 leagues; 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, documented 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"]` or `["runtime:modern-v1"]`, plus `match@1`.
|
||
- `CareerSession` selects the season engine from the manifest; the protocol reports **capabilities** per variant, so interfaces and console clients only offer supported actions.
|
||
- Conversions are **one-way**: Classic → Classic Extended (switch on extensions), Classic or Classic Extended → Modern (convert to the typed model). There is no way back, and the original file is kept.
|
||
- Legacy `.FBM` saves stay Classic.
|
||
|
||
## 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 | Variant field in manifests, engine selection in `CareerSession`, capability reporting in the protocol | Classic unchanged; capability tests |
|
||
| 6 | Classic Extended skeleton: extension registry, hook points, `x-extended` state, "all extensions off = Classic" test | Regression identical through Extended |
|
||
| 7 | Modern season engine on `bmh_world`, first with one nation and the shared match engine, then the competition model, then foreign leagues | Modern plausibility runs |
|
||
| 8 | First Classic Extended extensions; Modern feature growth | Per extension/feature |
|
||
|
||
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.
|
||
|
||
## 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:** Classic regression through the Extended engine with no extensions.
|
||
- **Modern plausibility:** bulk season simulations with goal, points and money distributions compared to Classic as a reference band.
|
||
- **Dependency check:** the build fails if `bmh_match` includes season or `GameState` headers.
|
||
|
||
## 9. Open decisions
|
||
|
||
- Whether Classic Extended may change the save layout for its extensions only in OBW saves or also offer a legacy `.FBM` export (proposal: OBW only).
|
||
- Whether Modern keeps `bmh-classic@1` as its only player attribute set at first (proposal: yes, richer attributes later).
|
||
- Which team owns which variant: Classic and the split (engine/integration), Modern interface (UI), Classic Extended extensions (both, per module).
|