Skip to main content

NevermoreCLIManifestUtils

Reads deploy metadata baked into the running place by the nevermore CLI at deploy time.

When a place is deployed via nevermore deploy, the CLI locates this ModuleScript in the built place and writes the deployment metadata (commit, target, timestamp, etc.) as attributes onto it. Because the data lives on the package's own instance it travels with the package and replicates to clients automatically -- consumers like GameConfig, GameVersionUtils or PlayerMetrics can simply require("NevermoreCLIManifestUtils") and call NevermoreCLIManifestUtils.getGameMetadata.

When running in Studio, or in a place that was never deployed through the CLI, no attributes are present and NevermoreCLIManifestUtils.isDeployed returns false. 

local metadata = NevermoreCLIManifestUtils.getGameMetadata()
if metadata.deployed then
	print(string.format("Running %s @ %s (%s)", metadata.target, metadata.commit, metadata.timestamp))
else
	print("Running an undeployed build (Studio)")
end

Types​

GameMetadata​

</>
interface GameMetadata {
deployed: boolean--

true only when injected by a nevermore deploy

commit: string?--

short git commit SHA the build was made from

version: string?--

full git commit SHA the build was made from

branch: string?--

git branch the build was made from

packageVersion: string?--

version from the deploying package's package.json (e.g. "1.0.0")

target: string?--

deploy target name (e.g. "test", "integration")

timestamp: string?--

ISO 8601 UTC timestamp of when the deploy ran

published: boolean?--

true if published live (--publish), false if only Saved

placeId: number?--

Roblox place ID the build was deployed to

universeId: number?--

Roblox universe ID the build was deployed to

}

Metadata describing how and when the running place was deployed. Every field other than deployed is optional -- older CLI versions may not populate all of them, and none are present in an undeployed build.

ManifestPlace​

</>
interface ManifestPlace {
name: string?
placeId: number
universeId: number
}

One place in the deployed target's place table. Deploying a multi-place target (e.g. a game with chapter0..chapterN places) bakes every place's IDs into the running place, so it can resolve a sibling's placeId without hard-coding it -- for example to teleport between chapters.

name is the place name from the deploy target (e.g. "chapter0"); it is absent for single-place targets.

Functions​

getGameMetadata​

</>
NevermoreCLIManifestUtils.getGameMetadata(instance: Instance?) → GameMetadata

Returns a snapshot of the deploy metadata for the running place.

Safe to call on both the client and the server. On the client the metadata replicates with the package, so it is available as soon as the package has replicated. Use NevermoreCLIManifestUtils.observeGameMetadata if you need to react to it becoming available.

instance defaults to the manifest module itself (where the CLI injects the data); pass an instance to parse metadata attributes off somewhere else.

isDeployed​

</>
NevermoreCLIManifestUtils.isDeployed(instance: Instance?) → boolean

Returns true if the running place was deployed through nevermore deploy. Returns false in Studio and in any place that was never deployed via the CLI.

observeGameMetadata​

</>
NevermoreCLIManifestUtils.observeGameMetadata(instance: Instance?) → Observable<GameMetadata>

Observes the deploy metadata, firing immediately with the current snapshot and again whenever any field changes (for example when the metadata first replicates to a client).

getPlaces​

</>
NevermoreCLIManifestUtils.getPlaces(instance: Instance?) → {ManifestPlace}

Returns every place in the deployed target, so a running place can look up a sibling place's placeId (for example to teleport between chapters) without hard-coding IDs. The order matches the deploy target's places list.

Returns an empty list in Studio, in an undeployed build, or if the older CLI that deployed the place did not stamp the place table.

instance defaults to the manifest module itself; pass an instance to parse the place table off somewhere else.

observePlaces​

</>
NevermoreCLIManifestUtils.observePlaces(instance: Instance?) → Observable<{ManifestPlace}>

Observes the deployed target's place table, firing immediately with the current list and again whenever attributes change (for example when the metadata first replicates to a client).

