diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d3afe2d..775f908 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -12,7 +12,7 @@ Complete edition-specific loading, presentation, competitions and sound support. ## 0.2: open data and typed state -Introduce a documented import format and a native save format, retaining supported legacy import where practical. Replace fixed-layout state gradually with typed clubs, players, contracts and competitions. Keep each intermediate stage usable and cover transitions with tests. +Introduce a documented import format and a native save format, retaining supported legacy import where practical. The format concept is [OBW](formats/OBW.md). Replace fixed-layout state gradually with typed clubs, players, contracts and competitions. Keep each intermediate stage usable and cover transitions with tests. ## 0.3: configurable rules @@ -20,7 +20,7 @@ Expose rule values and balance choices as configuration, with reproducible simul ## 0.4: adaptable interfaces and competitions -Add a scalable interface through the shared application/protocol boundary. Make league sizes and competition structures data-driven. Define content-pack formats for independently licensed artwork, names and other resources; do not distribute third-party material without permission. +Add a scalable interface (RmlUi) through the shared application/protocol boundary. Make league sizes and competition structures data-driven. Define content-pack formats for independently licensed artwork, names and other resources; do not distribute third-party material without permission. ## 0.5: independently distributable content diff --git a/docs/formats/OBW.md b/docs/formats/OBW.md new file mode 100644 index 0000000..495bd21 --- /dev/null +++ b/docs/formats/OBW.md @@ -0,0 +1,475 @@ +# OBW: OpenBMH world, save and pack format (concept, format version 1.0) + +Status: **concept** for roadmap 0.2 (open data and typed state) with preparation for 0.4 (scalable interface, content packs). Nothing here is implemented yet; the legacy formats in this directory remain authoritative for the current engine. + +## 1. Goals and non-goals + +Goals: + +- One documented, versioned format for a game world (start database), a running career (save) and content packs. +- A typed model of nations, clubs, players, staff, contracts, finances and competitions that no longer depends on the memory image of a particular executable. +- Data-driven competitions: up to **32 leagues** (national and foreign leagues together), real-world European club cups (league phase plus knockout), and national-team competitions including qualification and a Nations-League-style tiered competition. +- Import from the supported German editions and from Football Limited (FLTD), both for a new career and for an existing `.FBM` save. +- Preparation for a high-resolution interface built with RmlUi: logical asset keys, high-resolution crests and icons, player photos, further languages and modern font formats. +- Forward compatibility: readers of the same major version accept files written by later minor versions. + +Non-goals of version 1.0: + +- The match engine and its parameters (reserved namespace `x-matchengine`, see §3.3). +- Network play, an editor application and a binary encoding (reserved, see §2.4). +- Layout or screen data. Interfaces are themes (§9.6), not part of a world. + +## 2. Container and files + +### 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. + +| Extension | `kind` | Contents | +|---|---|---| +| `.obw` | `world` | Start database: everything needed to begin a career | +| `.obs` | `save` | A world plus the running state of a career | +| `.obp` | `pack` | Overlays and assets for worlds (names, crests, photos, texts) | +| `.obt` | `theme` | Interface theme for the RmlUi client (§9.6) | + +An unpacked directory with the same layout is accepted wherever an archive is, which keeps development and version control simple. + +### 2.2 Layout + +``` +manifest.json required, §3 +world/nations.json nations and their national teams +world/clubs.json clubs (teams of type "club") +world/players.json players +world/staff.json managers, coaches, other staff +world/stadiums.json stadiums +world/contracts.json player and staff contracts +world/finance.json club finances, sponsors, advertising, loans, shares +world/competitions.json competition definitions, §6 +world/calendar.json season calendar, §7 +world/rules.json rule values (training camps, interest rates, ...) +state/... save only, §5.9 +locale//*.po texts, §9.3 +assets/... packs and themes only, §9 +x-/... extensions, §3.3 +``` + +Every table file is an object `{"schema": "@.", "items": [...]}`. Tables with many rows (results, history, mail) may instead be stored as JSON Lines (`*.jsonl`, one item per line, first line the header object without `items`). + +### 2.3 Encoding rules + +- Text is UTF-8. Legacy single-byte text is converted on import (`iso646de_to_utf8`). +- Money is an integer in the smallest unit of the world currency (`manifest.currency`, e.g. `{"code": "DEM", "minor_units": 0}`); no floating point for money. +- Dates are ISO 8601 calendar dates (`"1995-07-01"`), in-game time is a date plus an optional `"minute"`. +- Percentages and ratings are integers on the scale declared by their attribute set (§5.3). +- Optional fields may be omitted; the schema gives their default. + +### 2.4 Reserved + +A compact binary encoding of large `state/` tables is reserved for a later minor version as an alternative representation of the same schema (`"encoding": "cbor"` in the table header). Readers of 1.0 reject unknown encodings with a clear error. + +## 3. Versioning and migration + +### 3.1 Manifest + +```json +{ + "format": "openbmh-world", + "format_version": "1.0", + "kind": "world", + "min_reader": "1.0", + "generator": "OpenBMH 0.2.0", + "created": "2026-10-17", + "title": {"default": "Season 1995/96"}, + "provenance": "import:bmh-de", + "content_license": "local-import-only", + "currency": {"code": "DEM", "minor_units": 0}, + "start_date": "1995-07-01", + "languages": ["de"], + "limits": {"leagues": 32}, + "requires": [], + "extensions": [] +} +``` + +- `format_version` is `major.minor`. A **minor** step only adds optional fields, tables, enum values that have a documented fallback, or new stage types guarded by `requires`. A **major** step may rename, remove or re-interpret fields. +- `min_reader` is the lowest reader version that can use the file correctly (a writer raises it when it uses a minor feature without a safe fallback). +- `requires` lists features without which the file cannot be played, e.g. `["stage:swiss"]`; a reader that lacks one refuses the file instead of guessing. +- `provenance` records where the content came from: `native`, `import:bmh-de`, `import:bmh-de-classic`, `import:fltd`, or `pack:`. `content_license` is free text or an SPDX identifier; `local-import-only` marks data converted from a user's own installation (§8.4). + +### 3.2 Reading and migration + +- Readers ignore unknown fields and tables, keep them in memory and write them back unchanged (round trip), so a newer minor version survives an older tool. +- Missing optional fields take the schema default. +- Older major versions are upgraded on load through a chain of migrations (`migrate_1_to_2`, `migrate_2_to_3`, ...). Writers always write the newest version; a migrated save is written under a new name unless the player confirms the upgrade. +- Each table carries its own `schema` version, so a table can advance a minor step independently; the manifest version is the highest of them. + +### 3.3 Extensions + +Fields and directories whose name starts with `x-` belong to extensions (`x-matchengine`, `x-realnames`, `x-editor`). The core never interprets them, preserves them on round trip and lists active ones in `manifest.extensions` with a version, e.g. `{"id": "x-matchengine", "version": "1.0"}`. + +### 3.4 Schemas + +Each format version is published as JSON Schema (draft 2020-12) under `docs/formats/obw/schema/./`, one file per table. The schemas are the machine-readable specification and the basis of the validator (§10). + +## 4. Identifiers and names + +- Every entity has a stable string id `:`, e.g. `nation:de`, `club:0042`, `player:01873`, `comp:de-1`, `stadium:0042`. Keys are opaque: they never encode a real name, so a world and a pack can be published independently. +- Ids are unique within a world and never reused within a save. The engine assigns runtime indices; files never store them. +- Nation keys use ISO 3166-1 alpha-2 where one exists, otherwise a documented private key (`nation:x-eng` for England, `nation:x-sco`, ...). +- Every displayed name is a localized string: `{"default": "...", "en": "...", "short": {"default": "..."}}`. `default` is required; a language entry overrides it; `short` and `abbr` are optional display variants for narrow layouts. +- Packs overlay names, crests and photos by id (§9.5), never by position. + +## 5. Entities + +Field lists name the type and whether the field is required (R) or optional (O, with default). Only the main fields are listed; the schema is authoritative. + +### 5.1 Nation (`world/nations.json`) + +| Field | Type | | Meaning | +|---|---|---|---| +| `id` | string | R | `nation:` | +| `name` | localized | R | | +| `confederation` | string | R | `uefa`, `conmebol`, `caf`, `afc`, `concacaf`, `ofc`, `other` | +| `coefficient` | integer | O 0 | Club-competition ranking points (§6.6) | +| `strength` | integer | O 0 | Rating of the national team when no squad is simulated | +| `national_team` | string | O | Team id of type `national` (§5.2) | +| `playable` | bool | O false | Whether its leagues are simulated in full | + +### 5.2 Team (`world/clubs.json`) + +Clubs and national teams share one entity type, distinguished by `type`. + +| Field | Type | | Meaning | +|---|---|---|---| +| `id` | string | R | `club:` or `nt:` | +| `type` | enum | R | `club`, `national`, `amateur` (newcomer pool), `foreign` (strength only) | +| `name` | localized | R | | +| `nation` | string | R | | +| `stadium` | string | O | | +| `colors` | array | O | 1 to 3 `#rrggbb` values, used for generated crests and kits | +| `reputation`, `fans`, `strength` | integer | O | Club values on the attribute scale of the world | +| `founded` | integer | O | Year | +| `crest` | string | O | Asset key, default `asset:club//crest` (§9.1) | +| `x-*` | any | O | Extensions | + +Teams without a squad (`foreign`, or `national` in a world that does not simulate national squads) carry `strength` instead of players. + +### 5.3 Player (`world/players.json`) + +| Field | Type | | Meaning | +|---|---|---|---| +| `id` | string | R | | +| `name` | object | R | `{"first": "...", "last": "...", "known_as": "..."}`, each a plain string; `known_as` optional | +| `born` | date | R | Age is derived from the in-game date | +| `nationalities` | array | R | Nation ids, first entry is the sporting nationality (national-team eligibility) | +| `positions` | array | R | `gk`, `def`, `mid`, `fwd` in the classic set; finer positions in later attribute sets | +| `foot` | enum | O | `left`, `right`, `both` | +| `attribute_set` | string | O world default | e.g. `bmh-classic@1` | +| `attributes` | object | R | Values named by the attribute set, e.g. `{"strength": 7, "technique": 5, "condition": 9, "form": 6}` | +| `character` | object | O | Traits the attribute set defines | +| `team` | string | O | Current team id; absent for free agents | +| `squad_number` | integer | O | | +| `status` | object | O | Injury, suspension and card counters per competition (save only) | +| `photo` | string | O | Default `asset:player//photo` | + +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: + +```json +{"id": "bmh-classic@1", "fields": { + "strength": {"min": 1, "max": 10}, + "technique": {"min": 1, "max": 10}, + "condition": {"min": 0, "max": 100}, + "form": {"min": 1, "max": 10}}} +``` + +The exact list and scales of `bmh-classic@1` are fixed when the importer is written, from the fields the current engine uses (`Player` in `src/game/state.hpp`). + +### 5.4 Staff and managers (`world/staff.json`) + +Managers (human or computer), coaches and other employees: `id`, `name`, `born`, `nation`, `role` (`manager`, `coach`, `physio`, ...), `team`, `attributes`. In a save, `state/managers.json` adds the human manager profile: options, ratings, history, automation settings. + +### 5.5 Contracts (`world/contracts.json`) + +`id`, `person` (player or staff id), `team`, `start`, `end`, `salary` (money per season), `bonuses` (signing, per goal, ...), `release_clause` (O), `options` (O). One active contract per person and team; the history is kept in the save. + +### 5.6 Stadiums (`world/stadiums.json`) + +`id`, `name`, `capacity` split by area (`standing`, `seated`, `boxes`), `facilities` (floodlights, heating, scoreboard, ... as named levels), `pitch`, `owner` (team id or `null`). + +### 5.7 Finance (`world/finance.json`) + +Per team: balance, ticket prices, sponsors (shirt, boards, with duration and value), advertising, loans (amount, rate, due date), shares and other income or cost sources the engine models today. Rate tables such as the credit table live in `world/rules.json`. + +### 5.8 Rules (`world/rules.json`) + +Named rule values that are content of the world rather than of the engine: training-camp resorts (price, quality grades), credit-rate tables, attribute sets, points for a win, squad limits. Today these values are read from the executable of the selected edition; in OBW they are ordinary data (and the starting point of the configurable rules of roadmap 0.3). + +### 5.9 Save state (`state/`, saves only) + +| File | Contents | +|---|---| +| `state/career.json` | Current date, season, phase, active human managers, settings | +| `state/rng.json` | State of the random generator(s) (`docs/RNG.md`), so a load continues deterministically | +| `state/tables.json` | Standings per competition stage and group | +| `state/results.jsonl` | Every played or scheduled match: competition, stage, round, home, away, result, after extra time / penalties | +| `state/squads.json` | Lineups, formations, tactics per team | +| `state/history.jsonl` | Season history: champions, cup winners, top scorers, records | +| `state/mail.jsonl` | Messages and news | +| `state/market.json` | Transfer list, open bids, loan offers | +| `state/x-legacy.json` | Unmapped legacy values carried over by the importer (§8.3) | + +## 6. Competitions + +### 6.1 Model + +A competition is an ordered list of **stages**. Each stage takes teams from **slots** (§6.4), plays a format and hands teams on (to the next stage, to another competition, or to a final ranking). + +```json +{ + "id": "comp:de-2", + "name": {"default": "2. Liga"}, + "type": "league", + "nation": "nation:de", + "tier": 2, + "season_cycle": 1, + "stages": [{ + "id": "regular", + "format": "league", + "teams": 18, + "legs": 2, + "points": {"win": 3, "draw": 1, "loss": 0}, + "tiebreakers": ["points", "goal_difference", "goals_for", "head_to_head", "draw_lots"], + "matchdays": "calendar:league-weekends" + }], + "movement": [ + {"ranks": [1, 2], "to": "comp:de-1"}, + {"ranks": [3], "to": "comp:de-1/playoff", "role": "challenger"}, + {"ranks": [16, 18], "to": "comp:de-3"} + ] +} +``` + +`type` is `league` (counts towards the league limit), `cup` (national cup), `club_international`, `national_team`, `friendly` or `indoor`. + +### 6.2 Stage formats + +| Format | Purpose | Main parameters | +|---|---|---| +| `league` | Round robin | `teams`, `legs` (1, 2, n), `points`, `tiebreakers`, fixture generator | +| `groups` | Several round robins | `groups`, `teams_per_group`, `legs`, seeding `pots`, draw constraints (e.g. no two teams of one nation) | +| `swiss` | League phase with a fixed number of games against drawn opponents | `teams` (e.g. 36), `matches` (e.g. 8), `pots`, `home_away_balance`, one common table | +| `knockout` | Ties | `legs` (1 or 2), `seeded`, `draw` (`open`, `seeded`, `bracket`), `extra_time`, `penalties`, `away_goals` (on/off), `neutral_venue`, `replay` (FA-Cup style) | +| `playoff` | Ties between teams of different competitions (relegation, qualification) | as `knockout` plus the roles of the participants | +| `final` | Single match or final tournament | `venue`, `teams` | + +Common stage parameters: `extra_time` (minutes), `penalties`, `suspensions` (cards that lead to a ban, counted per competition or per stage), `substitutions`, `squad_registration` (size, home-grown quota), `prize_money` per round and result, `tv_money`, `gate_split`. New formats are added through a minor version with an entry in `manifest.requires`. + +### 6.3 Fixture generation + +A `league` or `groups` stage names a generator: `"generator": "round-robin"` (circle method, home/away balanced) works for every size. The legacy round tables of the original game remain available as `"generator": "legacy:"` for imported worlds, so imported careers keep their familiar order; they come from the user's installation, not from the format. + +### 6.4 Slots and qualification + +Participants are declared, not hard-coded: + +```json +"slots": [ + {"from": "comp:de-1", "ranks": [1, 4], "stage": "league-phase"}, + {"from": "comp:de-cup", "winner": true, "to": "comp:uel", "stage": "league-phase", + "fallback": {"from": "comp:de-1", "next_unqualified": true}}, + {"from": "coefficient", "nation_rank": [1, 4], "places": 4}, + {"holder": "comp:ucl", "stage": "league-phase"} +] +``` + +A slot source is: a rank range of a stage, the winner/runner-up of a competition, the holder of a title, the next team not yet qualified (substitution rules), a coefficient ranking, or an explicit list. The engine resolves all slots at season end in the order given by `world/calendar.json`. + +### 6.5 League pyramid + +`movement` on a league connects tiers: promotion, relegation and playoffs between two leagues, several parallel lower leagues feeding one league (the two regional third divisions of the German editions), and a refill pool for the lowest tier (`"refill": {"from": "pool:amateur", "count": 2}`). This replaces the fixed per-edition tables in `src/game/schedule.hpp` (`kLeagueRelegation`, `kLeagueEurope`, `kGroupBelow`, `kNewcomerFirst`). + +### 6.6 Coefficients + +`world/rules.json` may define coefficient rankings (club and nation) with the points per result and per round reached and the number of seasons summed. They drive seeding pots and the number of European places per nation. A world may instead fix places per nation (`"places": {"nation:de": {"ucl": 4, "uel": 2}}`), which is how imported legacy worlds start. + +### 6.7 Templates + +The project ships competition templates under `docs/formats/obw/templates/`. They contain structure only, with neutral names: + +- **Club competitions:** a champions cup with a 36-team league phase, a knockout playoff for places 9 to 24, round of 16 to final; a second and a third club cup in the same shape; a super cup; the knockout-only cups of the original game. +- **National teams:** a world cup with continental qualification groups and playoffs, a continental championship with qualification, and a **tiered nations league**. The nations league has leagues A to D with groups of three or four, promotion and relegation between tiers, a final tournament for the group winners of A, and playoffs that can feed continental-championship places. +- **National cups and side competitions:** knockout national cups (with or without replays and a qualifying round), an indoor tournament, friendlies. + +### 6.8 National teams + +A world that simulates national teams gives each `national` team a call-up rule: squad size, eligibility through `nationalities[0]`, selection by attribute set (best `n` by position) or by a human manager. International windows in the calendar (§7) suspend club play when the world asks for it (`"club_break": true`). Worlds without national squads use `strength` and simulate only results. + +## 7. Calendar + +`world/calendar.json` describes a season as dated events, independent of the executable's day table: + +```json +{ + "season_start": "07-01", + "season_length_days": 365, + "windows": [ + {"id": "summer-transfer", "type": "transfer", "from": "07-01", "to": "08-31"}, + {"id": "intl-sep", "type": "international", "from": "09-02", "to": "09-10", "club_break": true} + ], + "series": [ + {"id": "league-weekends", "weekday": "sat", "from": "08-08", "to": "05-20", "skip": ["winter-break", "intl-*"]}, + {"id": "ucl-league-phase", "weekdays": ["tue", "wed"], "dates": ["09-16", "09-30"]} + ], + "events": [ + {"date": "06-30", "action": "season_end"}, + {"date": "01-05", "action": "training_camp_window"} + ] +} +``` + +Dates are month-day within the season; the engine maps them to concrete days each year, including leap years and seasons whose first day falls on a different weekday (the cases fixed in the current calendar code). Stages refer to a series by id. Imported worlds receive a calendar generated from the edition's day table, so the familiar rhythm stays. + +## 8. Import from BMH and Football Limited + +### 8.1 Sources + +The importer (planned module `src/import/`) reuses the existing loaders: + +| Source | Loader | Result | +|---|---|---| +| Master database `M3D.MAN` / `M3E.MAN` | `src/formats/m3d.cpp` | Clubs, players, staff, stadiums | +| Executable tables (league sizes, ladders, calendar, fixture tables, rule values) | `src/formats/le.cpp`, `src/launch/fltd.cpp`, `src/game/schedule.hpp` installers | Competitions, calendar, rules | +| Text database `TEXTD.BLK` / `TEXTE.BLK` | `src/formats/textd.cpp` | Local language layer `de-original` / `en-original` | +| Save `*.FBM` | `src/formats/fbm.cpp`, `savestate.cpp` | `state/` of a save | +| Crests and pictures `*.VGA`, `WAPPEN.LBM` | `src/formats/vga.cpp` | Low-resolution fallback assets, local only | + +Edition detection is the one the launcher already performs (`src/launch/game_data.cpp`). + +### 8.2 Mapping per edition + +Every edition has a mapping table in the importer (to be published with it as `docs/formats/obw/import.md`): + +| Legacy league | German editions | Football Limited | OBW | +|---|---|---|---| +| 0 | 1st division, 18 teams | 1st division, 20 teams | `comp:-1`, tier 1 | +| 1 | 2nd division, 18 | 2nd division, 20 | tier 2 | +| 2, 3 | Two parallel third divisions A and B, 18 each, one promotion group | 3rd and 4th division, 20 each | tier 3 (two leagues) / tiers 3 and 4 | +| 4 | Fourth tier, 18 | Fifth league, 10 teams, not played | tier 4 / tier 5 with `"played": false` | +| 5-8 | Four foreign leagues of 12 | Same four foreign leagues of 12 | `comp:-1` each, `nation.playable = true` | +| Newcomer pool | 30 amateur clubs | 12 further named clubs | `pool:amateur` | + +Cups, European cups, the indoor tournament, the English FA Cup with its qualifying stage and the League Cup become competitions with the same rules the engine applies today. Relegation places, European places and promotion groups are taken from the installed tables (`kLeagueRelegation`, `kLeagueEurope`, `kGroupBelow`), not re-typed by hand. + +### 8.3 Fidelity + +- 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. +- Values the typed model does not yet understand go to `state/x-legacy.json` with their legacy name, so nothing is lost while the model grows area by area. + +### 8.4 Rights + +Imported content stays on the player's machine. The importer marks it `"provenance": "import:..."` and `"content_license": "local-import-only"`; tools refuse to bundle such a world into a distributable pack. Only worlds and packs with their own licence may be shared. + +## 9. Assets, languages, fonts and the RmlUi interface + +### 9.1 Asset keys + +Data never refers to file paths. It uses logical keys: + +| Key | Meaning | +|---|---| +| `asset:club//crest` | Club crest | +| `asset:club//kit/home` | Kit | +| `asset:player//photo` | Player photo | +| `asset:staff//photo` | Staff photo | +| `asset:comp//logo`, `asset:comp//trophy` | Competition logo and trophy | +| `asset:nation//flag` | Flag | +| `asset:stadium//image` | Stadium picture | +| `asset:icon/` | Interface icon | + +### 9.2 Resolution and image formats + +A resolver looks a key up in the active packs by priority (§9.5), then in the world, then falls back: original low-resolution graphics of the installation where one exists, a crest generated from `colors`, a silhouette for photos, a neutral icon. + +- **Crests, logos, flags, icons:** SVG preferred (scales to every resolution). Otherwise PNG with alpha in size steps 64, 128, 256 and 512 px (`crest@128.png`). The resolver picks the smallest step not below the requested size. +- **Photos:** PNG, JPEG or WebP, aspect 3:4, reference size 300×400 px, larger allowed. Faces centred; the interface crops, it never stretches. +- **Pictures** (stadiums, backgrounds): PNG, JPEG or WebP, 16:9 reference 1920×1080. + +Asset metadata sits next to the files in `assets/index.json`: key, files per size, author, source and licence (required). + +### 9.3 Languages + +- Interface texts use gettext `.po` files under `locale//openbmh.po` (`msgctxt` for context, plural forms, mature translator tools such as Poedit and Weblate). Message ids are stable English keys. +- Data names are localized strings inside the tables (§4); packs can add languages to them. +- The original text databases are imported into a local layer `de-original` or `en-original`, which the classic interface uses. New interfaces use the project's own texts. +- A fallback chain is configured by the player, e.g. `["en-GB", "en", "de"]`. +- Text is shaped as Unicode (RmlUi supports it); no single-byte substitutions outside the legacy layer. + +### 9.4 Fonts + +- TrueType and OpenType (`.ttf`, `.otf`); RmlUi renders them through FreeType. Variable fonts are allowed. +- A theme declares font families with weights, a fallback chain covering the languages it claims, and the licence of every font file (for example SIL OFL). +- The original bitmap fonts stay for the classic interface only. + +### 9.5 Content packs (`.obp`) + +```json +{ + "format": "openbmh-world", + "format_version": "1.0", + "kind": "pack", + "id": "pack:example-crests", + "title": {"default": "Example crests"}, + "targets": [{"world_provenance": "import:bmh-de"}], + "priority": 100, + "content_license": "CC-BY-4.0", + "overlays": ["names", "assets", "locale"] +} +``` + +- A pack contains `overlay/
.json` files with partial entities by id (only the fields it changes), `assets/` and `locale/`. +- Several packs stack; the higher `priority` wins per field and per asset key. A pack may not add or remove entities in 1.0 (that is a world, not a pack), which keeps saves valid when a pack is removed. +- `targets` restricts a pack to worlds by provenance or world id. +- The project distributes only the format, tools and its own or freely licensed material. Packs with real names, crests or photos are made and shared by their authors under their own responsibility. The team's internal real-name pack uses this format and stays private. + +### 9.6 RmlUi themes (`.obt`) + +- A theme contains `.rml` documents, `.rcss` style sheets, fonts, icons and its `locale/` texts, plus a manifest naming the client version it targets. +- Interfaces bind to a **view model**, not to the world files. The client exposes data models (RmlUi data bindings) built from the application/protocol layer (`docs/protocol.md`), with ids and asset keys as values. RmlUi loads images through a file interface that resolves `asset:` keys (§9.2). +- Neither worlds nor packs contain layout, so a theme works with every world, and the classic 320×200 interface keeps working next to it. + +## 10. Validation and limits + +The validator (planned `openbmh_cli --validate `) checks, in this order: + +1. Container, manifest, `format_version`, `min_reader`, `requires`. +2. Every table against its JSON Schema. +3. References: every id used exists and has the right type; no id is defined twice. +4. Competition logic: slot counts match stage sizes; movements between tiers are balanced; every stage can be scheduled in the calendar; fixture generators exist for the sizes. +5. Engine limits declared in `manifest.limits` and enforced by the engine of a version. For 1.0: + +| Limit | Value | +|---|---| +| Competitions of type `league` (national and foreign) | **32** | +| Teams per league | 4 to 24 | +| Squad size per team | engine maximum of the attribute set | +| Groups per stage | 16 | + +The format itself has no fixed limits; a later engine raises them by changing `limits` and its own checks, without a format change. + +Errors name the file, the JSON path and the rule (`clubs.json: items[41].stadium: unknown id stadium:0999`). + +## 11. Implementation steps + +| Step | Roadmap | Content | +|---|---|---| +| 1 | 0.2 | Schemas 1.0, reader/writer, validator, round-trip tests with synthetic worlds | +| 2 | 0.2 | Importer for German editions and FLTD into `.obw`; adapter OBW → current `GameState`; regression: same first seasons | +| 3 | 0.2 | `.FBM` → `.obs` conversion and native OBW saves; area by area the engine reads typed data instead of the memory image (clubs, players, contracts, finances, then competitions) | +| 4 | 0.3 | `rules.json` drives the rule values; balance changes as data | +| 5 | 0.4 | Generic competition engine (stage formats, slots, pyramid, variable league sizes up to the limits); templates for the real-world club cups and national-team competitions | +| 6 | 0.4 | Asset resolver, packs, `.po` languages, RmlUi client with themes | +| 7 | 0.5 | Own worlds that need no original data | + +Each step keeps the game playable and the regression runs green; the legacy formats stay readable as import sources. diff --git a/docs/formats/README.md b/docs/formats/README.md index d0f5a10..fbb229b 100644 --- a/docs/formats/README.md +++ b/docs/formats/README.md @@ -19,6 +19,7 @@ Unless a page says otherwise, integer fields are little endian. Legacy strings u | Audio containers | `S/2000` through `S/2003` | [SOUND](SOUND.md) | `src/audio/container.cpp`, `original.cpp` | | Executable data | German LE and English X-32 images | [LE](LE.md), [executable layout](EXECUTABLE_LAYOUT.md) | `src/formats/le.cpp`, `src/launch/fltd.cpp` | | IFF crest template | `WAPPEN.LBM` | [WAPPEN](WAPPEN.md) | Not loaded by OpenBMH | +| OpenBMH world, save and pack (concept) | `*.obw`, `*.obs`, `*.obp`, `*.obt` | [OBW](OBW.md) | Planned for 0.2 | German and English editions can share a physical format while differing in text, league contents, executable layout and currency. Select the edition through the supplied installation; do not rename files or patch a save header to simulate another version. Original English V2.20 save import is a separate compatibility limitation from English installation support.