Standard guidelines for exposing Metadata API

3D Tiles for Godot
3

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:

:key: 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.

    • Lazy conversion (only convert when accessed).

    • Mirrors Unity’s CesiumPropertyTablePropertyImpl.

3. Value Layer

  • MetadataValue

    • Encapsulates typed accessors (as_float64(), as_vec3f(), try_get_enum()).

    • Small‑object optimization to reduce Variant churn.

    • Dedicated conversion layer separate from template helpers.

4. Metadata Coordination

  • MetadataCoordinator

    • Centralized manager for multiple property tables.

    • Provides unified API for querying properties across tables.

    • Similar to Unity’s CesiumMetadataImpl.

5. Utility Functions

  • MetadataUtility

    • Static helpers for parsing, validation, and conversion.

    • Enum range validation, matrix mapping, color type handling.

    • Equivalent to Unity’s CesiumFeaturesMetadataUtility.

6. Matrix & Enum Support

  • MatrixPropertyHandler

    • Implements conversion paths for Mat2/Mat3/Mat4.

    • Maps glm matrices to Godot Matrix types.

  • EnumPropertyHandler

    • Stores enum tables and validates ranges.

    • Prevents silent coercion into scalars/booleans.

:hammer_and_wrench: Structural Changes to TileMetadata.h

  • Refactor TileMetadata into a facade:

    • Delegates to specialized classes (FeatureIdSource, PropertyTableProperty, MetadataValue).

    • Keeps Dictionary/Variant outputs for GDScript ergonomics.

  • Introduce caching layer:

    • Preconvert common types (e.g., Float64→Float32 vec arrays).

    • Avoid repeated coercions in hot loops.

  • Add accessor API:

    • get_property(name) → returns PropertyTableProperty.

    • get_feature_id(source, index) → dispatches to correct FeatureIdSource.

:bar_chart: Comparison Snapshot

Unity Granular System Godot Current Proposed Godot Additions
CesiumFeatureIdAttributeImpl None FeatureIdAttributeSource
CesiumFeatureIdTextureImpl None FeatureIdTextureSource
CesiumPropertyTablePropertyImpl CesiumPropertyInfo PropertyTableProperty
CesiumMetadataImpl TileMetadata MetadataCoordinator
CesiumMetadataValueImpl Template helpers MetadataValue
CesiumFeaturesMetadataUtility Inline templates MetadataUtility

:bullseye: Outcome

By modularizing into these classes:

  • Granularity: Each metadata source/type is handled independently.

  • Performance: Typed accessors and caching reduce Variant overhead.

  • Extensibility: New metadata forms (colors, packed bitfields, GPU pathways) can be added without touching core.

  • Developer ergonomics: Typed wrappers for C++ performance, Dictionary/Variant for GDScript prototyping.