Skip to content

Environment

In this reference, the environment section specifically refers to the script/system environment that your program is being run on. Examples could include the current line number in the nvgt script being compiled, the operating system being run on or fetching the value of a shell environment variable.

Constants

NVGT Version

These constants describe the version of NVGT that is running your script, or that was used to compile your game. They are set when NVGT itself is built.

The individual number constants are useful for checking whether a script is running on a new enough version of NVGT, for example if (NVGT_VERSION_MAJOR == 0 && NVGT_VERSION_MINOR < 90) alert("Error", "Please update NVGT.");.

Not to be confused with SCRIPT_BUILD_TIME, which gives the time your own script was compiled.

Enums

ARCHITECTURE

This is a list of possible values of the PROCESSOR_ARCHITECTURE property. Many of these exist for completeness, since NVGT itself is only built for a few of these architectures.

OPERATING_SYSTEM

This is a list of possible values of the OS property. Many of these exist for completeness, since NVGT itself only runs on a few of these systems.

system_power_state

This is a list of possible values returned from the system_power_info() function.

Functions

chdir

Change the current working directory.

bool chdir(const string&in new_directory);

Arguments:

Returns:

bool: true if NVGT could set the current working directory to the specified directory; false otherwise.

Example:

void main() {
	string directory = input_box("Chdir Test", "Enter a valid path to a directory: ");
	// Could we switch to it?
	if (chdir (directory))
		alert("Success", "That directory is valid and could be switch to.");
	else 
		alert("Failure", "The directory could not be switched to. Check that you have typed the name correctly and that the directory exists.");
}

cwdir

Check the current working directory.

string cwdir();

Returns:

string: a string containing the current working directory.

Example:

void main() {
	alert("Current Working Directory is", cwdir());
}

environment_variable_exists

Check if the given environment variable exists.

bool environment_variable_exists(const string&in name);

Arguments:

Returns:

bool: true if the specified environment variable exists, false otherwise.

Example:

void main() {
	bool exists = environment_variable_exists("PATH");
	if (exists)
		alert("Info", "The PATH variable exists.");
	else
		alert("Info", "The PATH variable does not exist.");
}

expand_environment_variables

Expand environment variables.

string expand_environment_variables(const string&in variables);

Arguments:

Returns:

string: the expanded environment variable(s) if successful or an empty string if not.

Example:

void main() {
	// The end goal here is to obtain the user's home directory on the running system if possible. This logic happens in a below function; here we just display the result.
	alert("Result", get_home_directory());
}
string get_home_directory() {
	if (system_is_windows) return expand_environment_variables("%USERPROFILE%");
	else if (system_is_unix) return expand_environment_variables("$HOME");
	else return "Unknown";
}

get_preferred_locales

Get a list of the user's preferred locales.

string[]@ get_preferred_locales();

Returns:

string[]@: a handle to an array containing the locale names (as strings).

Example:

void main() {
	string[]@ locales = get_preferred_locales();
	string result; // To be shown to the user.
	for (uint i = 0; i < locales.length(); i++)
		result += locales[i] + ",\n";
	// Strip off the trailing comma and new line.
	result.trim_whitespace_right_this();
	result.erase(result.length() - 1);
	alert("Info", "The locales on your system are: " + result);
}

system_power_info

Determine the state of the system's battery.

system_power_state system_power_info(int&out seconds = void, int&out percent = void);

Arguments:

Returns:

system_power_state: One of the system_power_state constants.

Remarks:

This could be useful for various reasons, such as backing up game data on low battery or showing extra mercy to online game players who run out of battery power who you might otherwise punish/tag for unlawful disconnection.

If the battery percentage or time remaining cannot be determined, that value will be set to -1.

Whether a time or percentage is available is up to the underlying operating system.

Example:

// Utility function to convert a system_power_state to a string.
string describe_power_state(system_power_state st) {
	switch (st) {
		case POWER_STATE_ERROR: return "error";
		case POWER_STATE_ON_BATTERY: return "on battery";
		case POWER_STATE_NO_BATTERY: return "no battery";
		case POWER_STATE_CHARGING: return "charging";
		case POWER_STATE_CHARGED: return "charged";
		default: return "unknown";
	}
}
void main() {
	system_power_state old_state = system_power_info();
	show_window(describe_power_state(old_state));
	while (!key_pressed(KEY_ESCAPE) and !key_pressed(KEY_AC_BACK)) {
		wait(5);
		int seconds, percent;
		system_power_state st = system_power_info(seconds, percent);
		if (st != old_state) show_window(describe_power_state(st));
		old_state = st;
		if (key_pressed(KEY_SPACE)) {
			string time_str = seconds > -1? " (" + timespan(seconds, 0).format() + ")" : "";
			screen_reader_speak(percent > -1? percent + "%" + time_str : "unable to determine battery percent");
		}
	}
}

write_environment_variable

Write to an environment variable.

void write_environment_variable(const string&in variable, const string&in value);

Arguments:

Example:

void main() {
	write_environment_variable("NVGT_Test_for_docs", "Testing");
	alert("Result", read_environment_variable("NVGT_Test_for_docs"));
}

Global Properties

ANDROID_SDK_VERSION

The API level of the Android version the program is running on.

const int ANDROID_SDK_VERSION;

Remarks:

This is the Android API level, such as 34 for Android 14, not the user facing version number. It can be used to check whether features that need a particular Android version are available.

On platforms other than Android, this is -1.

Example:

void main() {
	if (ANDROID_SDK_VERSION < 0)
		alert("Example", "This program is not running on Android.");
	else
		alert("Example", "The Android API level is " + ANDROID_SDK_VERSION);
}

ARGS

An array containing the command line arguments that were passed to your program.

const string[]@ ARGS;

Remarks:

Unlike COMMAND_LINE, which joins every argument into a single string, ARGS keeps each argument separate, so arguments that contain spaces are not split apart.

The first element is reserved for the program itself. When running a script from source, ARGS[0] is the filename of the script. In a compiled game, ARGS[0] is an empty string. The arguments that were actually passed to the program start at ARGS[1].

When running a script from source on the command line, arguments meant for the script go after a --, for example nvgt game.nvgt -- first "second argument".

Example:

void main() {
	if (ARGS.length() < 2) {
		alert("Command line", "No arguments were provided.");
		return;
	}
	string list;
	for (uint i = 1; i < ARGS.length(); i++)
		list += i + ": " + ARGS[i] + "\n";
	alert("Command line arguments", list);
}

COMMAND_LINE

COMMAND_LINE returns anything that is passed as command line arguments. Note that it returns anything after the application name, and keep in mind that you will have to parse the output yourself (basic example below).

const string COMMAND_LINE;

Example:

void main() {
	const string[]@ arguments = COMMAND_LINE.split(" ");
	// Did we get any arguments?
	if (arguments[0] == "")
		alert("Command Line", "No arguments provided.");
	else
		alert("Command Line", "The first argument is " + arguments[0]);
}

OS

The operating system the program is running on, as a value from the OPERATING_SYSTEM enum.

const OPERATING_SYSTEM OS;

Remarks:

This value is decided when NVGT itself is built, so it describes the operating system family the running copy of NVGT was made for. For example, it is OS_WINDOWS_NT on every version of Windows and OS_DARWIN on both macOS and iOS.

If you only need a human readable name or a simple check, the PLATFORM property and functions such as system_is_windows may be easier to use.

Example:

void main() {
	if (OS == OS_WINDOWS_NT)
		alert("Example", "This program is running on Windows.");
	else if (OS == OS_LINUX || OS == OS_ANDROID)
		alert("Example", "This program is running on Linux or Android.");
	else
		alert("Example", "The operating system code is " + OS);
}

PLATFORM

This property returns a string containing the current platform, such as "Windows NT".

const string PLATFORM;

Example:

void main() {
	alert("Your current Platform  is", PLATFORM);
}

PLATFORM_ARCHITECTURE

This property returns a string containing the current platform architecture, such as "AMD64".

const string PLATFORM_ARCHITECTURE;

Example:

void main() {
	alert("Your current Platform architecture is", PLATFORM_ARCHITECTURE);
}

PLATFORM_DISPLAY_NAME

This property returns a string containing the current platform display name, such as "Windows 8".

