Files
Dreierpack-Manager/docs/formats/obw/editor-v1.md
T

5.6 KiB
Raw Blame History

OBW 1.1 editor-world-v1

This additive profile is a native editing interchange. It does not change classic-installation-v1, its seals, the Classic runtime or save files.

Identification

{
  "format": "openbmh-world",
  "format_version": "1.1",
  "min_reader": "1.1",
  "kind": "world",
  "title": {"default": "My world"},
  "start_date": "2026-07-01",
  "currency": {"code": "EUR", "minor_units": 2},
  "requires": ["editor:world-v1"],
  "extensions": [{"id": "x-editor", "version": "1"}],
  "x-editor": {"profile": "editor-world-v1", "playable": false}
}

The required editor capability is deliberately different from runtime:classic-v1. An edited world must not be resealed as a Classic world. On import the editor keeps the original manifest under x-editor.original_manifest, leaves compatibility/source regions intact, and requires Save As. An original Classic seal is historical evidence only in this profile. The existing Classic reader/validator is not broadened to accept it.

Tables and values

The existing world/*.json and assets/index.json structure remains. Each table is an object with schema and items. Stable id identifiers (asset key) are references, never array positions. Existing identifiers and unknown fields are preserved. New identifiers have a namespace and opaque suffix.

The editor adds explicit club competition, competition members (club IDs), and player squad_order. These are the editable projections of Classic league slots/squad rows. Moving a club updates league membership in the same transaction. The historical Classic slots stay source evidence; a future playable format adapter must choose and implement its own generation rules.

Player born can be null; an imported age_at_start object remains an age, not an invented birth date. team: null is an unassigned projection; an x-editor.membership_unresolved or membership_unassigned marker distinguishes missing/contradictory source facts from a verified free agent. Reported nationalities and sporting eligibility remain separate. No full roster is cut down to the 24 rows of a Classic compatibility view.

Attribute sets declare their actual numeric ranges in world/rules.json: type: "attribute_set", optional attribute_set alias, and fields mapping attribute names to {min,max,...}. The Classic importer declares strength 0–99, form/condition/technique/bonus 0–127, skills 0–3. An FC set remains a separate 0–99 system. Missing values are null/absent; unrated@1 with empty attributes does not invent a rating.

Competition trophy and optional fallback remain logical asset references; images are indexed just like crests and portraits. Arbitrary new competitions can use their own trophy or a package-supplied generic trophy.

Sources, conflicts and images

  • x-source/ can contain unchanged or losslessly gzipped normalized source tables, input hashes, source-to-projection identifiers and identity evidence. References include package-local file paths and JSON pointers. Sources do not become authoritative merely by being present.
  • x-editor/review.json has items with id, reason, resolved, optional table, entity, field (JSON pointer), and alternatives with value and source descriptions. Choosing a value updates its target plus the review record in one undoable transaction. Original alternatives remain.
  • Raster and SVG sources are stored unchanged. Identity imports preserve exact bytes. Edits use a normalized recipe: angle degrees, flip_x, flip_y, crop: {x,y,width,height}. Mirroring precedes clockwise rotation; rotation expands the canvas; crop coordinates refer to that expanded canvas. Values are finite, crop dimensions positive and inside [0,1]. JSON floating-point values must survive round trips.
  • An edited asset's x-editor stores original, original_sha256 and transform. Originals live in x-editor/originals/, rendered files in assets/edited/, addressed by SHA-256. Raster edits are PNG with transparent expanded edges, SVG edits remain vectors. Import does not upscale portraits. Referenced external SVG resources are refused. Originals and source recipes remain available on re-edit; no repeated destructive resampling is needed.
  • Portrait part sets and frozen appearance recipes remain valid. The editor composes those layers for display; a rename never regenerates the recipe.

Container, validation and saving

ZIP/ZIP64, stored or deflated entries; UTF-8 JSON; package-local paths without absolute paths, .., backslashes or symlinks. The editor limits are 100,000 entries, 64 MiB per uncompressed entry and 2 GiB total uncompressed bytes. This is independent of the smaller Classic 1.0 reader limits.

The editor checks identifier uniqueness, typed references, valid dates, declared attribute ranges and assets. Missing facts/source questions are warnings; structural errors block saving. A transaction either validates and commits or is rolled back. revision increases monotonically, including undo/redo. Undoing to the saved state clears the dirty flag.

Unknown entries, extensions, binary assets and untouched table bytes are retained. Large assets remain lazily read from an immutable source snapshot. Saving streams a temporary ZIP and atomically replaces the destination only after finalization. Modified-on-disk sources require Save As. The editor never writes legacy files or a running save.

The 1.1 editor schema documents structural constraints. Runtime validation additionally resolves cross-table references and rule-declared scales. This is not a claim that the generic world can yet be played by a game engine.