Checking native API changes
API baselines, CLI comparison, method hashes and difference diagnostics.
Use this workflow when changing the native API exposed to ReckfellExtension: method arguments, return types, defaults, properties, signals or enums. It compares an earlier API description with the API registered by the candidate editor. It does not validate C# bindings, project formats or the behavior of a loaded extension.
Keep a trustworthy baseline
Keep the baseline editor and candidate editor in separate locations. Use comparable build options: platform, precision, enabled modules and deprecated bindings affect the exposed API. A dump from a stripped template is not interchangeable with the editor's API.
The public product version is 1.0.0. Record the executable SHA-256 and build configuration alongside each dump: the displayed version alone does not identify two development builds. Do not overwrite a baseline with a dump from the candidate to make a check pass.
Set BASE_EDITOR and NEW_EDITOR to the absolute paths of the two editor command-line executables. Set QA_PROJECT to a small valid Reckfell project, separate from production work. Run the following in a new writable review directory. These shell examples assume those variables are already set:
"$BASE_EDITOR" --headless --xr-mode off --path "$QA_PROJECT" --dump-extension-apiThe output is extension_api.json in the current working directory, not automatically in QA_PROJECT. Preserve it as the baseline before invoking another dump command. Check that the file exists, parses as JSON and contains the expected header and classes. A zero exit from the dump command alone is insufficient: its top-level CLI branch returns success without forwarding the writer's result.
Compare the candidate against that saved file:
"$NEW_EDITOR" --headless --xr-mode off --path "$QA_PROJECT" --validate-extension-api "$PWD/extension_api.json"The validator exits with zero for a successful comparison and nonzero for a rejected comparison or an input error. Save both stdout and stderr. Do not infer a clean audit from the exit code while warnings remain.
Read the result correctly
The input JSON is the earlier contract; the running editor supplies the candidate API. This is a directional check: it asks whether previously described entries remain available. It is not an equality test and does not prove that an intentionally incomplete baseline covers the whole API.
| Diagnostic or change | Meaning and action |
|---|---|
Could not open file / JSON parse error | Fix the path or damaged baseline before discussing compatibility. |
different engine version / newer minor version | The validator rejects a different major or a baseline with a greater minor version. Do not edit the header to evade that check. |
API was removed | A baseline entry is absent in the candidate. Check the registered name and build configuration, then decide whether the removal is intentional. |
Argument count, type, return value or default_value changed | Review the exposed contract and generated consumers. An optional new argument can still change native bindings. |
Hash changed | The earlier method hash is neither current nor registered among compatibility hashes. A comment or edited JSON does not repair that binding. |
| Argument name changed, comparison passes | Argument comparison permits name changes. Recheck source callers and named arguments separately; passing here does not establish source compatibility. |
| No structural differences reported | Run the affected extension and behavioral tests as well. Matching signatures do not verify semantics or memory ownership. |
The installed runtime currently emits 17 warnings of the form Compatibility hash ... mapped to non-existent hash ... while generating its API. They concern stale special compatibility mappings. Self-comparison and the targeted negative cases work, but this warning remains an unresolved native audit issue. Preserve it in the report; do not suppress it or describe the dump as warning-free.
Changing a native method
Check the C++ declaration, ClassDB::bind_method call and generated API together. If an existing Reckfell contract must remain callable, a compatibility binding needs its earlier signature and behavior; delegating to the current implementation is preferable to copying the algorithm. Keep the earlier default values explicitly. A cast that narrows a value or discards a return result requires its own behavioral tests.
The current AStarGrid2D implementation provides a concrete reference:
core/math/a_star_grid_2d.h: current three-argumentget_id_pathandget_point_path, withallow_partial_path = false.core/math/a_star_grid_2d.cpp: public bindings withDEFVAL(false)and inclusion of the adjacent.compat.incfile.core/math/a_star_grid_2d.compat.inc: two-argument adapters forwardfalseand register throughClassDB::bind_compatibility_method.
Those adapters are guarded by DISABLE_DEPRECATED; deprecated=no defines that macro. Test the configuration you intend to ship. Do not add old Entity names, obsolete project formats or a project migrator as part of this process. Native method adapters do not implement format migration.
After changing an API, rebuild the affected engine configuration using the relevant compilation guide, regenerate affected bindings and rebuild consumers. Then compare against the preserved baseline and run a small extension exercising the changed method, defaults, return value and ownership. Update the API documentation and change record. A text file listing allowed differences does not change this CLI validator's result.
For this documentation review, the installed Windows editor created a dump; self-comparison, changed hash/default, renamed argument, absent method, wrong major and missing-file cases were exercised using scratch JSON. No engine was rebuilt or modified, no two-release compatibility claim was established, and no native extension binary was loaded.