const string PLATFORM_DISPLAY_NAME;

Remarks:

Due to a backwards compatibility problem in windows, this function by default will cap out at Windows 8 even if the user is running a newer version of Windows. If determining the most modern windows version on the user's system is important to you, you can create a gamename.exe.manifest file to target your app for modern windows. Here is some microsoft documentation that explains how, you can probably just use the example manifest provided there.

Example:

void main() {
	alert("Your current Platform display name is", PLATFORM_DISPLAY_NAME);
}

PLATFORM_VERSION

This property returns a string containing the current platform version, such as "6.2 (Build 9200)".

const string PLATFORM_VERSION;

Example:

void main() {
	alert("Your current Platform version is", PLATFORM_VERSION);
}

PROCESSOR_ARCHITECTURE

The processor architecture the program is running on, as a value from the ARCHITECTURE enum.

const ARCHITECTURE PROCESSOR_ARCHITECTURE;

Remarks:

This value is decided when NVGT itself is built, so it describes the architecture the running copy of NVGT was compiled for. For example, a 64 bit Intel or AMD build reports ARCH_AMD64. If an x64 build is running under emulation on an ARM processor, it still reports ARCH_AMD64.

For a human readable architecture name, see the PLATFORM_ARCHITECTURE property.

Example:

void main() {
	if (PROCESSOR_ARCHITECTURE == ARCH_AMD64)
		alert("Example", "This is a 64 bit Intel or AMD build.");
	else if (PROCESSOR_ARCHITECTURE == ARCH_ARM64)
		alert("Example", "This is a 64 bit ARM build.");
	else
		alert("Example", "The architecture code is " + PROCESSOR_ARCHITECTURE);
}

PROCESSOR_COUNT

This property returns the number of processors on your system. Note that this returns the number of threads, not physical cores.

const uint PROCESSOR_COUNT;

Example:

void main() {
	alert("Processor Threads Count", PROCESSOR_COUNT);
}

system_is_chromebook

This property is true if the application is running on a Google Chromebook.

const bool system_is_chromebook;

Example:

void main() {
	if(system_is_chromebook)
		alert("example", "This application is running on a chromebook!");
	else
		alert("example", "This application is not running on a chromebook.");
}

system_is_DeX_mode

This property is true if the application is running in Samsung DeX mode, which is a desktop-like environment available on certain Samsung devices. It allows a mobile device to provide a desktop experience when connected to an external display.

const bool system_is_DeX_mode;

Example:

void main() {
	if(system_is_DeX_mode)
		alert("example", "This application is running in Samsung DeX mode!");
	else
		alert("example", "This application is not running in Samsung DeX mode.");
}

system_is_mobile

This property is true if the application is running on any mobile device, for example a cell phone.

const bool system_is_mobile;

Example:

void main() {
	if(system_is_mobile)
		alert("example", "This application is running on a mobile device!");
	else
		alert("example", "This application is not running on a mobile device.");
}

system_is_tablet

This property is true if the application is running on any device that identifies itself as a tablet.

const bool system_is_tablet;

Example:

void main() {
	if(system_is_tablet)
		alert("example", "This application is running on a tablet!");
	else
		alert("example", "This application is not running on a tablet.");
}

system_is_unix

This property is true if the application is running on a unix operating system, which in regards to NVGT's platforms is almost everything other than windows.

const bool system_is_unix;

Example:

void main() {
	if(system_is_unix)
		alert("example", "This application is running on a unix operating system!");
	else
		alert("example", "This application is probably running on windows, or in any case not a unix operating system");
}

system_is_windows

This property is true if the application is running on a windows operating system.

const bool system_is_windows;

Example:

void main() {
	if(system_is_windows)
		alert("example", "This application is running on windows!");
	else
		alert("example", "This application is not running on windows.");
}

system_node_id

This property returns the node ID, or another words, primary MAC address, of your system.

const string system_node_id;

Example:

void main() {
	alert("Your system node/host ID is", system_node_id);
}

system_node_name

This property returns the node name, or another word, host name, of your system.

const string system_node_name;

Example:

void main() {
	alert("Your system node/host name is", system_node_name);
}