# Legacy installation importer (first version) `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. ## Build and use Configure the project as described in [BUILDING](../../BUILDING.md), then build the additional target: ```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" ``` 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: ```sh ./build/openbmh_import --data "path/to/FLTD.EXE" --output "season-directory" \ --start-date 1995-07-01 --directory ``` `--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 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. 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. ## Conversion profile and coverage 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 | |---|---| | `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 | `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. 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. ### Identifiers and edition mappings Ids derive from source identity slots, not names: `club:00000`, `player:00000`, `stadium:00000`. National teams use `nt:`. 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-` 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`. | 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 | 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. 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 and rights 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.` message ids with `legacy-text` context. It is a preservation layer, not a completed translation of the modern interface. 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. ## Validation and remaining work 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. 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.