12 KiB
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.