Files
Dreierpack-Manager/docs/formats/obw/import.md
T

144 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:<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`.
| 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.<index>` 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.