Files
Dreierpack-Manager/docs/formats/obw/classic-v1.md
T

12 KiB
Raw Blame History

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.