Show raw api
{
    "functions": [
        {
            "name": "getGameMetadata",
            "desc": "Returns a snapshot of the deploy metadata for the running place.\n\nSafe to call on both the client and the server. On the client the metadata\nreplicates with the package, so it is available as soon as the package has\nreplicated. Use [NevermoreCLIManifestUtils.observeGameMetadata] if you need\nto react to it becoming available.\n\n`instance` defaults to the manifest module itself (where the CLI injects the\ndata); pass an instance to parse metadata attributes off somewhere else.",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "GameMetadata"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 180,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        },
        {
            "name": "isDeployed",
            "desc": "Returns true if the running place was deployed through `nevermore deploy`.\nReturns false in Studio and in any place that was never deployed via the CLI.",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 191,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        },
        {
            "name": "observeGameMetadata",
            "desc": "Observes the deploy metadata, firing immediately with the current snapshot\nand again whenever any field changes (for example when the metadata first\nreplicates to a client).",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<GameMetadata>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 203,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        },
        {
            "name": "getPlaces",
            "desc": "Returns every place in the deployed target, so a running place can look up a\nsibling place's `placeId` (for example to teleport between chapters) without\nhard-coding IDs. The order matches the deploy target's `places` list.\n\nReturns an empty list in Studio, in an undeployed build, or if the older CLI\nthat deployed the place did not stamp the place table.\n\n`instance` defaults to the manifest module itself; pass an instance to parse\nthe place table off somewhere else.",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ ManifestPlace }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 231,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        },
        {
            "name": "observePlaces",
            "desc": "Observes the deployed target's place table, firing immediately with the\ncurrent list and again whenever attributes change (for example when the\nmetadata first replicates to a client).",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<{ ManifestPlace }>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 243,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "GameMetadata",
            "desc": "Metadata describing how and when the running place was deployed. Every field\nother than `deployed` is optional -- older CLI versions may not populate all\nof them, and none are present in an undeployed build.",
            "fields": [
                {
                    "name": "deployed",
                    "lua_type": "boolean",
                    "desc": "true only when injected by a `nevermore deploy`"
                },
                {
                    "name": "commit",
                    "lua_type": "string?",
                    "desc": "short git commit SHA the build was made from"
                },
                {
                    "name": "version",
                    "lua_type": "string?",
                    "desc": "full git commit SHA the build was made from"
                },
                {
                    "name": "branch",
                    "lua_type": "string?",
                    "desc": "git branch the build was made from"
                },
                {
                    "name": "packageVersion",
                    "lua_type": "string?",
                    "desc": "`version` from the deploying package's package.json (e.g. \"1.0.0\")"
                },
                {
                    "name": "target",
                    "lua_type": "string?",
                    "desc": "deploy target name (e.g. \"test\", \"integration\")"
                },
                {
                    "name": "timestamp",
                    "lua_type": "string?",
                    "desc": "ISO 8601 UTC timestamp of when the deploy ran"
                },
                {
                    "name": "published",
                    "lua_type": "boolean?",
                    "desc": "true if published live (`--publish`), false if only Saved"
                },
                {
                    "name": "placeId",
                    "lua_type": "number?",
                    "desc": "Roblox place ID the build was deployed to"
                },
                {
                    "name": "universeId",
                    "lua_type": "number?",
                    "desc": "Roblox universe ID the build was deployed to"
                }
            ],
            "source": {
                "line": 56,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        },
        {
            "name": "ManifestPlace",
            "desc": "One place in the deployed target's place table. Deploying a multi-place\ntarget (e.g. a game with `chapter0`..`chapterN` places) bakes every place's\nIDs into the running place, so it can resolve a sibling's `placeId` without\nhard-coding it -- for example to teleport between chapters.\n\n`name` is the place name from the deploy target (e.g. \"chapter0\"); it is\nabsent for single-place targets.",
            "fields": [
                {
                    "name": "name",
                    "lua_type": "string?",
                    "desc": ""
                },
                {
                    "name": "placeId",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "universeId",
                    "lua_type": "number",
                    "desc": ""
                }
            ],
            "source": {
                "line": 84,
                "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
            }
        }
    ],
    "name": "NevermoreCLIManifestUtils",
    "desc": "Reads deploy metadata baked into the running place by the nevermore CLI at\ndeploy time.\n\nWhen a place is deployed via `nevermore deploy`, the CLI locates this\nModuleScript in the built place and writes the deployment metadata (commit,\ntarget, timestamp, etc.) as attributes onto it. Because the data lives on\nthe package's own instance it travels with the package and replicates to\nclients automatically -- consumers like GameConfig, GameVersionUtils or\nPlayerMetrics can simply `require(\"NevermoreCLIManifestUtils\")` and call\n[NevermoreCLIManifestUtils.getGameMetadata].\n\nWhen running in Studio, or in a place that was never deployed through the\nCLI, no attributes are present and [NevermoreCLIManifestUtils.isDeployed]\nreturns false.\n\n```lua\nlocal metadata = NevermoreCLIManifestUtils.getGameMetadata()\nif metadata.deployed then\n\tprint(string.format(\"Running %s @ %s (%s)\", metadata.target, metadata.commit, metadata.timestamp))\nelse\n\tprint(\"Running an undeployed build (Studio)\")\nend\n```",
    "source": {
        "line": 29,
        "path": "src/nevermore-cli-manifest/src/Shared/NevermoreCLIManifestUtils.lua"
    }
}