109 lines
5.6 KiB
Markdown
109 lines
5.6 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"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](schema/1.1/editor-world.json) 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.
|