Complete Classic BMH and FLTD installation imports (by Codex)

This commit is contained in:
Codex committed 2026-10-18 10:07:38 +02:00
1 parent 65b087c1d0
commit 3a021fc160
32 files changed
+2297 -203

No files matched your search

+7 -7
View File
@@ -1,6 +1,6 @@
# OBW: OpenBMH world, save and pack format (concept, format version 1.0)
Status: **concept with an initial standalone converter** for roadmap 0.2 (open data and typed state), with preparation for 0.4 (scalable interface, content packs). `openbmh_import` implements the guarded `legacy-database-v1` conversion profile described in [import.md](obw/import.md). Its intermediate files cannot yet start a career. The legacy formats remain authoritative for the current engine; an OBW engine adapter and save conversion are not implemented.
Status: **format concept with a complete Classic installation-content converter** for roadmap 0.2, with preparation for 0.4. `openbmh_import` produces `BMH-classic` and `FLTD-classic` worlds under the guarded [`runtime:classic-v1` contract](obw/classic-v1.md), including all startup inputs and media. The [import guide](obw/import.md) distinguishes this from the explicitly partial `legacy-database-v1` development export. The 0.1 engine still reads legacy installations; OBW runtime integration and savegame conversion are separate work.
## 1. Goals and non-goals
@@ -23,7 +23,7 @@ Non-goals of version 1.0:
### 2.1 Container
Every OBW file is a ZIP archive (deflate or stored) containing UTF-8 JSON documents. The project already links miniz (`bmh_miniz`) and has a JSON reader/writer (`src/cli/json.cpp`), so the format needs no new dependency. JSON keeps worlds diffable and editable by hand or by script.
Every OBW file is a ZIP archive (deflate or stored) containing UTF-8 JSON documents and referenced binary assets. The versioned Classic extension additionally permits data-only compatibility regions and startup input records; it does not permit executable code or save state in a world. The project already links miniz (`bmh_miniz`) and has a JSON reader/writer (`src/cli/json.cpp`), so the format needs no new dependency. JSON keeps worlds diffable and editable by hand or by script.
| Extension | `kind` | Contents |
|---|---|---|
@@ -50,7 +50,7 @@ world/calendar.json season calendar, §7
world/rules.json rule values (training camps, interest rates, ...)
state/... save only, §5.9
locale/<lang>/*.po texts, §9.3
assets/... packs and themes only, §9
assets/... local Classic worlds, packs and themes, §9
x-<name>/... extensions, §3.3
```
@@ -112,7 +112,7 @@ Fields and directories whose name starts with `x-` belong to extensions (`x-matc
Each format version is published as JSON Schema (draft 2020-12) under `docs/formats/obw/schema/<major>.<minor>/`, one file per table. The schemas are the machine-readable specification and the basis of the validator (§10).
The initial schemas describe the `legacy-database-v1` intermediate conversion profile only; save, pack, theme and complete playable-world schemas are still planned. This profile uses `requires` to prevent a partial conversion being mistaken for a complete world. Optional fields and unknown extensions remain allowed.
The schemas describe the intermediate `legacy-database-v1` profile and the completed `classic-installation-v1` content profile. The latter requires `runtime:classic-v1`: it contains initialization policies and data-region compatibility fields in addition to typed projections. A generic OBW reader cannot execute those fields without the Classic adapter. Save, pack, theme and fully generic playable-world schemas remain future work. Optional fields and unknown extensions remain allowed.
## 4. Identifiers and names
@@ -186,7 +186,7 @@ Teams without a squad (`foreign`, or `national` in a world that does not simulat
- `set` names a portrait part set; it defines the number of backgrounds, the layers, the number of parts per layer and their placement. `bmh-classic@1` is the set of the original game.
- The importer computes the recipe once from the legacy name and **freezes** it. A later rename (for example by a name pack) keeps the face; the legacy name-derived generator is never re-run.
- Players created in OpenBMH (youth, generated players) receive a random recipe of the world's default set.
- The recipe holds indices only. The part graphics come from the user's installation or from a pack that provides the same set, possibly in higher resolution (§9.2), so a world contains no original artwork.
- The recipe holds indices only. The part graphics come from the user's installation or from a pack that provides the same set, possibly in higher resolution (§9.2), so a recipe does not embed a composed face. A local Classic import may include the original part set as local-only assets; distributable worlds need separately licensed artwork.
An attribute set is declared once in `world/rules.json` with its fields, scales and meaning, so a later, finer model can sit next to the classic one without breaking the format:
@@ -363,7 +363,7 @@ Edition detection is the one the launcher already performs (`src/launch/game_dat
### 8.2 Mapping per edition
The first standalone converter and its coverage are documented in [the edition mapping](obw/import.md). The full intended mapping is:
The standalone converter and its Classic contract are documented in [the edition mapping](obw/import.md) and [Classic v1](obw/classic-v1.md). The core league mapping is:
| Legacy league | German editions | Football Limited | OBW |
|---|---|---|---|
@@ -378,7 +378,7 @@ Cups, European cups, the indoor tournament, the English FA Cup with its qualifyi
### 8.3 Fidelity
The initial `legacy-database-v1` converter preserves database seeds and source tables without starting a career. It does not yet satisfy the engine equivalence criteria below; those require the 0.2 adapter. Its manifest explicitly marks it non-playable, and its import report lists unresolved areas. Unmapped world data lives in `x-legacy/`; `state/x-legacy.json` is reserved for converted saves.
The complete `classic-installation-v1` importer preserves all installation content without starting a career. Typed projections are complemented by the versioned `x-classic` startup contract and data-only regions, including original and effective rules. Installation tests reconstruct from OBW and compare first-season initialization bytes and both RNG streams with the existing loader. They do not establish a released OBW frontend or save continuation. The optional `--database-only` intermediate profile remains explicitly non-playable. `state/x-legacy.json` is reserved for converted saves.
- A new career imported from an installation must produce the same first season in the engine as the legacy start (same fixtures, same participants), verified by the regression runs.
- A converted `.FBM` must continue with the same results as the legacy save for a fixed number of turns.
+185
View File
@@ -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.
+123 -114
View File
@@ -1,143 +1,152 @@
# Legacy installation importer (first version)
# BMH and Football Limited installation converter
`openbmh_import` converts a locally supplied German BMH installation or English
Football Limited installation into an OBW ZIP, or an unpacked OBW directory.
It is a separate tool: neither game frontend nor the engine reads OBW yet.
Integration into the game belongs to version 0.2.
`openbmh_import` imports the content of a supported, locally supplied installation
as **BMH-classic** or **FLTD-classic**. Football Limited's executable is named
`FLTD.EXE`; the spellings `FTDL-classic` and `FTLD-classic` are accepted as CLI
aliases and written as `FLTD-classic`.
The output is an `.obw` ZIP, or an equivalent directory. It contains the complete
**Classic installation content**, including graphics, portrait parts, fonts,
audio and the original data tables. It contains no running career or executable.
The existing 0.1 game does not read OBW. The new 0.2 adapter must implement the
versioned [Classic contract](classic-v1.md); this is deliberately separate from
migrating every engine rule to the future generic model.
## Build and use
Configure the project as described in [BUILDING](../../BUILDING.md), then build
the additional target:
Configure as described in [BUILDING](../../BUILDING.md), then:
```sh
cmake --build build --config Release --target openbmh_import
./build/openbmh_import --data "path/to/game" --output "season.obw" \
--start-date 2026-07-01 --title "My imported season"
./build/openbmh_import --data "path/to/BMH" --output "BMH-classic.obw" \
--start-date 2026-07-01 --mod BMH-classic
./build/openbmh_import --data "path/to/FLTD.EXE" --output "FLTD-classic.obw" \
--start-date 1995-07-01 --mod FLTD-classic
./build/openbmh_import --validate "BMH-classic.obw"
```
With a Visual Studio multi-configuration build, use
`build\Release\openbmh_import.exe`. On Linux and macOS, the executable is in
`build/openbmh_import`. To inspect or edit the JSON directly:
On a Visual Studio multi-configuration build use
`build\Release\openbmh_import.exe`. `--mod` is optional: the tool detects the
edition. A mismatching explicit mod is an error. `--title TEXT` changes the
world's display title. `--directory` writes an unpacked world, which `--validate`
can read too. The source may be an installation directory, its executable, or a
parent with exactly one installation. File discovery ignores case. If both game
executables exist, select the intended executable explicitly.
```sh
./build/openbmh_import --data "path/to/FLTD.EXE" --output "season-directory" \
--start-date 1995-07-01 --directory
```
A full import requires the same installation resources as the current launcher:
master database, text database, executable, `M3.MEN`, `M3.DAT`, palette, required
`KB`/`W` pictures, two fonts and four sound banks. A missing resource is an error.
Supported inputs are the German CD-family editions and Football Limited; the
1994 floppy `M3.EXE`/`M3PC.MAN` family and Amiga installations are not supported.
Source ZIP/7z and `.FBM` files are not input formats for this tool.
`--data` accepts an installation directory, a parent containing exactly one
installation, or its `BMH.EXE`/`FLTD.EXE`. File discovery ignores case. An
installation containing both executables requires naming the executable.
Only the executable, master database and text database are required; absent
graphics, audio or desktop files do not prevent conversion. Source ZIP/7z
archives and individual `.FBM` saves are not input formats for this first tool.
The date must be July 1 of an explicit year (1900–9998). Master data contain
ages without an unambiguous season year; the converter never uses today's date
or invents birth dates. Player age is recorded as `age_at_start`. Calendar setup
remains a Classic runtime operation using the selected season/options.
The reference date is explicit because a master database records ages without
an unambiguous season year. It must be July 1, from 1900 through 9998. The tool
does not use the computer's current date. It refuses existing output paths,
including symlinks. Output is assembled in a sibling staging directory and
published after validation; the output parent must already exist.
Do not run competing writers against the same destination.
Existing destinations, including symlinks, are refused. The parent directory
must exist. The tool stages and validates output before publishing by rename;
source files are read only. Do not run competing writers for one destination.
Runtime packages for 0.1 retain their existing products. The source build has
the extra importer; `cmake --install build --component ImportTools` installs it
separately. Installing it does not enable OBW in the game.
## What a Classic world contains
## Conversion profile and coverage
The manifest names `mod: BMH-classic` or `FLTD-classic`, profile
`classic-installation-v1`, `requires: ["runtime:classic-v1"]` and
`content_license: local-import-only`. `content_complete: true` means all inputs
for that **specific Classic runtime** are present. It does not claim that the
0.1 client can load OBW or that every rule has already been migrated to a generic
0.2/0.4 schema. A reader without `runtime:classic-v1` must refuse the world.
The manifest declares format `1.0`, `kind: world`, provenance `import:bmh-de`
or `import:fltd`, and `content_license: local-import-only`. Crucially,
`requires: ["import:legacy-database-v1"]` and `x-import.playable: false`
identify an **intermediate conversion**, not a fully initialized playable world.
A reader which does not support this profile must refuse it. Future conversion
passes can complete its mappings without needing to reopen the original database.
Every core table uses the `schema`/`items` envelope, including `rules` and
`calendar`. The schemas under [schema/1.0](schema/1.0) describe this first
conversion profile; complete save/pack/theme schemas and engine playability
validation remain future work.
| Source | Exported data |
| Area | Contents |
|---|---|
| `M3D.MAN` / `M3E.MAN` | Named clubs, national teams, nations, all 2,574 players, master squad assignments, stadium name pool |
| Player words and bonus bytes | Position, age, nationality including the high bonus bit, form/technique/condition, seven skills, bonus and derived display strength |
| Executable, through existing loaders | Nine league sizes/tiers/participants, original fixture pairings, promotion-ladder inputs, 366 source calendar words, training-camp prices/quality and credit factors |
| `TEXTD.BLK` / `TEXTE.BLK` | Local `de-original` / `en-original` gettext layer and an indexed text table with raw bytes |
| Unmapped master fields | Named hexadecimal tables, original name pools, original player words, badge/kit selectors, squad words and flags |
| Source master database | Exact file bytes in `x-legacy/source-database.json`, hexadecimal, for lossless later re-mapping |
| Nations and teams | All named clubs/national teams, nine leagues, amateur pool, foreign nation blocks, encoded strength band/style, crest and kit selectors |
| Players | All 2,574 identities, squads, raw words/flags, attributes, age reference, nationality and frozen portrait recipe |
| Staff | Referee names, properties and strictness; human/computer manager setup is a runtime initializer |
| Contracts and finance | Contract seeds per assigned player and finance policies for all 138 league clubs; actual values are created by the same manager/season initialization as today |
| Stadiums | Entire name pool and stadium initializer, with all building, capacity, price and facility tables retained in Classic data regions |
| Competitions | Nine league definitions and fixture generators, plus every configured cup-table stage with links, flags, group/qualifying information and runtime participant resolvers |
| Calendar and rules | Day table, league bindings, cup series, ladder, training camps, credit factors, initialization sequence and all remaining data-region content |
| Text | UTF-8 original gettext layer, indexed strings, raw text blob and embedded executable-data texts |
| Artwork | Every numeric `KB/*.VGA` and `W/*.VGA` decoded as indexed PNG plus exact pixel indices; crest crops, original palette, portrait parts, bitmap fonts |
| Audio and optional art | Four original audio containers with chunk descriptors; optional FLI/FLC animation and WAPPEN.LBM when present |
| Preservation | Exact master-database bytes, named auxiliary tables/pools, original and effective data regions, resource metadata and CRC32 inventory |
`x-legacy/import-report.json` records warnings and outstanding mappings. Staff,
contracts and finance tables are empty: their initialized values are created
by career setup, rather than supplied as complete records by the master database.
Stadium names are exported without invented owners or capacities. Squad rows are
preserved as legacy rows, not claimed to be shirt numbers. A source player name
is kept whole in `name.last`; the importer does not guess first/last-name splits.
A source database does **not** contain ready-made human-manager finances,
contracts or stadium capacities. Those depend on the selected club, game level,
mode and random seeds. The world specifies their initialization rather than
inventing a balance, contract term or stadium owner. Imported player attributes
are the master seeds; the existing Classic initialization changes ratings and
ages and can shuffle club draw positions. This consumes no RNG during import.
Exact birth dates are unknown. A player instead carries
`age_at_start: {"years": 22, "on": "2026-07-01"}`. This is an explicit alternative
to `born`, not an assumed birthday. Attribute scales are the stored scales:
form, technique, condition and bonus 0–127; skills 0–3; display strength 0–99.
`bmh-classic@1` in `world/rules.json` declares those scales and marks strength as
derived. These are master seeds, before career initialization varies ratings,
rewrites nationality fields or shuffles league participants. No career is
started and no random stream is consumed during import.
Player `appearance` is computed from the **raw legacy byte name**, before Unicode
conversion. It freezes the background and five layer indices once. Name overlays
must retain this field. The imported set stores individual transparent parts and
placement metadata; composed player faces are never stored. Packed atlas parts
which cross a source row boundary retain their original pixels.
### Identifiers and edition mappings
The effective data use OpenBMH's existing supported rule profile. Unpatched
source data are preserved separately, including Football Limited's native data
segment. Neither copy includes a DOS header, executable code or relocation
instructions. `x-classic` is a documented compatibility bridge, not a claim that
the current address-based engine has already been replaced.
Ids derive from source identity slots, not names: `club:00000`, `player:00000`,
`stadium:00000`. National teams use `nt:<nation key>`. Recognized geographic
aliases get ISO nation keys (England/Scotland/Wales/Northern Ireland use private
football-association keys). Unrecognized or duplicate labels get
`nation:x-legacy-<index>` with confederation `other` and a warning. Foreign clubs
whose nation has not been decoded refer to `nation:x-legacy-unassigned`.
The source index always remains in `x-legacy`.
## Stable identities and original encodings
| Source leagues | German | Football Limited |
|---|---|---|
| 0, 1 | Tiers 1, 2; 18 clubs each | Tiers 1, 2; 20 clubs each |
| 2, 3 | Parallel tier 3, ids ending `-3-a` / `-3-b`; 18 each | Tiers 3, 4; 20 each |
| 4 | Tier 4; 18 clubs | Tier 5; 10 clubs, `played: false`, no fixture generator |
| 5–8 | Four 12-club leagues, using nation slots 1–4 | Same, with the English database's nation-slot order |
| 138–167 | Named amateur-pool slots | Only named slots become entities; unnamed slots remain in the source data |
| 168–356 | Foreign teams without squads | Same |
| 357–418 | National teams / nationality labels | Same |
IDs derive from master identity slots: `club:00000`, `player:00000`,
`stadium:00000`; national teams use `nt:<nation-key>`. Recognized countries get
ISO keys, with private association keys for England/Scotland/Wales/Northern
Ireland. Unrecognized/duplicate country labels retain `nation:x-legacy-<index>`
and a report warning, preserving modded or historical identities.
Foreign strength bytes encode a band and style flags, not a 0–255 rating. They
stay in `x-legacy.strength_code` until a typed interpretation is implemented.
Fixture tables store home/away **draw-position pairs**, not final shuffled
career fixtures. Calendar words remain source day offsets; competition options
and weekday alignment have not run. Promotion and European-place bytes are
retained as inputs, without pretending that cup qualifications have been mapped.
Foreign club indices 168–356 form 27 blocks of seven teams corresponding to
nation slots 5–31. The nine league ranges retain their edition-specific sizes:
German 18/18/18/18/18 and four 12-team leagues; English 20/20/20/20/10 and four
12-team leagues. The English fifth division is an unplayed pool; no ten-team
fixture generator is invented. Unnamed English amateur slots remain in the
preserved source rather than becoming fabricated clubs.
The existing executable loaders apply OpenBMH's supported rule profile, and the
English loader translates FLTD data into the common address space. The manifest
records `rule_profile: openbmh-supported`; this tool does **not** claim an
unmodified dump of every original edition's rules. No executable is included in
the OBW file.
Text follows ISO 646-DE substitutions and preserves extended bytes as Latin-1
Unicode code points; raw bytes remain available. Player names are kept whole in
`name.last`, without guessing first/last-name splits. Fixture tables describe
draw positions; qualified participants and final fixtures are resolved at the
same initialization phase as in the Classic engine.
### Text and rights
## Validation and verification
Text follows the existing ISO 646-DE substitutions. Extended bytes are preserved
as Latin-1 Unicode code points and original hexadecimal bytes; control/layout
codes remain available in the legacy text table. The local gettext catalogue
uses stable `legacy.text.<index>` message ids with `legacy-text` context. It is
a preservation layer, not a completed translation of the modern interface.
`--validate` checks the profile, versions, safe paths, unique entity/asset IDs,
core references, squad/stage counts, complete cup bindings, contract ownership,
initialization contract, media shapes, portrait indices, resource files and the
inventory before accepting a world. ZIP and directory readers enforce size
limits; directory symlinks and injected `state/` content are rejected. CRC32
catches accidental damage; it is not a signature or proof of trustworthy content.
This is the Classic profile validator, not a general competition engine or a full
JSON Schema implementation. Draft 2020-12 schemas are provided for external tools.
Imported names and texts retain their original ownership. Keep the resulting
world on your machine; the importer does not grant permission to distribute it.
The public repository contains only implementation, schemas and synthetic tests.
`obw_import_tests` uses synthetic data to cover both editions, binary round trips,
frozen appearances, malformed input and damaged payloads. With `BMH_DATA`,
`obw_classic_installation_tests` imports an installation, writes/reopens its ZIP,
reconstructs the startup inputs without reading the source again, and compares
first-season initialization bytes and both RNG streams. It also compares data
regions, atlas pixels, palette, fonts and audio against the source. The same test
can be run with a Football Limited directory as its argument. It does not test
OBW integration in a released client or a complete played season.
## Validation and remaining work
## Partial development export
The tool checks required documents, table versions, duplicate identities,
cross-table team/nation references, stage participant counts, fixture rows,
source squad ownership and supported edition sizes before publishing output.
Malformed/truncated input is an error; it does not substitute synthetic game
content. `obw_import_tests` covers synthetic German/English mappings, legacy
reader input, archive/directory round trips and rejected inputs.
`--database-only` deliberately retains the previous `legacy-database-v1` export
for database investigations without media. Its manifest remains
`playable: false`, requires `import:legacy-database-v1`, and its report lists gaps.
It is **not** one of the completed Classic mods. Default imports never silently
fall back to this mode.
Still to implement: full cup definitions/qualification and dated calendars,
complete rule mappings, initialized finances/contracts/staff/stadiums, asset
conversion, `.FBM` to `.obs`, a general OBW reader/validator and the 0.2 engine
adapter. First-season equivalence and save continuation regressions only become
possible when that adapter exists; the first converter does not claim them.
## Rights and excluded data
All imported content remains local and retains its original ownership. Do not
publish generated worlds or assets without appropriate rights. Public tests and
schemas contain only independently authored implementation and synthetic data.
There is **no savegame converter**. `.FBM`, personal `.EIN`, `SOUND.CFG`, high
scores, backups, editor/program executables and manuals are not imported.
Manager choices and career RNG state belong to a new game or later `.obs` save,
not to this installation conversion.
@@ -0,0 +1,55 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": true,
"$id": "https://raw.githubusercontent.com/Weyoune/openbmh/main/docs/formats/obw/schema/1.0/asset-index.json",
"properties": {
"schema": {
"const": "asset-index@1.0"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^asset:"
},
"files": {
"type": "object",
"minProperties": 1,
"additionalProperties": {
"type": "string"
}
},
"source": {
"type": "string"
},
"author": {
"type": "string"
},
"license": {
"const": "local-import-only"
},
"kind": {
"type": "string"
}
},
"required": [
"key",
"files",
"source",
"author",
"license",
"kind"
]
}
}
},
"required": [
"schema",
"items"
],
"$comment": "SPDX-License-Identifier: GPL-3.0-only; legacy database and Classic installation profiles."
}
@@ -0,0 +1,41 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": true,
"$id": "https://raw.githubusercontent.com/Weyoune/openbmh/main/docs/formats/obw/schema/1.0/classic-inventory.json",
"properties": {
"schema": {
"const": "classic-inventory@1.0"
},
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"bytes": {
"type": "integer",
"minimum": 0
},
"crc32": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"path",
"bytes",
"crc32"
]
}
}
},
"required": [
"schema",
"entries"
],
"$comment": "SPDX-License-Identifier: GPL-3.0-only; legacy database and Classic installation profiles."
}
@@ -0,0 +1,26 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": true,
"$comment": "SPDX-License-Identifier: GPL-3.0-only; Classic installation content.",
"$id": "https://raw.githubusercontent.com/Weyoune/openbmh/main/docs/formats/obw/schema/1.0/classic-palette.json",
"properties": {
"schema": {
"const": "classic-palette@1.0"
},
"argb": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"minItems": 256,
"maxItems": 256
}
},
"required": [
"schema",
"argb"
]
}
@@ -0,0 +1,200 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": true,
"$comment": "SPDX-License-Identifier: GPL-3.0-only; Classic installation content.",
"$id": "https://raw.githubusercontent.com/Weyoune/openbmh/main/docs/formats/obw/schema/1.0/classic-resources.json",
"properties": {
"schema": {
"const": "classic-resources@1.0"
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"width": {
"type": "integer",
"minimum": 1,
"maximum": 65535
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 65535
},
"pixels": {
"type": "string"
},
"png": {
"type": "string"
}
},
"required": [
"name",
"width",
"height",
"pixels",
"png"
]
}
},
"fonts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"height": {
"type": "integer",
"minimum": 0
},
"baseline": {
"type": "integer",
"minimum": 0
},
"nominal_width": {
"type": "integer",
"minimum": 0
},
"flags": {
"type": "integer",
"minimum": 0
},
"lo_char": {
"type": "integer",
"minimum": 0
},
"hi_char": {
"type": "integer",
"minimum": 0
},
"modulo": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string"
},
"bitmap": {
"type": "string"
},
"glyphs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bit_offset": {
"type": "integer",
"minimum": 0
},
"bit_width": {
"type": "integer",
"minimum": 0
},
"advance": {
"type": "integer"
}
},
"required": [
"bit_offset",
"bit_width",
"advance"
]
}
}
},
"required": [
"name",
"height",
"baseline",
"nominal_width",
"flags",
"lo_char",
"hi_char",
"modulo",
"glyphs",
"bitmap"
]
},
"minItems": 2,
"maxItems": 2
},
"audio": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"codec": {
"const": "original-alptraum@1"
},
"chunks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"offset": {
"type": "integer",
"minimum": 0
},
"size": {
"type": "integer",
"minimum": 0
}
},
"required": [
"id",
"offset",
"size"
]
}
}
},
"required": [
"name",
"path",
"codec",
"chunks"
]
},
"minItems": 4,
"maxItems": 4
},
"optional": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"name",
"path"
]
}
}
},
"required": [
"schema",
"images",
"fonts",
"audio",
"optional"
]
}
@@ -0,0 +1,189 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": true,
"$id": "https://raw.githubusercontent.com/Weyoune/openbmh/main/docs/formats/obw/schema/1.0/classic-startup.json",
"properties": {
"schema": {
"const": "classic-startup@1.0"
},
"layout": {
"const": "openbmh-classic-layout@1"
},
"mod": {
"enum": [
"BMH-classic",
"FLTD-classic"
]
},
"english": {
"type": "boolean"
},
"rule_profile": {
"const": "openbmh-supported@1"
},
"data_regions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"base": {
"type": "integer"
},
"size": {
"type": "integer",
"minimum": 1
},
"path": {
"type": "string"
}
},
"required": [
"name",
"base",
"size",
"path"
]
},
"minItems": 1,
"maxItems": 2
},
"source_regions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"base": {
"type": "integer"
},
"size": {
"type": "integer",
"minimum": 1
},
"path": {
"type": "string"
}
},
"required": [
"name",
"base",
"size",
"path"
]
},
"minItems": 1,
"maxItems": 2
},
"desktop_seed": {
"type": "string"
},
"formation_seed": {
"type": "string"
},
"text_blob": {
"type": "string"
},
"initializers": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 8,
"maxItems": 8
},
"runtime_inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"rng": {
"type": "object"
},
"embedded_literals": {
"type": "array",
"minItems": 4,
"maxItems": 4,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "integer"
},
"bytes_hex": {
"type": "string",
"pattern": "^(?:[0-9a-f]{2})+$"
}
},
"required": [
"name",
"address",
"bytes_hex"
]
}
},
"source_literals": {
"type": "array",
"minItems": 4,
"maxItems": 4,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "integer"
},
"bytes_hex": {
"type": "string",
"pattern": "^(?:[0-9a-f]{2})+$"
}
},
"required": [
"name",
"address",
"bytes_hex"
]
}
},
"text_header": {
"type": "array",
"minItems": 7,
"maxItems": 7,
"items": {
"type": "integer",
"minimum": 0,
"maximum": 255
}
}
},
"required": [
"schema",
"layout",
"mod",
"english",
"rule_profile",
"data_regions",
"source_regions",
"desktop_seed",
"formation_seed",
"text_blob",
"initializers",
"runtime_inputs",
"rng",
"embedded_literals",
"source_literals",
"text_header"
],
"$comment": "SPDX-License-Identifier: GPL-3.0-only; legacy database and Classic installation profiles."
}
+74 -20
View File
@@ -19,7 +19,14 @@
"$ref": "common.json#/$defs/localized"
},
"type": {
"const": "league"
"enum": [
"league",
"cup",
"club_international",
"national_team",
"friendly",
"indoor"
]
},
"nation": {
"$ref": "common.json#/$defs/nation_id"
@@ -40,12 +47,18 @@
"type": "string"
},
"format": {
"const": "league"
"enum": [
"league",
"groups",
"knockout",
"final",
"playoff"
]
},
"teams": {
"type": "integer",
"minimum": 4,
"maximum": 24
"minimum": 0,
"maximum": 255
},
"legs": {
"type": "integer",
@@ -60,20 +73,46 @@
"slots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"teams": {
"type": "array",
"items": {
"$ref": "common.json#/$defs/team_id"
"oneOf": [
{
"type": "object",
"properties": {
"teams": {
"type": "array",
"items": {
"$ref": "common.json#/$defs/team_id"
},
"uniqueItems": true
}
},
"uniqueItems": true
"required": [
"teams"
]
},
{
"type": "object",
"properties": {
"resolver": {
"const": "classic-entry@1"
},
"entry": {
"type": "integer",
"minimum": 0,
"maximum": 35
},
"count": {
"type": "integer",
"minimum": 0,
"maximum": 255
}
},
"required": [
"resolver",
"entry",
"count"
]
}
},
"required": [
"teams"
],
"additionalProperties": true
]
},
"minItems": 1
}
@@ -94,12 +133,27 @@
"id",
"name",
"type",
"nation",
"tier",
"played",
"stages"
],
"additionalProperties": true
"additionalProperties": true,
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "league"
}
}
},
"then": {
"required": [
"nation",
"tier"
]
}
}
]
}
}
},
@@ -108,5 +162,5 @@
"items"
],
"additionalProperties": true,
"$comment": "SPDX-License-Identifier: GPL-3.0-only; initial legacy-database-v1 conversion profile."
"$comment": "SPDX-License-Identifier: GPL-3.0-only; legacy database and Classic installation profiles."
}
+119 -22
View File
@@ -69,8 +69,17 @@
"additionalProperties": true
},
"requires": {
"const": [
"import:legacy-database-v1"
"oneOf": [
{
"const": [
"import:legacy-database-v1"
]
},
{
"const": [
"runtime:classic-v1"
]
}
]
},
"extensions": {
@@ -93,27 +102,76 @@
}
},
"x-import": {
"type": "object",
"properties": {
"profile": {
"const": "legacy-database-v1"
"oneOf": [
{
"type": "object",
"properties": {
"profile": {
"const": "legacy-database-v1"
},
"playable": {
"const": false
},
"rule_profile": {
"const": "openbmh-supported"
},
"default_attribute_set": {
"type": "string"
}
},
"required": [
"profile",
"playable",
"rule_profile"
],
"additionalProperties": true
},
"playable": {
"const": false
},
"rule_profile": {
"const": "openbmh-supported"
},
"default_attribute_set": {
"type": "string"
{
"type": "object",
"properties": {
"profile": {
"const": "classic-installation-v1"
},
"content_complete": {
"const": true
},
"runtime": {
"const": "runtime:classic-v1"
},
"rule_profile": {
"const": "openbmh-supported@1"
},
"source_rules_preserved": {
"const": true
},
"default_attribute_set": {
"const": "bmh-classic@1"
},
"default_portrait_set": {
"const": "bmh-classic@1"
}
},
"required": [
"profile",
"content_complete",
"runtime",
"rule_profile",
"source_rules_preserved",
"default_attribute_set",
"default_portrait_set"
],
"additionalProperties": true
}
},
"required": [
"profile",
"playable",
"rule_profile"
],
"additionalProperties": true
]
},
"id": {
"type": "string"
},
"mod": {
"enum": [
"BMH-classic",
"FLTD-classic"
]
}
},
"required": [
@@ -134,5 +192,44 @@
"x-import"
],
"additionalProperties": true,
"$comment": "SPDX-License-Identifier: GPL-3.0-only; initial legacy-database-v1 conversion profile."
"$comment": "SPDX-License-Identifier: GPL-3.0-only; legacy database and Classic installation profiles.",
"allOf": [
{
"if": {
"properties": {
"requires": {
"const": [
"runtime:classic-v1"
]
}
}
},
"then": {
"required": [
"id",
"mod"
],
"properties": {
"x-import": {
"properties": {
"profile": {
"const": "classic-installation-v1"
}
}
}
}
},
"else": {
"properties": {
"x-import": {
"properties": {
"profile": {
"const": "legacy-database-v1"
}
}
}
}
}
}
]
}
@@ -0,0 +1,85 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": true,
"$id": "https://raw.githubusercontent.com/Weyoune/openbmh/main/docs/formats/obw/schema/1.0/portrait-set.json",
"properties": {
"schema": {
"const": "portrait-set@1.0"
},
"id": {
"const": "bmh-classic@1"
},
"width": {
"const": 38
},
"height": {
"const": 38
},
"transparent_index": {
"const": 0
},
"backgrounds": {
"type": "array",
"minItems": 4,
"maxItems": 4,
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string"
},
"x": {
"type": "integer"
},
"y": {
"type": "integer"
}
},
"required": [
"asset",
"x",
"y"
]
}
},
"layers": {
"type": "array",
"minItems": 5,
"maxItems": 5,
"items": {
"type": "object",
"properties": {
"x": {
"type": "integer"
},
"y": {
"type": "integer"
},
"parts": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
},
"required": [
"x",
"y",
"parts"
]
}
}
},
"required": [
"schema",
"id",
"width",
"height",
"backgrounds",
"layers",
"transparent_index"
],
"$comment": "SPDX-License-Identifier: GPL-3.0-only; legacy database and Classic installation profiles."
}