Generated API and Metadata

This document explains the engine code-generation and metadata-registration flow. Use it when changing generated source, metadata annotations, property definitions, or script-visible API contracts.

Ownership model

The engine owns the reusable metadata/codegen machinery. An embedding project supplies project configuration, extra metadata sources, common headers, and script/content inputs through CMake options and project files.

Generated files are build artifacts. Document the source annotations, templates, generator inputs, and validation flow; do not treat generated output as hand-authored engine source.

Source paths inspected

• BuildTools/cmake/stages/Codegen.cmake
• BuildTools/cmake/stages/EngineSources.cmake
• BuildTools/cmake/helpers/Build.cmake
• BuildTools/cmake/helpers/State.cmake
• BuildTools/codegen.py
• Source/Common/MetadataRegistration.h
• Source/Common/MetadataRegistration.cpp
• Source/Common/MetadataRegistration-Template.cpp
• Source/Common/GenericCode-Template.cpp
• Source/Common/Properties.h
• Source/Common/Properties.cpp
• Source/Common/Entity.h
• Source/Common/Entity.cpp
• Source/Tools/MetadataBaker.h
• Source/Tools/MetadataBaker.cpp
• Source/Tests/Test_EngineMetadata.cpp
• Source/Tests/Test_MetadataBaker.cpp
• Source/Tests/Test_Properties.cpp
• PUBLIC_API.md

CMake codegen stage

BuildTools/cmake/stages/Codegen.cmake constructs the generator command and output list.

Important command arguments include:

• -maincfg — embedding project’s main config (FO_MAIN_CONFIG).
• -buildhash — current build hash.
• -genoutput — generated output directory, currently GeneratedSource under the CMake binary dir.
• -devname / -nicename — project identity values.
• -embedded — embedded data capacity (FO_EMBEDDED_DATA_CAPACITY).
• -internalcfg — internal config capacity (FO_INTERNAL_CONFIG_CAPACITY).
• -meta — metadata source entries from FO_SOURCE_META_FILES and FO_MONO_SOURCE.
• -commonheader — extra common headers from FO_ADDED_COMMON_HEADERS.

The stage creates normal and forced code-generation command targets and appends CodeGeneration to FO_GEN_DEPENDENCIES.

Generated outputs

Codegen.cmake declares generated outputs under GeneratedSource/, including:

• CodeGenTouch
• Version-Include.h
• EmbeddedResources-Include.h
• InternalConfig-Include.h
• MetadataRegistration-Server.cpp
• MetadataRegistration-Client.cpp
• MetadataRegistration-Mapper.cpp
• MetadataRegistration-ServerStub.cpp
• MetadataRegistration-ClientStub.cpp
• MetadataRegistration-MapperStub.cpp
• GenericCode-Common.cpp

These file names are useful for understanding build flow, but changes should usually be made in templates, annotations, metadata sources, or generator scripts rather than in generated output.

Metadata registration entry points

Hand-authored declarations live in Source/Common/MetadataRegistration.h:

• RegisterServerMetadata()
• RegisterClientMetadata()
• RegisterMapperMetadata()
• RegisterServerStubMetadata()
• RegisterClientStubMetadata()
• RegisterMapperStubMetadata()
• RegisterDynamicMetadata()
• ReadMetadataBin()

Source/Common/MetadataRegistration-Template.cpp is the template used to generate side-specific registration files. It contains code-generation markers such as ///@ CodeGen RegisterHelpers and ///@ CodeGen Register.

Source/Common/GenericCode-Template.cpp is the template for generated common code.

Dynamic metadata

Source/Common/MetadataRegistration.cpp implements RegisterDynamicMetadata(). It reads binary metadata sections and dispatches them into typed registration steps such as:

• enums
• entities
• entity holders
• fixed/value/reference types
• properties
• events
• remote calls
• settings
• migration rules

This is the runtime side of metadata that can be loaded from generated/baked data rather than compiled static registration alone.

Properties and generated contracts

Source/Common/Properties.h and Source/Common/Properties.cpp define the property runtime model used by entities and metadata. Key concepts include:

• PropertyRawData
• Property
• PropertyRegistrator
• Properties
• property getter/setter/post-set callbacks
• base type, struct layout, and serialization-related descriptors

When property metadata changes, inspect both the property runtime and the generator inputs/templates. Script-visible nullability or API changes should also update Scripting.md, ScriptMethodsMap.md, and Nullability.md as applicable.

Public API relationship

../PUBLIC_API.md documents public build/API knobs such as build toggles and project helper functions like resource/package additions. Keep public API docs high-level and stable; put generator internals here.

Metadata and baker relationship

Metadata generation and metadata baking are related but not identical:

• Codegen produces generated C++/include files used by compiled targets.
• MetadataBaker participates in resource baking and can produce metadata data for runtime loading.
• RegisterDynamicMetadata() consumes metadata binary data from resources.

For resource baking details, see BakingPipeline.md.

Tests to inspect

Relevant tests include:

• Source/Tests/Test_EngineMetadata.cpp
• Source/Tests/Test_MetadataBaker.cpp
• Source/Tests/Test_Properties.cpp
• Baker/codegen-adjacent tests such as Test_BakerSetup.cpp and the specific baker tests when metadata affects baked resources.

If a generated script API change is involved, inspect AngelScript-related tests as well.

Change routing

• CMake generator arguments/output list: BuildTools/cmake/stages/Codegen.cmake.
• Generator script behavior: BuildTools/codegen.py.
• Static metadata registration template: Source/Common/MetadataRegistration-Template.cpp.
• Generated common code template: Source/Common/GenericCode-Template.cpp.
• Runtime dynamic metadata reader/registrar: Source/Common/MetadataRegistration.cpp.
• Property model: Source/Common/Properties.* and entity/prototype metadata code.
• Metadata resource baking: Source/Tools/MetadataBaker.* and BakingPipeline.md.
• Script runtime and script-visible signatures: Scripting.md, ScriptMethodsMap.md, and Nullability.md.

Validation checklist

1. Configure from an embedding project root so project metadata sources are available.
2. Run normal code generation and verify generated files are updated as expected.
3. Run forced code generation when generator caching/dependency behavior changes.
4. Build the smallest target that compiles the generated files.
5. Run metadata/property tests relevant to the change.
6. If metadata is baked, run the relevant baker test and bake target.
7. Update docs that expose changed public contracts, especially Scripting.md, ScriptMethodsMap.md, Nullability.md, and ../PUBLIC_API.md when applicable.