From faaecf2eb214821e191065dccea339c3158be6d0 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 22 Oct 2026 09:02:10 +0200 Subject: [PATCH] Define competition trophy references and generic fallback (by Codex) --- docs/formats/OBW.md | 28 +++++++++++++++++++ docs/formats/obw/schema/1.0/competitions.json | 5 ++++ src/import/classic.cpp | 1 + src/import/obw.cpp | 15 ++++++++++ tests/obw_import_tests.cpp | 21 ++++++++++++++ 5 files changed, 70 insertions(+) diff --git a/docs/formats/OBW.md b/docs/formats/OBW.md index c62a3cf..093c9d9 100644 --- a/docs/formats/OBW.md +++ b/docs/formats/OBW.md @@ -247,6 +247,7 @@ A competition is an ordered list of **stages**. Each stage takes teams from **sl "type": "league", "nation": "nation:de", "tier": 2, + "trophy": "asset:comp/de-2/trophy", "season_cycle": 1, "stages": [{ "id": "regular", @@ -405,6 +406,30 @@ Data never refers to file paths. It uses logical keys: | `asset:stadium//image` | Stadium picture | | `asset:icon/` | Interface icon | +**Competition trophies.** Every competition type may set the optional string +`trophy` to a logical key `asset:comp//trophy`. The key is stable and opaque; +it may be shared by several competitions, and never embeds a season, localized +name, file path, URL or runtime index. `` is a nonempty sequence of ASCII +letters, digits, `.`, `_` or `-`, excluding `.` and `..`. A competition without +the field uses `asset:comp//trophy`, where the competition key is +its `id` without `comp:`. This also applies to additional foreign leagues and +international competitions; a fixed competition list is not part of the format. + +Resolve that key from active packs by priority, then the world. If unavailable, +resolve `asset:comp/generic/trophy` through the same sources, then use the +client's built-in neutral trophy icon. The generic key is reserved for this +fallback. A missing trophy never prevents a competition from being played. +An invalid explicitly supplied key is an input error, not a request to guess a +file path. File presence is not mandatory because a pack or theme may supply +the image later. Asset-index metadata and rights requirements still apply. +Trophies are presentation only; they do not identify competition rules, stages +or historical winners. + +This optional-field clarification remains compatible with 1.0 worlds: old +documents omit it, older readers ignore it, and no new `requires` feature is +needed. Classic converters emit the conventional per-competition key without +fabricating a trophy image or changing the original local media inventory. + ### 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. @@ -412,6 +437,9 @@ A resolver looks a key up in the active packs by priority (§9.5), then in the w - **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. +- **Trophies:** SVG or PNG/WebP with alpha, preserving the full object and native + aspect ratio. A transparent generic trophy may be provided under the reserved + fallback key. No real trophy artwork is bundled by the format specification. Asset metadata sits next to the files in `assets/index.json`: key, files per size, author, source and licence (required). diff --git a/docs/formats/obw/schema/1.0/competitions.json b/docs/formats/obw/schema/1.0/competitions.json index 2a378fe..2e40087 100644 --- a/docs/formats/obw/schema/1.0/competitions.json +++ b/docs/formats/obw/schema/1.0/competitions.json @@ -127,6 +127,11 @@ "additionalProperties": true }, "minItems": 1 + }, + "trophy": { + "type": "string", + "pattern": "^asset:comp/(?!\\.{1,2}/)[a-zA-Z0-9._-]+/trophy$", + "description": "Optional presentation key; default is asset:comp//trophy. Missing artwork resolves to asset:comp/generic/trophy and then a built-in neutral trophy icon." } }, "required": [ diff --git a/src/import/classic.cpp b/src/import/classic.cpp index d11f012..f23c084 100644 --- a/src/import/classic.cpp +++ b/src/import/classic.cpp @@ -122,6 +122,7 @@ void competitions(Documents& out, const LeImage& exe) { std::string type = cup == 0 ? "cup" : cup >= 1 && cup <= 3 ? "club_international" : cup >= 4 && cup <= 8 ? "national_team" : cup == 10 ? "friendly" : cup == 11 && !english ? "indoor" : "cup"; comps.emplace_back(O{{"id", "comp:classic-cup-" + std::to_string(cup)}, {"name", O{{"default", label}}}, + {"trophy", "asset:comp/classic-cup-" + std::to_string(cup) + "/trophy"}, {"type", type}, {"played", true}, {"stages", std::move(stages)}, {"classic", O{{"competition_id", cup}, {"calendar_bit", cup + 5}, {"qualification", "classic-season-entrants@1"}, {"runtime_participants", true}}}}); diff --git a/src/import/obw.cpp b/src/import/obw.cpp index d31046e..c7a78c2 100644 --- a/src/import/obw.cpp +++ b/src/import/obw.cpp @@ -11,6 +11,7 @@ #include #include #include +#include #include #include "formats/executable_layout.hpp" @@ -338,6 +339,7 @@ Documents convert_database(const Database& db, const TextDb& texts, const LeImag const auto nation = league < 5 ? nation_ids[0] : nation_ids[league - 4]; const int tier = league < 5 ? (english ? int(league + 1) : (league < 3 ? int(league + 1) : int(league))) : 1; competitions.emplace_back(O{{"id", comp_ids[league]}, {"name", localized(label)}, {"type", "league"}, + {"trophy", "asset:comp/" + comp_ids[league].substr(5) + "/trophy"}, {"nation", nation}, {"tier", tier}, {"played", played}, {"stages", A{std::move(stage)}}, {"x-legacy", O{{"league_index", int(league)}, {"calendar_bit", int(bit)}, {"relegation_places", int(exe.u8(layout::CareerSession_InstallLeagueSizes_RuntimeField2 + uint32_t(league)))}, @@ -568,6 +570,19 @@ void validate(const Documents& documents) { } } if (std::string(name) == "competitions") { + // Presentation references may be supplied by a later content pack. + // Missing assets use the documented generic trophy fallback. + if (item.object()->contains("trophy")) { + const auto key = string_field(item, "trophy", at); + constexpr std::string_view prefix = "asset:comp/", suffix = "/trophy"; + if (!key.starts_with(prefix) || !key.ends_with(suffix) || + key.size() <= prefix.size() + suffix.size()) fail(at + ": invalid trophy asset key"); + const auto name = key.substr(prefix.size(), key.size() - prefix.size() - suffix.size()); + if (!std::all_of(name.begin(), name.end(), [](unsigned char c) { + return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || + (c >= '0' && c <= '9') || c == '.' || c == '_' || c == '-'; + }) || name == "." || name == "..") fail(at + ": invalid trophy asset key"); + } const auto* stages = field(item, "stages", at).array(); if (!stages) fail(at + ": stages must be an array"); for (const auto& stage : *stages) { diff --git a/tests/obw_import_tests.cpp b/tests/obw_import_tests.cpp index 3c851e4..9d72c31 100644 --- a/tests/obw_import_tests.cpp +++ b/tests/obw_import_tests.cpp @@ -189,6 +189,27 @@ int main() { check(*f(leagues[3], "tier").integer() == 4, "English fourth tier"); check(!*f(leagues[4], "played").boolean(), "English fifth league is not simulated"); check(!f(leagues[4], "stages").array()->at(0).object()->contains("generator"), "no fabricated ten-team fixture table"); + check(*f(leagues[0], "trophy").string() == "asset:comp/" + + f(leagues[0], "id").string()->substr(5) + "/trophy", "stable default trophy reference"); + const auto with_trophy = [&](const J& value) { + auto copy = documents; + auto competitions = document(copy, "world/competitions.json"); + std::get(competitions.object()->at("items").value)[0].object()->at("trophy") = value; + copy["world/competitions.json"] = cli::dump_json(competitions); + return copy; + }; + // Artwork may be supplied by a future pack, including a shared generic key. + obw::validate(with_trophy(J("asset:comp/generic/trophy"))); + obw::validate(with_trophy(J("asset:comp/future-international_42.v2/trophy"))); + for (const auto& key : {"", "assets/cup.png", "https://example.invalid/cup.png", + "asset:comp//trophy", "asset:comp/../trophy", "asset:comp/a/b/trophy"}) + rejects([&] { obw::validate(with_trophy(J(key))); }, "reject invalid trophy reference"); + rejects([&] { obw::validate(with_trophy(J(12))); }, "reject non-string trophy reference"); + auto no_trophy = documents; + auto old_competitions = document(no_trophy, "world/competitions.json"); + for (auto& row : std::get(old_competitions.object()->at("items").value)) row.object()->erase("trophy"); + no_trophy["world/competitions.json"] = cli::dump_json(old_competitions); + obw::validate(no_trophy); // Existing 1.0 documents retain implicit trophy defaults. check(f(document(english, "world/clubs.json"), "items").array()->size() == 418, "ignore unnamed English slot"); const auto zip = root / "test.obw";