Skip to main content

GameVersionUtils

Utility functions to automatically detect the version a game is running at.

Beyond the place version, this reads the deploy metadata baked in by the nevermore CLI (see NevermoreCLIManifestUtils) so diagnostics can report which environment and commit a build came from: 

print(GameVersionUtils.getVersionString())
--> 1.0.0 · integration · a4a79e8 · v312                        (deployed from main)
--> 1.0.0 · integration · users/quenty/thing · a4a79e8 · v312   (deployed from a branch)
--> studio                                                      (never deployed)
--> undeployed · v312                                           (published outside the CLI)

Types​

ServerType​

</>
type ServerType = "standard" | "vip" | "reserved"

The server type to return

GameVersionStringConfig​

</>
interface GameVersionStringConfig {
separator: string?--

between fields, defaults to " · "

placeVersionPrefix: string?--

before a numeric place version, defaults to "v"

undeployedLabel: string?--

for a live place with no manifest, defaults to "undeployed"

unknownTargetLabel: string?--

for a deploy that did not record its target, defaults to "unknown"

defaultBranches: {[string]: boolean}?--

branches not worth reporting, defaults to main and master

}

How GameVersionUtils.formatVersionString renders a build. Every field is optional and falls back to the default below, so a caller that only wants a different separator passes only that.

defaultBranches are the branches every build is expected to come from -- the branch is only worth reporting when a build came from somewhere else.

Functions​

getBuild​

</>
GameVersionUtils.getBuild() → string

Gets the game build

getBuildWithServerType​

</>
GameVersionUtils.getBuildWithServerType() → string

Gets the game build with a server type specified for debugging

getServerType​

</>
GameVersionUtils.getServerType() → ServerType

Gets a string label for the current server type

isVIPServer​

</>
GameVersionUtils.isVIPServer() → boolean

Returns true if we're a VIP server

getEnvironmentName​

</>
GameVersionUtils.getEnvironmentName() → string?

Gets the deploy target the running place was deployed to, for example "integration" or "production-demo". This is the target name from the deploying package's deploy.nevermore.json.

Returns nil in Studio and in any place that was not deployed through the nevermore CLI, so callers can degrade to whatever they showed before rather than inventing an environment name.

observeEnvironmentName​

</>
GameVersionUtils.observeEnvironmentName() → Observable<string?>

Observes the deploy target, firing immediately and again if the metadata changes. On the client the metadata arrives with replication, so the first value may be nil before it lands.

formatVersionString​

</>
GameVersionUtils.formatVersionString(
metadata: GameMetadata,
build: string,--

as returned by GameVersionUtils.getBuild

) → string

Formats a human readable version string out of deploy metadata and a build.

Fields are emitted from most to least stable -- package version, environment, branch, commit, then the place version -- and any field that is not known is dropped rather than printed as a placeholder.

The branch is only included when the build came from something other than main or master, which is exactly the case where the environment alone does not tell you what is running.

getVersionString​

</>
GameVersionUtils.getVersionString(config: GameVersionStringConfig?) → string

Gets the version string for the running place. See GameVersionUtils.formatVersionString for the format.

Safe on both the client and the server, but on the client the deploy metadata replicates with the package, so prefer GameVersionUtils.observeVersionString for anything shown at boot.

observeVersionString​

</>
GameVersionUtils.observeVersionString(config: GameVersionStringConfig?) → Observable<string>

Observes the version string, firing immediately and again whenever the deploy metadata or the place version changes.

