Different game engines have established user friendly metadata API to optimize the exploitation of what Cesium has been designed to empower users.
Godot for Cesium is a new addition to the family of Cesium values for the worldwide users.
It would be prudent that there are guidelines how:
[1] What are the minimum first stage exposure of Metadata API
which are the minimum API that would allow visualiation in Edit mode (e.g. in Godot)
[2] Which are the next level beyond the basic Metadata API for users to be aware of location, surrounding buildings and their attributes and street etc.
[3] What are the bleeding edge advanced Metadata API that are being developed by more matured game engines e.g. Unreal in exploiting the API
=> We need these guidelines so we can evaluate if the path of Godot for cesium development is on the right track serving Godot communities as was the vision of allocating grant and resources for making Cesium available (urgently) to the Godot communities.
I value any developers from other game engines e.g. Unreal and Unity for sharing your experience.
What should users from Unity and Unreal expect these API in Godot.
Conversion to Variant and Dictionary for engine interoperability; potential overhead and narrowing during float64→float32
Developer ergonomics
Strong separation of concerns, clear source-specific APIs, C#-friendly
Single entry point (TileMetadata) yielding engine-native structures (Dictionary/Variant), GDScript-friendly
Summary: Unity emphasizes modular, source-specific metadata handling with strong typing and performance specialization, while the Godot code prioritizes a unified, engine-native representation via Dictionary/Variant for broad usability.
What the Godot Cesium API exposes
Entry point:
TileMetadata aggregates property tables with init, add_table(const CesiumGltf::PropertyTableView&), and exposes them via get_table(index) returning a Godot Dictionary.
CesiumPropertyInfo holds propertyType, componentType, isArray, and a Variantdata.
Conversion helpers:
get_component_type infers numeric component types using CesiumGltf traits and C++ type traits.
make_vector_type maps glm vectors to Godot Vector2/Vector3/Vector4 or integer vector variants, with error/warning handling for invalid types and narrowing.
make_array_type converts metadata arrays to Godot Array of Variants, preserving element type info in the parent.
make_metadata_value is the central dispatcher, distinguishing arrays, VecN, strings, booleans/scalars via CesiumGltf trait checks, then returning a Ref to CesiumPropertyInfo.
Runtime representation:
Property tables are stored in std::vector<Dictionary> (m_tables) and an overall Dictionary cache (m_accesibleRepresentation), aligning with Godot’s scripting ergonomics.
Where Unity provides more granularity
Feature ID sources:
Unity: Different classes for attributes vs textures vs implicit IDs allow tailored parsing, caching, and late binding per source.
Godot (code shown): No separate abstraction for feature ID sources; all metadata arrives via PropertyTableView and is normalized into Variants.
Property table access and typing:
Unity: Per-property wrappers with type safety and fast paths, avoiding per-access boxing/unboxing.
Godot: Unified Variant-based container simplifies usage, but introduces runtime type checks and potential conversions.
Value conversion layer:
Unity: A dedicated value layer abstracts type coercion, minimizing allocations and branch cost across hot paths.
Godot: Conversion is embedded in templates; warnings are emitted on narrowing (e.g., Float64→Float32), but there’s no separate optimization layer.
Extensibility surface:
Unity: Drop-in extensions for new metadata forms (e.g., new texture encodings) without touching core property accessors.
Godot: To introduce new types (e.g., color types, packed bitfields), you extend EPropertyType/EComponentType and the conversion helpers.
Strengths of the Godot approach
Engine-native ergonomics:
Dictionary/Variant outputs integrate seamlessly with GDScript and Godot’s editor tooling, speeding prototyping and scripting.
Clear vector and array handling:
Explicit mapping to Vector2/Vector3/Vector4 and Array makes common GIS/3D use cases straightforward.
Safety cues during conversion:
ERR_PRINT/WARN_PRINT provide immediate feedback on invalid component mixes and narrowing conversions, aiding debugging.
Gaps relative to Unity and practical enhancements
Missing feature ID source abstraction:
Add interfaces like IFeatureIdSource with concrete implementations for vertex attributes, textures, and implicit IDs.
Benefit: Enables targeted caching, GPU-friendly pathways, and selective refresh.
Dedicated value layer for performance:
Introduce a MetadataValue class encapsulating typed accessors (e.g., as_float64(), as_vec3f(), try_get_enum()) with small-object optimization.
Benefit: Reduces Variant churn and branchy template paths in hot loops.
Per-property wrappers:
Create PropertyTableProperty objects exposing type-safe getters and lazy conversion, keyed by property name.
Benefit: Mirrors Unity’s property-centric ergonomics and aids static analysis.
Matrix support parity:
The enum lists Mat2/Mat3/Mat4, but conversion paths for matrices are not implemented.
Implement glm→Godot matrix mapping or a custom Matrix type for consistent handling.
Enum typing and validation:
Add enum value tables and range validation to avoid silently treating enums as booleans/scalars in mixed cases.
Batch access and caching:
Cache common conversions (e.g., Float64→Float32 vec arrays) per table to avoid repeated per-feature coercions.
Example usage patterns and recommended wrappers
Godot scripting-friendly accessor layer:
Goal: Keep Dictionary/Variant for GDScript while offering typed C++ access for performance-critical paths.
Design:
TileMetadataView: exposes get_table_names(), get_property(name), get_feature_id(source, index) with typed returns.
MetadataCache: memoizes conversions and provides bulk readers (e.g., read_vec3_array(property)).
To bring Godot’s Cesium TileMetadata.h closer to the granular, modular system Unity uses, need to break out responsibilities into specialized classes rather than funneling everything through TileMetadata + CesiumPropertyInfo. Here’s a structured list of changes and additions:
Proposed Class Additions for Granularity
1. Feature ID Sources
FeatureIdAttributeSource
Handles feature IDs embedded in vertex attributes.
Provides GPU‑friendly pathways for instancing/selection.
FeatureIdTextureSource
Manages feature IDs stored in textures.
Supports caching and late binding for texture‑based IDs.
FeatureIdImplicitSource
Provides implicit ID generation when no explicit source exists.
Useful for fallback or procedural tiles.
2. Property Wrappers
PropertyTableProperty
Represents a single property with type‑safe getters.
Proposed Class Additions for Granularity
Structural Changes to TileMetadata.h
Comparison Snapshot
Outcome