Accessing Asset Metadata - bryanedds/Nu GitHub Wiki

The Metadata Module

Unlike most everything thing else in Nu, metadata is not accessed via the World API. Instead, it is accessed via the Metadata module, like so -

        override this.GetAttributesInferred (entity, world) =
            match Metadata.tryGetTextureSizeF (entity.GetBorderImage world) with
            | ValueSome size -> AttributesInferred.make size.V3 v3Zero
            | ValueNone -> AttributesInferred.make Constants.Engine.EntitySize2dDefault v3Zero

Attribute inference behavior is often defined in terms of a particular entity's asset's texture size.

For convenience and because it's effectively a static resource, metadata is globally available from the Metadata module.

When a Nu game is started (when the World value is initially constructed), all the metadata for the game's assets is synchronously loaded. This includes information like texture sizes, tile map metadata, model vertices, and any other information needed to drive gameplay, physics, or simulation-side presentation logic. Because metadata loading needs to be as fast as possible (since all metadata is loaded at start-up), information not needed like actual texture color data is not loaded.

The following is a user-relevant snapshot of the current Metadata API -

    /// Get the metadate packages that have been loaded.
    /// NOTE: this is a potentially expensive call as the tree of ConcurrentDictionaries must be copied to avoid
    /// invalidating enumeration in a multi-threaded context.
    /// Thread-safe.
    let getMetadataPackagesLoaded ()

    /// Determine that a given asset's metadata exists.
    /// Thread-safe.
    let getMetadataExists (assetTag : AssetTag)

    /// Attempt to get the file path of the given asset.
    /// Thread-safe.
    let tryGetFilePath (assetTag : AssetTag)

    /// Attempt to get the metadata of the given asset.
    /// Thread-safe.
    let tryGetMetadata (assetTag : AssetTag)

    /// Attempt to get the texture metadata of the given image.
    /// Thread-safe.
    let tryGetTextureMetadata (image : Image AssetTag)

    /// Forcibly get the texture metadata of the given image (throwing on failure).
    /// Thread-safe.
    let getTextureMetadata image

    /// Attempt to get the texture size of the given image.
    /// Thread-safe.
    let tryGetTextureSize (image : Image AssetTag)

    /// Forcibly get the texture size of the given image (throwing on failure).
    /// Thread-safe.
    let getTextureSize image

    /// Attempt to get the texture size of the given image.
    /// Thread-safe.
    let tryGetTextureSizeF image

    /// Forcibly get the texture size of the given image (throwing on failure).
    /// Thread-safe.
    let getTextureSizeF image

    /// Attempt to get the metadata of the given tile map.
    /// Thread-safe.
    let tryGetTileMapMetadata (tileMap : TileMap AssetTag)

    /// Forcibly get the metadata of the given tile map (throwing on failure).
    /// Thread-safe.
    let getTileMapMetadata tileMap

    /// Attempt to get the metadata of the given static model.
    /// Thread-safe.
    let tryGetStaticModelMetadata (staticModel : StaticModel AssetTag)

    /// Forcibly get the metadata of the given static model (throwing on failure).
    /// Thread-safe.
    let getStaticModelMetadata staticModel

    /// Attempt to get the albedo image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelAlbedoImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the roughness image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelRoughnessImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the metallic image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelMetallicImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the ambient occlusion image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelAmbientOcclusionImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the emission image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelEmissionImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the normal image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelNormalImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the height image asset for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelHeightImage materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the two-sided property for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelTwoSided materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the 3d navigation shape for the given material index and static model.
    /// Thread-safe.
    let tryGetStaticModelNavShape materialIndex (staticModel : StaticModel AssetTag)

    /// Attempt to get the metadata of the given animated model.
    /// Thread-safe.
    let tryGetAnimatedModelMetadata (animatedModel : AnimatedModel AssetTag)

    /// Forcibly get the metadata of the given animated model (throwing on failure).
    /// Thread-safe.
    let getAnimatedModelMetadata animatedModel

    /// Attempt to get the albedo image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelAlbedoImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the roughness image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelRoughnessImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the metallic image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelMetallicImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the ambient occlusion image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelAmbientOcclusionImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the emission image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelEmissionImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the normal image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelNormalImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the height image asset for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelHeightImage materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the two-sided property for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelTwoSided materialIndex (animatedModel : AnimatedModel AssetTag)

    /// Attempt to get the 3d navigation shape property for the given material index and animated model.
    /// Thread-safe.
    let tryGetAnimatedModelNavShape materialIndex (animatedModel : AnimatedModel AssetTag)

Though metadata is effectively a static resource, metadata can be reloaded via a call to the Metadata.reloadMetadata function, which is done whenever the user manually reloads assets in Nu's editor, Gaia.