Show raw api
{
    "functions": [
        {
            "name": "getBuild",
            "desc": "Gets the game build",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 99,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "getBuildWithServerType",
            "desc": "Gets the game build with a server type specified for debugging",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 111,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "getServerType",
            "desc": "Gets a string label for the current server type",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ServerType"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 119,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "isVIPServer",
            "desc": "Returns true if we're a VIP server",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 135,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "getEnvironmentName",
            "desc": "Gets the deploy target the running place was deployed to, for example\n\"integration\" or \"production-demo\". This is the target name from the\ndeploying package's `deploy.nevermore.json`.\n\nReturns nil in Studio and in any place that was not deployed through the\nnevermore CLI, so callers can degrade to whatever they showed before rather\nthan inventing an environment name.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 150,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "observeEnvironmentName",
            "desc": "Observes the deploy target, firing immediately and again if the metadata\nchanges. On the client the metadata arrives with replication, so the first\nvalue may be nil before it lands.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<string?>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 166,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "formatVersionString",
            "desc": "Formats a human readable version string out of deploy metadata and a build.\n\nFields are emitted from most to least stable -- package version,\nenvironment, branch, commit, then the place version -- and any field that is\nnot known is dropped rather than printed as a placeholder.\n\nThe branch is only included when the build came from something other than\n`main` or `master`, which is exactly the case where the environment alone\ndoes not tell you what is running.",
            "params": [
                {
                    "name": "metadata",
                    "desc": "",
                    "lua_type": "GameMetadata"
                },
                {
                    "name": "build",
                    "desc": "as returned by [GameVersionUtils.getBuild]",
                    "lua_type": "string"
                },
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "GameVersionStringConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 195,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "getVersionString",
            "desc": "Gets the version string for the running place. See\n[GameVersionUtils.formatVersionString] for the format.\n\nSafe on both the client and the server, but on the client the deploy\nmetadata replicates with the package, so prefer\n[GameVersionUtils.observeVersionString] for anything shown at boot.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "GameVersionStringConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 249,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "observeVersionString",
            "desc": "Observes the version string, firing immediately and again whenever the\ndeploy metadata or the place version changes.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "GameVersionStringConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<string>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 264,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "ServerType",
            "desc": "The server type to return",
            "lua_type": "\"standard\" | \"vip\" | \"reserved\"",
            "source": {
                "line": 36,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        },
        {
            "name": "GameVersionStringConfig",
            "desc": "How [GameVersionUtils.formatVersionString] renders a build. Every field is\noptional and falls back to the default below, so a caller that only wants a\ndifferent separator passes only that.\n\n`defaultBranches` are the branches every build is expected to come from --\nthe branch is only worth reporting when a build came from somewhere else.",
            "fields": [
                {
                    "name": "separator",
                    "lua_type": "string?",
                    "desc": "between fields, defaults to \" · \""
                },
                {
                    "name": "placeVersionPrefix",
                    "lua_type": "string?",
                    "desc": "before a numeric place version, defaults to \"v\""
                },
                {
                    "name": "undeployedLabel",
                    "lua_type": "string?",
                    "desc": "for a live place with no manifest, defaults to \"undeployed\""
                },
                {
                    "name": "unknownTargetLabel",
                    "lua_type": "string?",
                    "desc": "for a deploy that did not record its target, defaults to \"unknown\""
                },
                {
                    "name": "defaultBranches",
                    "lua_type": "{ [string]: boolean }?",
                    "desc": "branches not worth reporting, defaults to main and master"
                }
            ],
            "source": {
                "line": 54,
                "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
            }
        }
    ],
    "name": "GameVersionUtils",
    "desc": "Utility functions to automatically detect the version a game is running at.\n\nBeyond the place version, this reads the deploy metadata baked in by the\nnevermore CLI (see [NevermoreCLIManifestUtils]) so diagnostics can report\nwhich environment and commit a build came from:\n\n```lua\nprint(GameVersionUtils.getVersionString())\n--> 1.0.0 · integration · a4a79e8 · v312                        (deployed from main)\n--> 1.0.0 · integration · users/quenty/thing · a4a79e8 · v312   (deployed from a branch)\n--> studio                                                      (never deployed)\n--> undeployed · v312                                           (published outside the CLI)\n```",
    "source": {
        "line": 19,
        "path": "src/gameversionutils/src/Shared/GameVersionUtils.lua"
    }
}