Complete Classic BMH and FLTD installation imports (by Codex)
This commit is contained in:
1 parent
65b087c1d0
commit
3a021fc160
32 files changed
+2297
-203
No files matched your search
@@ -0,0 +1,185 @@
|
||||
# Classic installation content contract, version 1
|
||||
|
||||
This contract completes the installation import for the two supported Classic
|
||||
mods without making the 0.1 engine consume OBW. It is an additive OBW 1.0
|
||||
extension, guarded by **`requires: ["runtime:classic-v1"]`**. Readers which do not
|
||||
implement it must reject it. The mod IDs are `BMH-classic` and `FLTD-classic`.
|
||||
|
||||
The contract is a bridge for the 0.2 adapter. Core JSON gives stable identities
|
||||
and useful typed projections; `x-classic` retains every remaining content byte
|
||||
and binds initialization semantics to a version. It does not make a legacy cup
|
||||
table into the generic competition engine planned for 0.4. Neither a DOS
|
||||
executable nor an installed game is needed to reconstruct the imported content.
|
||||
|
||||
## Content and precedence
|
||||
|
||||
| Path | Contract |
|
||||
|---|---|
|
||||
| `manifest.json` | Profile `classic-installation-v1`, canonical mod ID, content ownership, season reference and required runtime |
|
||||
| `world/*.json` | Core entities, source squad identities, initialization policies, league/cup projections and rule/calendar projections |
|
||||
| `x-legacy/source-database.json` | Exact master database as hex, with `legacy-source@1.0`; preserves spare slots and packed fields |
|
||||
| `x-legacy/database.json` | Named auxiliary tables and name pools |
|
||||
| `x-legacy/texts.json` | Original text indices, decoded strings and raw bytes |
|
||||
| `x-classic/startup.json` | `classic-startup@1.0`, edition, layout version, initializers, inputs and resource references |
|
||||
| `x-classic/{source,effective}/*.bin` | Original and supported-profile DATA regions, never program code |
|
||||
| `x-classic/{desktop,formation}-seed.bin` | The 864-byte desktop and 1,408-byte formation input records |
|
||||
| `x-classic/text-blob.bin` | Exact text block after its seven-byte source header, including following bytes used by bounded legacy text reads; startup metadata preserves the header |
|
||||
| `assets/classic/resources.json` | Image dimensions/indices/PNG paths, bitmap-font metrics, audio-container chunks and optional artwork |
|
||||
| `assets/classic/palette.json` | All 256 ARGB colors, using the existing verified VGA-DAC expansion |
|
||||
| `assets/index.json` | Logical keys, paths, kind, source and rights metadata |
|
||||
| `assets/portrait-sets/bmh-classic@1/set.json` | Four backgrounds, five ordered layers, individual part keys and placement |
|
||||
| `x-classic/inventory.json` | Every other entry's path, byte count and CRC32 |
|
||||
|
||||
`content_complete: true` means that all content needed by this particular runtime
|
||||
is present. It does not identify a running game, an OBW-capable released client,
|
||||
or a completely generic typed simulation. The adapter must preserve legacy
|
||||
fields it does not otherwise use. Names/appearance/assets in the core projection
|
||||
are the presentation values; original byte names and offsets remain available
|
||||
for Classic initialization and compatibility. An adapter which supports editing
|
||||
ratings, membership or competitions must explicitly apply those changes to its
|
||||
initialization model; blindly replaying the preserved database would ignore them.
|
||||
|
||||
## Data regions
|
||||
|
||||
`openbmh-classic-layout@1` fixes the address layout already documented in
|
||||
`src/formats/executable_layout.hpp` at the introduction of this contract:
|
||||
|
||||
- Common German-layout data: `[0xA0000, 0xC1000)`.
|
||||
- Football Limited only, native English data: `[0x6B000, 0x776A8)`.
|
||||
|
||||
Only these allowlisted regions and four bounded text literals can be reconstructed.
|
||||
The literals are the free-kick, penalty, corner and automatic-taker labels at
|
||||
`0x80CC9`, `0x80CD2`, `0x80CDB`, `0x80CE3`, with bounds 9/9/8/5 bytes including
|
||||
the terminator. They share a German LE code object, so they are extracted as
|
||||
individual strings, never as the containing object. English normalized images
|
||||
retain their existing values (empty where untranslated). All other locations of
|
||||
the compatibility image are zero. DOS headers, program instructions and relocation
|
||||
instructions are excluded. Pointer-valued data remain numbers; they are never executed.
|
||||
|
||||
`effective` is the existing loader's output with `openbmh-supported@1` rules.
|
||||
`source` is the same loaded/translated data before applying that rule profile.
|
||||
English translation still maps the edition's content into the common layout and
|
||||
also retains its native data region. The two copies prevent shared rule
|
||||
normalization from destroying source values. The current supported rule profile
|
||||
is the default for both Classic mods; selecting unpatched rules requires a
|
||||
separately versioned runtime/profile, not a silent behavioral change.
|
||||
|
||||
Raw regions include all content read through the current executable-data API:
|
||||
cup/qualification tables, ladder, prices, training and credit data, stadium
|
||||
configuration, player-generation settings, match parameters, embedded strings,
|
||||
interface atlases/coordinates and audio tables. Some of these remain byte-based
|
||||
compatibility fields rather than final generic rule objects. They are fully
|
||||
preserved, not left to a future re-import from the executable.
|
||||
|
||||
## New-game initialization
|
||||
|
||||
The importer does **not** choose a manager, start a career, simulate a season,
|
||||
consume either game RNG or import an FBM. The adapter receives two seeds, manager
|
||||
choices, level, mode and competition options when starting a new game. It applies
|
||||
these operations in order, retaining the existing engine's arithmetic, packed
|
||||
field behavior and draw sequence:
|
||||
|
||||
| Initializer | Existing semantic operation |
|
||||
|---|---|
|
||||
| `classic-load-seeds@1` | `startup_state`: database/pools, saved static blocks, desktop/formation input, competition pointers and nationality transforms |
|
||||
| `classic-player-ratings@1` | `startup_players`, with edition league structure and original extra-player slots |
|
||||
| `classic-pending-offers@1` | Clear the four pending-offer words to their empty sentinel, as `new_career_before_dialog` |
|
||||
| `classic-markets-and-moods@1` | `new_career_markets_and_moods`: funds/shares, provisional computer-manager names, market history and club moods |
|
||||
| `classic-free-agents@1` | `new_career_players`: ages/skills and release of extra players |
|
||||
| `classic-setup-options@1` | Apply level, mode, duration, manager count, competition/calendar masks, then `career_managers_begin` |
|
||||
| `classic-confirm-managers@1` | `career_add_manager`: name/portrait, identity swaps, ratings, financial/contractual, lineup, stadium and sponsor initialization; then `career_managers_end` |
|
||||
| `classic-season-setup@1` | `career_season_setup` and `career_first_steps`: entrants, international cycle, calendar, tickets, club accounts, player season and shuffled draw positions |
|
||||
|
||||
Extra runtime configuration mirrors `CareerSession`: currency suffix, training-camp
|
||||
data, credit tables/divisor, edition scheduling, message strings and runtime
|
||||
options all come from the imported content/current versioned Classic algorithm.
|
||||
|
||||
The adapter maps `manifest.start_date` to its calendar's season origin. The
|
||||
current 0.1 engine uses a 2026 date label internally; the importer does not change
|
||||
that engine. The installation equivalence test uses the same 2026 origin and
|
||||
identical options/seeds on both paths. Other requested start years are retained
|
||||
as world input for the 0.2 calendar adapter.
|
||||
|
||||
`classic-manager-finance@1`, `classic-player-contract@1` and
|
||||
`classic-stadium@1` are **initialization policies**, not existing contracts,
|
||||
balances or owned stadiums. Finance policies cover 138 league clubs; actual
|
||||
human-manager accounts are created when a manager is assigned. Contract seeds
|
||||
bind every assigned player to the source team with the packed source values.
|
||||
Referees are staff entities; managers and other generated staff get identities
|
||||
when a new game creates them. Stadium entities form the complete name pool.
|
||||
No invented birth date, contract term or zero-capacity stadium fills a gap.
|
||||
|
||||
## Competition and calendar projections
|
||||
|
||||
All nine leagues use the edition's sizes, members and fixture draw-position
|
||||
tables. German regional third divisions remain parallel. The English ten-club
|
||||
fifth tier remains unplayed, with no invented fixture generator.
|
||||
|
||||
All 36 source cup entries remain in the data regions. Entries with a valid
|
||||
competition ID 0–26 are also represented as stages grouped by competition ID;
|
||||
sentinel entries remain data only. Their Classic fields record source entry,
|
||||
flags, next/parallel links, round counts, qualification quota and group number.
|
||||
Slots with `resolver: classic-entry@1` are dynamic fields populated by
|
||||
`classic-season-entrants@1`, not explicit team lists. `teams` records the source
|
||||
stage size and can be zero before initialization. The resolver must implement
|
||||
the current edition's selection and qualification algorithm, including FA Cup
|
||||
qualifying/proper rounds and League Cup for English data, or indoor/Masters for
|
||||
German data. The generic `format` field alone is insufficient to execute a stage.
|
||||
|
||||
`classic-calendar@1` retains the complete source day table and bindings.
|
||||
`classic-season-calendar@1` applies options, season cycle, weekday alignment and
|
||||
leap-year behavior using the Classic calendar algorithm at runtime. Cup series
|
||||
bind calendar bit `competition_id + 5`; league series retain the edition's
|
||||
calendar-group binding. Dated fixtures cannot be exported before manager/options
|
||||
selection without changing the original start semantics.
|
||||
|
||||
## Artwork, portraits, fonts and audio
|
||||
|
||||
Every imported image has an indexed PNG for standard consumers plus a `.pixels`
|
||||
payload for the Classic adapter's exact palette-index operations. Dimensions and
|
||||
palette are explicit. The source VGA files themselves are not required. Crest
|
||||
keys bind stable club identities; the original generic crest is used where the
|
||||
Classic interface deliberately uses a fallback. Kit selectors and the complete
|
||||
relevant sprite sheets remain available.
|
||||
|
||||
`appearance` contains the source-name-derived result, computed with the same
|
||||
signed-byte/unsigned-seed arithmetic as `PlayerCardScreen::draw_portrait`, including
|
||||
its discarded initial draw. It never consumes the game's RNG streams. A rename
|
||||
changes the name, not the recipe. The set stores each part separately, preserving
|
||||
linear source-stride wrap at row edges, transparent index zero, layer order and
|
||||
offsets relative to the 38×38 background. It never stores composed faces.
|
||||
|
||||
Bitmap fonts store glyph locations, widths, advances, original alphabet bounds,
|
||||
baseline and exact bitmap bytes. The zero-width replacement glyph may point
|
||||
beyond the bitmap because it is never dereferenced. These fonts use the Classic
|
||||
byte encoding; new modern interface fonts remain a separate theme concern.
|
||||
|
||||
The four original ALPTRAUM audio containers are local binary assets with chunk
|
||||
metadata, consumed by the already implemented audio decoder. Music keeps its
|
||||
instrument/sequence data rather than being destructively flattened to a recording.
|
||||
Source frequency/operator tables remain in the Classic data regions. Optional
|
||||
FLI/FLC and editor artwork is retained as identified local artwork, without
|
||||
importing editor programs, user settings or saves.
|
||||
|
||||
## Reader, writer and checks
|
||||
|
||||
`bmh::obw::read` accepts ZIP/directory content and validates it. `load_classic`
|
||||
returns the read-only input model (`Database`, data-only `LeImage`, full `TextDb`,
|
||||
desktop/formation seeds, indexed images, palette, fonts and audio) independently
|
||||
of either game frontend. It does not create `GameState` or `CareerSession`.
|
||||
|
||||
Binary payloads are byte strings, not UTF-8 JSON strings. Paths are authored
|
||||
relative forward-slash paths. The reader rejects traversal, duplicate entries,
|
||||
symlinks in a directory, excessive sizes and unknown required profiles. The
|
||||
validator checks cross-references, complete stage/contract bindings, resource
|
||||
shapes, portrait indices and inventory. CRC32 detects accidental damage, not
|
||||
malicious modification. An editor deliberately changing a world must update its
|
||||
inventory (`refresh_classic_inventory`) and validate it before writing.
|
||||
|
||||
The installation test reconstructs from an OBW ZIP, then compares a complete
|
||||
first-season initialization in RAM against the existing legacy-load path:
|
||||
native state bytes and both RNG seeds/counts. It also compares every exported
|
||||
data-region byte and original atlas pixels, palette, fonts and audio. This proves
|
||||
content/startup preservation for the supplied installation and chosen test start;
|
||||
it does not claim an implemented 0.2 adapter, native-platform testing, a fully
|
||||
played season or savegame conversion.
|
||||
Reference in new issue
Block a user