feat: add godotengine.godot-cpp 0.0.1 (import godot_cpp)

[Sunrisepeak]

Stacked on #143, and draft on purpose. This one cannot go green until #143 merges and publish-artifact reruns — see Ordering at the bottom. Based on feat/compat-godot-cpp so the diff shows only this change; GitHub retargets it to main when #143 merges.

What

Registers mcpplibs/godot-cpp-m 0.0.1 as godotengine.godot-cpp — the C++23 module layer over godot-cpp's unchanged API:

import std;
import godot_cpp;

int main() {
    godot::Vector2 v{3, 4};
    std::println("{}", v.length());   // 5 — the same godot-cpp, no #include
}

Form A: the index carries the descriptor, nothing else. The 1022-TU source build stays in compat.godot-cpp (#143) and the module layer lives in its own repo — the same split ffmpeg/opencv use, and what keeps this index from growing a second full godot-cpp build.

Module name

One segment, godot_cpp — matching the library and the #include <godot_cpp/...> root users already type. The dotted spelling is reserved here for packages that expose several submodules (opencv.cv, ffmpeg.av); this one has a single interface unit.

The wrapper is generated, not curated

godot-cpp's public surface is ~1750 names — every engine class, every builtin Variant type, the global enums and their enumerators (so godot::OK and godot::ERR_FILE_NOT_FOUND still spell the same), godot::Math, the templates — and it moves with every Godot release. So src/godot_cpp.cppm is produced by a brace/namespace-aware scan of the headers (tools/gen_module_cppm.py in the package repo) and checked by the compiler.

Two things it deliberately does not carry

Both are upstream's shape, not a wrapper choice:

Macros. GDCLASS, GDREGISTER_CLASS, GDVIRTUAL_*, D_METHOD, memnew/memdelete, the ERR_* family — a named module cannot export macros, and GDExtension code is written in them. The package ships <godot-cpp-m/macros.h> to include next to the import, the same answer ffmpeg-m gives:

#include <godot-cpp-m/macros.h>
import godot_cpp;

class Player : public godot::Node2D {
    GDCLASS(Player, Node2D)
    // ...
};

godot-cpp's headers sit in the module's global module fragment, so both spellings denote the same entities and mixing them is well-formed. The package's own tests/godot_cpp_macros.cpp is exactly this shape.

HashMap/HashSet and their default hashers (7 names). Their inline bodies reach hash_murmur3_one_float/double, which are static and declare an unnamed union in their bodies. An unnamed union type is TU-local, and exposing a TU-local type from a module interface is a hard error — not the -Wexpose-global-module-tu-local warning. Found by bisecting the 1759 exports, not by guessing. They are godot-cpp's internal container plumbing (extension code uses Dictionary/Array/TypedArray) and remain reachable through the headers.

Mirrors

region	url
GLOBAL	github.com/mcpplibs/godot-cpp-m/archive/refs/tags/v0.0.1.tar.gz
CN	gitcode.com/mcpp-res/godot-cpp/releases/download/v0.0.1/godot-cpp-m-0.0.1.tar.gz

sha256 5145f1e539b4b42bdb4064a2df0dcb54ffac4d70f88edc42f38bf2304a37a344, hashed twice from GitHub and re-downloaded from GitCode — byte-identical. The archive carries no symlinks (checked, for the Windows leg).

Test member

tests/examples/godot-cpp-module/ consumes the package the way a user would and asserts the same numbers tests/examples/godot-cpp asserts through headers — that member is the header spelling of this one, so a divergence means the re-export changed behaviour. Both halves can fail: the Variant math is defined in compat.godot-cpp's src/variant/*.cpp (so it only resolves if that dependency linked), and Node/Node2D/Node::PROCESS_MODE_*/godot::OK exist only in the pre-generated gen/ tree.

Verification so far

In the package repo, against compat.godot-cpp resolved from the #143 checkout:

$ mcpp test
godot_cpp_macros ... ok (0.11s)     # GDCLASS + bound method + engine virtual, next to the import
godot_cpp_module ... ok (0.15s)     # the module surface
 test result ok. 2 passed; 0 failed
$ cd examples/summator && mcpp build   # a real GDExtension, kind = "shared"
    Finished dev [unoptimized + debuginfo] in 74.16s
$ nm -D .../libsummator.so | grep summator_library_init
0000000000b228fc T summator_library_init

That example is also what caught compat.godot-cpp missing -fPIC — now fixed in #143.

Lint here is clean (mcpp xpkg parse, mirror table, package name, cross-package refs) and the CN url returns 200.

Ordering

This member declares [indices] godotengine, and a member-level table replaces the root's rather than merging — so the transitive compat.godot-cpp resolves from the published index. That is the constraint tests/examples/ffmpeg-module documents, and it means workspace (*) here stays red until #143 merges and publish-artifact republishes the index.

Simulating a published index locally does not substitute for that: mcpp refreshes the index on a resolution miss and wipes the injected state, so the real gate is CI after the merge.

Design notes: .agents/docs/2026-08-04-add-godot-cpp-plan.md §6.