open-dragoman 0.2.0__tar.gz

open_dragoman-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+build/
+build-*/
+cmake-build-*/
+out/
+.cache/
+compile_commands.json
+
+*.o
+*.a
+*.so
+*.so.*
+*.dylib
+*.dll
+*.lib
+*.exp
+*.pdb
+
+__pycache__/
+*.egg-info/
+dist/
+.venv/
+
+.DS_Store
+.idea/
+.vscode/
+
+# Maps used for local conformance runs. Neither game's maps belong in this
+# repository -- Open Doctrines' are its own and GD5's are GPL -- so they are
+# pointed at from outside instead. See docs/roundtrip.md.
+maps/
+*.odmap

open_dragoman-0.2.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [semver](https://semver.org/), with a separate ABI version — see
+[docs/versioning.md](docs/versioning.md).
+
+## [0.2.0] — 2026-08-15
+
+Both changes here came from opening converted maps in the games themselves and
+looking at what was wrong.
+
+### Added
+
+- **Sea provinces are invented when the source game does not draw any.** Open
+  Doctrines leaves its oceans unpainted; GD5 can neither render nor sail across
+  what is not a province, so a converted map arrived with a black sea and no
+  fleet could move.
+
+  The water is **grown** into provinces, not cut: seeds are laid on a lattice,
+  displaced by a hash of their own coordinates so the shapes are irregular but
+  a map still converts identically twice, snapped to the nearest water, and
+  grown outwards all at once through water only. Each province is the water
+  nearest one seed, so it follows the coast — 0.56 on bounding-box fill against
+  the 0.66 of GD5's own hand-drawn ones, where a grid would be 1.00. A province
+  cannot cross land, so the Mediterranean and the Atlantic are separate however
+  close two seeds fall.
+
+  The world map gets 917: one network of 747 that is every ocean joined
+  together, and 163 lakes. The ids are recorded in the sidecar and deleted
+  again on the way back, so the round trip is unaffected. New
+  `synthesise_ocean` option, default on.
+
+- **Research is derived from the map's date.** Open Doctrines stores none in a
+  map — its tree is compiled into the game and seeded from a hardcoded list of
+  ISO codes — so converted maps reached GD5 with every nation at level zero in
+  everything. GD5 already knows how to turn a year into research levels, so
+  that rule is applied against the tech tree read out of the GD5 installation
+  being written into, rather than a copy kept here that would go stale. Output
+  matches GD5's own `get_time_appropriate_research` exactly for 1914 and 2000.
+  Nations that arrive with research keep it.
+
+### Fixed
+
+- **Flags now render in GD5.** `flag_data` is not base64 of a PNG, which is
+  what this library was writing; it is base64 of *raw pixel bytes* at exactly
+  60x40, handed to `pygame.image.fromstring`. A PNG makes that raise,
+  `decode_b64_to_surf` swallows the exception, and every nation showed a blank
+  white rectangle. Flags are now decoded, resampled to 60x40 and written as raw
+  pixels, and the original full-size image is preserved in the sidecar so a
+  crossing does not permanently shrink it to GD5's icon size.
+- **One rule for "does this map draw its water"**, shared by both writers,
+  replacing two that disagreed. Deciding it by whether any province is marked
+  sea was wrong in both directions: Open Doctrines maps have a handful of
+  coastal provinces that sit mostly under the mask, so no ocean was ever
+  synthesised, while GD5 maps with lots of unpainted border did not get those
+  borders filled. It is now a pixel count, and the two populations are not
+  close — GD5's maps run 0.35 to 7.8 on the ratio, Open Doctrines' all sit at
+  0.0001.
+
+### Changed
+
+- **ABI version 2.** `dg_options` gained a field, which changes the struct's
+  size, so anything compiled against ABI 1 must be rebuilt. `SOVERSION` moves
+  with it.
+
+## [0.1.0] — 2026-08-15
+
+First release. Converts maps between Open Doctrines `.odmap` archives and
+Greater Diplomacy 5 map directories, in both directions.
+
+### Added
+
+- **Both readers and writers**, against a shared interchange model rather than
+  directly between the two layouts.
+- **Lossless round trips.** Everything the destination format cannot hold is
+  written into a sidecar beside the map — a directory both games ignore — and
+  restored on the way back. `dragoman roundtrip` asserts it; `--no-sidecar`
+  turns it off for a smaller, deliberately lossy conversion.
+- **Derived geometry.** Province adjacency, centroids, coastal flags and the
+  land/sea mask are computed from the province raster, because Open Doctrines
+  derives all of them at load and GD5 requires them stored. The centroid finder
+  handles crescent-shaped provinces, whose mean pixel falls outside themselves.
+- **Script translation** in both directions for the shared subset — a gate and
+  the things that happen when it opens. Constructs outside it are reported by
+  name and carried verbatim. GD5 event types the library does not model pass
+  through unchanged, so GD5 → OD → GD5 is lossless for all of them.
+- **C99 ABI** with a C++ RAII wrapper, a ctypes Python package needing no
+  compiler, and a `dragoman` command line tool.
+- **CI** across Linux, macOS and Windows, building, testing, and importing and
+  exercising the Python binding on each — a symbol that is not exported passes
+  every C++ test and fails at the first `dlsym`.
+- **Version consistency checks**, from inside the build and from a standalone
+  script, over `VERSION`, the C header, the Python package and CMake.
+
+### Verified
+
+Every map both games ship round-trips with no modelled field lost: 28 of 28
+Greater Diplomacy 5 maps (12 base maps, 16 scenarios) and 6 of 6 Open Doctrines
+maps, plus the unit suite. Reproduce with `tools/conformance.py`.
+
+Facts established against the real data, each of which cost a bug first:
+
+- Province ids survive exactly. Open Doctrines packs an id into a pixel
+  big-endian and GD5 little-endian, verified across all 1248 and 2523 provinces
+  of the two games' maps with no exception, so the rasters differ only by
+  swapping red and blue.
+- A GD5 nation's identity is its key in `nation_data`, not its `name` field. The
+  1914 scenario has two separate nations both named "German Empire"; treating
+  the name as the identity merged them and handed 121 provinces to nobody.
+- `UNC` / "Unclaimed" is a real country in both games, not a blank — 104
+  provinces of Open Doctrines' 1914 map belong to it.
+- A nation's claims and a province's cores are different facts in GD5. Merging
+  them invented cores and discarded claims.
+- Open Doctrines does not divide water into provinces at all, so a map crossing
+  to GD5 arrives with nothing to sail on. Reported as `gd5.nosea` rather than
+  passed over in silence.
+
+[0.1.0]: https://github.com/Pr1nted/dragoman/releases/tag/v0.1.0

open_dragoman-0.2.0/CMakeLists.txt

@@ -0,0 +1,170 @@
+cmake_minimum_required(VERSION 3.16)
+
+# The version lives in one file, is read here, and is checked against the C
+# header and the Python package by tests/test_version.cpp and the CI job. A
+# release that forgets one of the three fails before it is tagged.
+file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" DRAGOMAN_VERSION_RAW)
+string(STRIP "${DRAGOMAN_VERSION_RAW}" DRAGOMAN_VERSION_RAW)
+
+project(dragoman VERSION ${DRAGOMAN_VERSION_RAW} LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+option(DRAGOMAN_BUILD_TESTS "Build the test suite" ON)
+option(DRAGOMAN_BUILD_CLI "Build the dragoman command line tool" ON)
+option(DRAGOMAN_BUILD_SHARED "Build a shared library as well as a static one" ON)
+option(DRAGOMAN_WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
+option(DRAGOMAN_PYTHON_WHEEL "Install only the shared library, into the Python package" OFF)
+
+# --------------------------------------------------------------- third party
+#
+# miniz for the zip container and stb for PNG, both taken from the versions
+# Open Doctrines itself builds against, so an archive this library writes is
+# read back by exactly the code that will open it in the game. nlohmann/json
+# is the same single header the game uses. All three are MIT or public domain.
+add_library(dragoman_thirdparty STATIC
+    third_party/miniz/miniz.c
+    third_party/miniz/miniz_tdef.c
+    third_party/miniz/miniz_tinfl.c
+    third_party/miniz/miniz_zip.c
+    third_party/stb/stb_impl.c
+)
+target_include_directories(dragoman_thirdparty PUBLIC
+    "${CMAKE_CURRENT_SOURCE_DIR}/third_party/miniz"
+    "${CMAKE_CURRENT_SOURCE_DIR}/third_party/stb"
+    "${CMAKE_CURRENT_SOURCE_DIR}/third_party/json"
+)
+# nlohmann/json ships as json.hpp; the library includes it by its usual path.
+file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/thirdparty_include/nlohmann")
+configure_file(third_party/json/json.hpp
+               "${CMAKE_CURRENT_BINARY_DIR}/thirdparty_include/nlohmann/json.hpp" COPYONLY)
+target_include_directories(dragoman_thirdparty PUBLIC
+    "${CMAKE_CURRENT_BINARY_DIR}/thirdparty_include")
+
+if(NOT MSVC)
+    target_compile_options(dragoman_thirdparty PRIVATE -w)
+endif()
+
+# ------------------------------------------------------------------- library
+
+set(DRAGOMAN_SOURCES
+    src/Api.cpp
+    src/Common.cpp
+    src/Gd5Map.cpp
+    src/ModelJson.cpp
+    src/OdMap.cpp
+    src/Raster.cpp
+    src/Scripts.cpp
+    src/Support.cpp
+    src/Zip.cpp
+)
+
+add_library(dragoman STATIC ${DRAGOMAN_SOURCES})
+add_library(dragoman::dragoman ALIAS dragoman)
+target_include_directories(dragoman
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+    PRIVATE
+        "${CMAKE_CURRENT_SOURCE_DIR}/src"
+)
+target_link_libraries(dragoman PRIVATE dragoman_thirdparty)
+target_compile_definitions(dragoman PRIVATE DRAGOMAN_BUILDING)
+
+if(MSVC)
+    target_compile_options(dragoman PRIVATE /W4)
+    if(DRAGOMAN_WARNINGS_AS_ERRORS)
+        target_compile_options(dragoman PRIVATE /WX)
+    endif()
+else()
+    target_compile_options(dragoman PRIVATE -Wall -Wextra)
+    if(DRAGOMAN_WARNINGS_AS_ERRORS)
+        target_compile_options(dragoman PRIVATE -Werror)
+    endif()
+endif()
+
+# The shared build is what every non-C binding loads: Python via ctypes, Go
+# via cgo, C# via P/Invoke. It exports the C ABI and nothing else.
+if(DRAGOMAN_BUILD_SHARED)
+    add_library(dragoman_shared SHARED ${DRAGOMAN_SOURCES})
+    set_target_properties(dragoman_shared PROPERTIES
+        OUTPUT_NAME dragoman
+        VERSION ${PROJECT_VERSION}
+        SOVERSION 2                     # the ABI version, not the release
+        C_VISIBILITY_PRESET hidden
+        CXX_VISIBILITY_PRESET hidden
+    )
+    target_include_directories(dragoman_shared
+        PUBLIC
+            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+            $<INSTALL_INTERFACE:include>
+        PRIVATE
+            "${CMAKE_CURRENT_SOURCE_DIR}/src"
+    )
+    target_link_libraries(dragoman_shared PRIVATE dragoman_thirdparty)
+    target_compile_definitions(dragoman_shared PRIVATE DRAGOMAN_BUILDING DRAGOMAN_SHARED)
+
+    # The C++ runtime is linked in statically on Linux. Nothing about this
+    # library's interface is C++ -- it is loaded by ctypes, by cgo, by P/Invoke,
+    # from processes that have no reason to have libstdc++ at the version it was
+    # built against. Carrying it removes the one dependency a caller could not
+    # have predicted from the header.
+    if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+        target_link_options(dragoman_shared PRIVATE -static-libstdc++ -static-libgcc)
+    endif()
+endif()
+
+# ----------------------------------------------------------------------- cli
+
+if(DRAGOMAN_BUILD_CLI)
+    add_executable(dragoman_cli tools/dragoman_cli.cpp)
+    set_target_properties(dragoman_cli PROPERTIES OUTPUT_NAME dragoman)
+    target_link_libraries(dragoman_cli PRIVATE dragoman)
+endif()
+
+# --------------------------------------------------------------------- tests
+
+if(DRAGOMAN_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()
+
+# ------------------------------------------------------------------- install
+
+# Building a Python wheel: the shared library goes *inside* the package, beside
+# __init__.py, which is the first place bindings/python/dragoman/_ffi.py looks.
+# That is what makes `pip install dragoman` a complete install with no compiler
+# and no separate library to find -- the audience for this includes people who
+# install Greater Diplomacy 5 by unzipping it.
+if(DRAGOMAN_PYTHON_WHEEL)
+    if(NOT DRAGOMAN_BUILD_SHARED)
+        message(FATAL_ERROR "DRAGOMAN_PYTHON_WHEEL needs DRAGOMAN_BUILD_SHARED")
+    endif()
+    # COMPONENT is repeated per artifact on purpose. Written once at the end it
+    # binds only to the group it follows, so on Linux and macOS -- where a
+    # shared library is a LIBRARY artifact, not a RUNTIME one -- the .so landed
+    # in the default component and `--install --component python` installed
+    # nothing at all. The wheel built, imported, and had no library in it.
+    install(TARGETS dragoman_shared
+            LIBRARY DESTINATION dragoman COMPONENT python
+            RUNTIME DESTINATION dragoman COMPONENT python)
+    return()   # a wheel wants the library and nothing else -- no headers, no CLI
+endif()
+
+include(GNUInstallDirs)
+install(TARGETS dragoman
+        EXPORT dragomanTargets
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+if(DRAGOMAN_BUILD_SHARED)
+    install(TARGETS dragoman_shared
+            EXPORT dragomanTargets
+            LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+endif()
+if(DRAGOMAN_BUILD_CLI)
+    install(TARGETS dragoman_cli RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+endif()
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

open_dragoman-0.2.0/LICENSE

@@ -0,0 +1,43 @@
+MIT License
+
+Copyright (c) 2026 Dragoman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Dragoman is an independent implementation, written from observing the two file
+formats it converts between. No source code from either game is included in or
+derived into it.
+
+The games themselves remain under their own licences, and neither project's
+maps are redistributed here:
+
+  Open Doctrines        OpenDoctrines Non-Commercial License
+  Greater Diplomacy 5   GNU General Public License v3.0
+                        https://github.com/GitGetGot415/Greater-Diplomacy-5
+
+Vendored third-party code, all permissively licensed:
+
+  third_party/miniz     miniz 11.3.1, MIT
+                        https://github.com/richgel999/miniz
+  third_party/stb       stb_image / stb_image_write, MIT or public domain
+                        https://github.com/nothings/stb
+  third_party/json      nlohmann/json 3.11.3, MIT
+                        https://github.com/nlohmann/json

open_dragoman-0.2.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.2
+Name: open-dragoman
+Version: 0.2.0
+Summary: Translate maps between Open Doctrines and Greater Diplomacy 5
+Keywords: grand-strategy,map,conversion,opendoctrines,greater-diplomacy,modding
+Author: Dragoman contributors
+License: MIT License
+         
+         Copyright (c) 2026 Dragoman contributors
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+         ---
+         
+         Dragoman is an independent implementation, written from observing the two file
+         formats it converts between. No source code from either game is included in or
+         derived into it.
+         
+         The games themselves remain under their own licences, and neither project's
+         maps are redistributed here:
+         
+           Open Doctrines        OpenDoctrines Non-Commercial License
+           Greater Diplomacy 5   GNU General Public License v3.0
+                                 https://github.com/GitGetGot415/Greater-Diplomacy-5
+         
+         Vendored third-party code, all permissively licensed:
+         
+           third_party/miniz     miniz 11.3.1, MIT
+                                 https://github.com/richgel999/miniz
+           third_party/stb       stb_image / stb_image_write, MIT or public domain
+                                 https://github.com/nothings/stb
+           third_party/json      nlohmann/json 3.11.3, MIT
+                                 https://github.com/nlohmann/json
+         
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: File Formats
+Project-URL: Homepage, https://github.com/Pr1nted/dragoman
+Project-URL: Documentation, https://github.com/Pr1nted/dragoman/wiki
+Project-URL: Changelog, https://github.com/Pr1nted/dragoman/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Pr1nted/dragoman/issues
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Dragoman
+
+Translate maps between **Open Doctrines** (`.odmap`) and **Greater Diplomacy 5**
+(map directories), in both directions, losing as little as the two formats
+allow — and nothing at all on a round trip.
+
+A *dragoman* was the interpreter attached to an embassy: the person through
+whom two powers who shared no language could nonetheless sign something. This
+is that, for map files.
+
+```bash
+pip install open-dragoman
+
+dragoman convert 1914.odmap base_maps/1914 --to gd5
+dragoman convert base_maps/GD4 gd4.odmap   --to odmap
+dragoman roundtrip 1914.odmap              # prove nothing was lost
+```
+
+```python
+import dragoman
+
+dragoman.convert("1914.odmap", "base_maps/1914", to="gd5")
+
+world = dragoman.load("1914.odmap")
+print(world.name, len(world.provinces), "provinces")
+```
+
+**[Read the wiki →](https://github.com/Pr1nted/dragoman/wiki)** — what it is,
+how to use it, what every message means, and what it cannot do.
+
+## Status
+
+Every map both games ship round-trips without losing a single modelled field:
+
+| Suite | Result |
+|---|---|
+| Greater Diplomacy 5 maps (12 base maps + 16 scenarios) | **28 / 28** |
+| Open Doctrines maps (5 scenarios + the world map) | **6 / 6** |
+| Unit tests (raster, scripts, ABI, versioning, round trip) | **5 / 5** |
+
+Verified against Open Doctrines and against
+[GitGetGot415/Greater-Diplomacy-5](https://github.com/GitGetGot415/Greater-Diplomacy-5).
+Reproduce with `python3 tools/conformance.py <directory of maps>`.
+
+Converted maps have also been **played in both games**, not merely loaded by
+this library. Open Doctrines' world map converted to GD5 boots through GD5's
+own `Controller` and `Map` state with all 23 screens, its flags drawn, its
+oceans navigable and every province centre inside its own province; a GD5 map
+converted to Open Doctrines plays five AI turns under `OpenDoctrines
+--simulate`. Nearly everything this library gets right, it gets right because
+somebody opened the result in the game and looked at it — the flag encoding,
+the ocean, the political layer's colour key and the province-border fill were
+all found that way.
+
+One thing crossing to Open Doctrines still needs a human: GD5 starts its
+nations with an empty stockpile and Open Doctrines expects a starting
+endowment, so a converted map bankrupts its world on the first turn unless
+treasuries are set. Reported as `od.treasury` rather than guessed at.
+
+## What "lossless" means here
+
+The two games are not the same game, so a straight translation always loses
+something: Open Doctrines models a province's population, its port and its
+ethnic minorities, and GD5 has no field for any of them; GD5 models terrain,
+province adjacency, unit rosters and research, and Open Doctrines has no field
+for those.
+
+Dragoman writes the difference down. Everything the destination cannot hold
+goes into a **sidecar** beside the map — `dragoman_sidecar/` in a GD5
+directory, `dragoman/` inside a `.odmap` archive. Both games read a fixed list
+of filenames and ignore everything else, so the sidecar is invisible to them
+and costs the converted map nothing.
+
+The result:
+
+- **Converting one way** is as faithful as the target format permits, and every
+  approximation is reported by a stable code you can act on.
+- **Converting back** restores what the target could not hold. `A → B → A` keeps
+  every province, nation, relation, claim, core, script and carried file, and
+  the province raster hashes identical.
+
+`dragoman roundtrip <map>` asserts exactly that. Pass `--no-sidecar` for a
+smaller, genuinely lossy conversion — the round trip then fails, on purpose.
+
+Not promised: byte-identical container files. Two zip archives holding
+identical members are different files, because deflate is not reproducible
+across implementations, and Open Doctrines packs with Python's zlib while this
+packs with miniz. Every file *inside* is preserved exactly.
+
+## What crosses
+
+| | Open Doctrines | Greater Diplomacy 5 |
+|---|---|---|
+| Province raster | `provinces.png`, id packed big-endian | `id_map.png`, id packed little-endian |
+| Province identity | preserved exactly — the rasters differ only by swapping red and blue |||
+| Owner, name, claims | ✅ | ✅ |
+| Cores | — | ✅ (carried) |
+| Sea provinces | — (**synthesised** for GD5) | ✅ |
+| Population, ports, fortification | ✅ | — (carried) |
+| Minorities, political compass, policies | ✅ | — (carried) |
+| Terrain, adjacency, province centres | — (**derived** from the raster) | ✅ |
+| Units, buildings, research, factions | — (armies carried) | ✅ |
+| Flags | a PNG in the archive | raw 60x40 pixels, base64 |
+| Relations | ally, non-aggression, guarantee | war and alliance only (rest carried) |
+| Scripts | imperative `#OD/MapEngine/1` | declarative scripted events |
+
+Adjacency and centroids are computed from the province raster when converting
+to GD5, since Open Doctrines derives both at load and never stores them. The
+centroid finder deliberately handles crescent-shaped provinces, whose mean
+pixel falls outside themselves.
+
+Full field-by-field detail: [docs/mapping.md](docs/mapping.md).
+
+## Scripts
+
+Open Doctrines' scripting is imperative and line-based, with loops and
+`waitUntil` suspension points. GD5's is a list of declarative events, each a
+set of conditions and a set of actions. The overlap is the shape both express:
+a gate, and things that happen when it opens.
+
+An Open Doctrines script written as top-level `waitUntil` stages becomes GD5
+events, one stage at a time. A GD5 event becomes an entry script with a
+`waitUntil` and some `set` lines. Anything outside that overlap — a `foreach`
+over a country's provinces, conditions chained with `XOR` — is reported by name
+and carried unchanged rather than half-translated. GD5 event types this library
+has never heard of pass through untouched, so a GD5 → OD → GD5 trip is lossless
+even for conditions added to the game after this was written.
+
+Details and the full vocabulary: [docs/scripting.md](docs/scripting.md).
+
+## Installing
+
+```bash
+pip install open-dragoman
+```
+
+The wheel carries the compiled library inside the package, so there is no
+compiler needed at install time and nothing to locate afterwards. You get both
+the Python API and a `dragoman` command.
+
+Prebuilt binaries for people who want nothing to do with Python are attached to
+each [release](https://github.com/Pr1nted/dragoman/releases). The full set of
+options — release archives, source builds, CMake `FetchContent` — is on
+[the Installing page](https://github.com/Pr1nted/dragoman/wiki/Installing).
+
+## Building from source
+
+Needs CMake 3.16 and a C++17 compiler. There are no external dependencies —
+miniz, stb and nlohmann/json are vendored, all MIT or public domain.
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+This produces `libdragoman.a`, a shared `libdragoman.{so,dylib,dll}`, and the
+`dragoman` command line tool.
+
+## Using it from your language
+
+The core is C++17 behind a flat **C99 ABI**, so anything with an FFI can call
+it. The whole interchange model is available as JSON through
+`dg_world_to_json`, which is how a binding reads or edits a map without needing
+an accessor per field.
+
+- **C** — `#include <dragoman/dragoman.h>`, link `dragoman`. See
+  [bindings/c/example.c](bindings/c/example.c).
+- **C++** — `#include <dragoman/dragoman.hpp>` for an RAII wrapper over the same
+  ABI. See [bindings/cpp/example.cpp](bindings/cpp/example.cpp).
+- **Python** — `pip install open-dragoman`. Pure ctypes, and the wheel carries the
+  library, so no compiler is needed at install time.
+- **Anything else** — Rust, Go, C#, Java, Lua and WebAssembly all bind the same
+  header. [docs/abi.md](docs/abi.md) documents the contract.
+
+## Versioning
+
+Two numbers that move for different reasons:
+
+- **Library version** (`VERSION`, semver) — the release. Currently `0.2.0`.
+- **ABI version** (`DRAGOMAN_ABI_VERSION`) — bumped only when an existing symbol
+  changes meaning, so a binding can refuse to load a library it cannot speak to
+  without parsing semver.
+
+The version lives in `VERSION` and is mirrored into the C header, the Python
+package and the CMake project. `tools/check_version.py` and
+`tests/test_version.cpp` both fail if any copy drifts, and CI runs them on every
+push. Details: [docs/versioning.md](docs/versioning.md).
+
+## Licence
+
+Dragoman is MIT. It is an independent implementation written from observing
+both file formats; no code from either game is copied into it. Open Doctrines
+and Greater Diplomacy 5 remain under their own licences (Open Doctrines
+Non-Commercial, and GPL-3.0 respectively), and neither project's maps are
+redistributed here.