Engine split: Classic Extended backports Modern features into Classic
Classic Extended is the Classic season engine plus Modern features ported back one at a time where the bitmap interface can present them. Modern features are written against small ports in a shared feature library so they can be backported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
9f1928bd9e
commit
c1121da116
2 files changed
+70
-44
No files matched your search
+69
-43
@@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
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
|
||||
|
||||
@@ -8,27 +8,35 @@ 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 |
|
||||
| **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 | Classic engine plus features **backported from Modern**, step by step | Classic bitmap interface, extended by hand per feature | Grows 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 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
|
||||
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
|
||||
@@ -37,11 +45,21 @@ All three use **the same match engine**. A match between two given teams under t
|
||||
|---|---|---|
|
||||
| `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 |
|
||||
| `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 rule: **the match engine knows no season engine**, and no season engine reaches into another one's state.
|
||||
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
|
||||
|
||||
@@ -94,7 +112,7 @@ The match engine draws only through an injected `RandomSources` interface with t
|
||||
|
||||
### 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.
|
||||
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
|
||||
|
||||
@@ -102,22 +120,27 @@ The match engine consumes players in attribute set `bmh-classic@1` (OBW §5.3).
|
||||
|
||||
## 4. Classic Extended
|
||||
|
||||
Classic Extended is **Classic plus switchable extensions**:
|
||||
Classic Extended is the **Classic season engine plus backported Modern features**, presented in the classic bitmap interface.
|
||||
|
||||
- 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).
|
||||
- **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; 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.
|
||||
- **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).
|
||||
|
||||
@@ -125,9 +148,9 @@ Modern does not have to reproduce Classic results; its quality gate is plausibil
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
- Legacy `.FBM` saves stay Classic.
|
||||
|
||||
## 7. Migration plan
|
||||
@@ -141,23 +164,26 @@ Each step keeps the game playable and the Classic regression (`tools/regression/
|
||||
| 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 |
|
||||
| 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.
|
||||
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:** Classic regression through the Extended engine with no extensions.
|
||||
- **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 check:** the build fails if `bmh_match` includes season or `GameState` headers.
|
||||
- **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
|
||||
|
||||
- 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).
|
||||
- Which features become the first backport candidates (proposal: features of interface cost 1 or 2 that do not change league structure).
|
||||
- Whether Classic Extended saves exist only as OBW saves (proposal: yes, no `.FBM` export).
|
||||
- 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).
|
||||
@@ -26,7 +26,7 @@ Some calendar operations need synchronous human decisions. Their presenters own
|
||||
|
||||
## Calendar and matches
|
||||
|
||||
The planned split into one shared match engine and three season engines (Classic, Classic Extended, Modern) is described in [ENGINE_SPLIT](ENGINE_SPLIT.md).
|
||||
The planned split into one shared match engine and the season engines of Classic, Classic Extended (Classic plus backported Modern features) and Modern is described in [ENGINE_SPLIT](ENGINE_SPLIT.md).
|
||||
|
||||
The turn driver moves between manager desks, match clocks and calendar events. Weekly, monthly and seasonal processing can produce decisions as well as simulation results. Match groups contain the day's competitions; a manager can intervene only in a group involving that manager's team. A multi-client match clock advances at a barrier shared by all seats.
|
||||
|
||||
|
||||
Reference in new issue
Block a user