Normative. A change that breaks a rule here needs an ADR first (adr/).
Rules
| # | Rule |
| B1 | Vendored files (test/vendored_files.txt) are never edited here. A fix goes to OpenCoD2-Plus Server first and comes back with git am (../development/vendored.md). |
| B2 | The engine and OpenCoD2-Plus Server never call each other directly: every crossing goes through the bridge in src/compat. |
| B3 | Every bridge crossing is type-checked: return types are decltype of OpenCoD2-Plus Server's declarations; the server and client_server modules are also checked against the engine's ABI (test/server_abi.txt, test/client_server_abi.txt, the engine side's 1.3 ABI, kept by hand; format in scripts/engine_abi.py). No crossing function is regparm. |
| B4 | One copy of each state per executable. Engine sources whose state OpenCoD2-Plus Server also holds are listed in test/plus_replaces.txt and left out of the dedicated server; scripts/check_single_impl.py enforces it. |
| B5 | No C name defined by both sides in one target; scripts/check_duplicates.py enforces it (MinGW links with --allow-multiple-definition, so a duplicate would win silently). |
| B6 | The engine's bgame globals that OpenCoD2-Plus Server's bgame also defines carry the eng_ prefix (test/engine_bgame_names.txt, scripts/bgame_names.py); bg_itemlist, bg_numItems, scr_const stay shared. |
| B7 | Shared structure layouts are pinned (COD2_ASSERT_FIELD, COD2_ASSERT_SIZE) and compared with OpenCoD2-Plus Server's (scripts/layout_parity.py, test/layout_parity_types.txt). |
| B8 | Engine extern declarations must match their definitions (scripts/check_c_decls.py, allowlist test/c_decls_allowlist.txt, which may only shrink). |
| B9 | Behavior follows the original 1.3 binaries; a fix cites the original's address when it was checked against it (../development/validation.md). |
| B10 | The data blobs keep the original binary's globals; a global that OpenCoD2-Plus Server defines is guarded out of the blobs (COD2_PLUS_SERVER, COD2_PLUS_GAME, COD2_PLUS_CM) in src/blobs/bss.c and the generated build/native_gen/data32.c, build/win_gen/data.win.S and literals.win.S. The VM's globals, which every build takes from it, are not in the blobs at all. MinGW builds one executable per configuration, so the client's blobs take COD2_PLUS_GAME and COD2_PLUS_CM as global definitions. |
Dependency matrix
| From \ To | Engine | Bridge | OpenCoD2-Plus Server | Blobs |
| Engine (src/PC) | yes | yes (exports) | no | yes |
| Bridge (src/compat) | yes (C names) | yes | yes (C++ names) | yes |
| OpenCoD2-Plus Server | no | yes (imports) | yes | no |
| Blobs | imp_ pointers only | no | no | yes |
Bridge modules
| Module | Generated files | Interface list | Used by |
| script | script_exports.cpp, script_imports.cpp (+ script_game_imports.cpp, script_core_imports.cpp for executables without OpenCoD2-Plus Server's game/core) | test/script_interface.txt | every Linux/MinGW executable |
| server | server_exports.cpp, server_imports.cpp | test/server_interface.txt, test/server_fatal.txt | dedicated server |
| client_server | client_server_exports.cpp, client_server_imports.cpp | test/client_server_interface.txt | client |
Hand-written parts: *_missing.cpp (what one side lacks), server_data.cpp, server_bgame_names.cpp, *_decls.h.
Accepted exceptions
| Exception | Why | Where decided |
| On the MSVC ABI, C and C++ globals are joined by /alternatename aliases generated at link (cmake/msvc_data_aliases.cmake) | the MSVC ABI mangles C++ variables, Itanium does not; functions still cross only through the bridge | ADR 0015 |
| The client keeps the engine's bgame for cgame (prediction) next to OpenCoD2-Plus Server's for the local server | cgame reaches its state through bgs; OpenCoD2-Plus Server uses level_bgs and another animation_s | client.md |
| Functions only code the dedicated server never runs needs, which OpenCoD2-Plus Server lacks, stop the server with their name (test/server_fatal.txt) | linked for symbols, never called | server.md |
| The engine's cl_plusid_mp.c includes OpenCoD2-Plus Server's src/libcod/plusid.hpp and links its Mbed TLS (cod2_plus_mbedtls) | the header is inline, includes no engine headers and calls no server symbol, so the proof the client signs is the one the server checks | ADR 0019 |
Forbidden
- Editing a vendored file in place.
- Calling a OpenCoD2-Plus Server C++ symbol from engine code without a bridge entry.
- Adding an entry to an allowlist (test/c_decls_allowlist.txt, test/c_linkage_allowlist.txt) to silence a real mismatch.