System functions and properties

System functions and properties

CapsLock property
ColorDepth property (system)
Gamma property
HardwareAcceleration property
NumLock property
OperatingSystem property
ScreenHeight property
ScreenWidth property
ScrollLock property
SupportsGammaControl property
Version property
ViewportHeight property
ViewportWidth property
VSync property
Windowed property

CapsLock property

readonly static bool System.CapsLock;

Gets whether Caps Lock is active on the player's system.

You might want to use this to warn the player to switch it off before typing a password in, for example.

Example:

if (System.CapsLock)
{
  Display("The CAPS LOCK light is on.");
}

will display a message if Caps Lock is on.

Compatibility: Supported by AGS 3.0.1 and later versions.

See Also: System.NumLock, System.ScrollLock

ColorDepth property (system)

(Formerly known as system.color_depth, which is now obsolete)

readonly static int System.ColorDepth;

Returns the colour depth at which the game is running. This is the overall game colour depth setting, and it is possible for individual sprites or backgrounds to be different.

Example:

Display("Game is running at: %d x %d, %d-bit colour", System.ScreenWidth,
                                  System.ScreenHeight, System.ColorDepth);

will display the current resolution and colour depth

Gamma property

static int System.Gamma;

Gets/sets the current screen Gamma level. This is 100 by default, and you can set it anywhere from 0 (pitch black) to 200 (double normal brightness).

System.SupportsGammaControl must return true in order for this property to have any effect.

Because every player's monitor will be different, you should normally use this property linked to a GUI Slider in order to allow the player to adjust it to suit their system.

Example:

if (System.SupportsGammaControl) {
  System.Gamma = 150;
}

will turn the screen brightness up to 50% higher than normal

See Also: System.SupportsGammaControl

HardwareAcceleration property

readonly static bool System.HardwareAcceleration;

Returns whether the game is running with hardware acceleration (eg. Direct3D). If this is the case then RawDrawing is likely to be slower, but alpha blending and large sprites are likely to be faster, than when the non-accelerated driver is used.

Cross-Platform Support

Windows: Direct3D driver
MS-DOS: No
Linux: No
MacOS: No

Example:

if (System.HardwareAcceleration) {
  Display("Yay, we can draw loads of alpha blended sprites fast!");
}

will display a message if the game is being run with hardware acceleration

NumLock property

readonly static bool System.NumLock;

Gets whether Num Lock is active on the player's system.

You might want to use this to warn the player to switch it off before using the numeric keypad arrow keys, for example.

Example:

if (System.NumLock)
{
  Display("The NUM LOCK light is on.");
}

will display a message if Num Lock is on.

Compatibility: Supported by AGS 3.0.1 and later versions.

See Also: System.CapsLock, System.ScrollLock

OperatingSystem property

(Formerly known as system.os, which is now obsolete)

readonly static eOperatingSystem System.OperatingSystem;

Returns which operating system the game is currently running under. It can be one of the following values:

eOSDOS
eOSWindows
eOSLinux
eOSMacOS

Example:

if (System.OperatingSystem == eOSWindows) {
  Display("Running on Windows!");
}
else {
  Display("Not running on Windows!");
}

ScreenHeight property

(Formerly known as system.screen_height, which is now obsolete)

readonly static int System.ScreenHeight;

Returns the actual screen height that the game is running at. This could be 200, 240, 400, 480 or 600.

Note that if a graphic filter is in use, the resolution returned will be that before any stretching applied by the filter has been applied.

NOTE: This information is provided in case you need it to optimise your game, however please do not use it to force the player to run at a particular resolution. AGS is designed to allow players to choose different resolutions to help get the game working on their PC.

Example:

Display("Game is running at: %d x %d, %d-bit colour", System.ScreenWidth,
                                  System.ScreenHeight, System.ColorDepth);

will display the current resolution and colour depth

ScreenWidth property

(Formerly known as system.screen_width, which is now obsolete)

readonly static int System.ScreenWidth;

Returns the actual screen width that the game is running at. This could be 320, 640 or 800.

Note that if a graphic filter is in use, the resolution returned will be that before any stretching applied by the filter has been applied.

Example:

Display("Game is running at: %d x %d, %d-bit colour", System.ScreenWidth,
                                  System.ScreenHeight, System.ColorDepth);

will display the current resolution and colour depth

ScrollLock property

readonly static bool System.ScrollLock;

Gets whether Scroll Lock is active on the player's system.

Note that when running your game under the debugger, the Scroll Lock key will break out of the game into the debugger, so it is not advised that you use it for any other purpose in your game.

Example:

if (System.ScrollLock)
{
  Display("The SCROLL LOCK light is on.");
}

will display a message if Scroll Lock is on.

Compatibility: Supported by AGS 3.0.1 and later versions.

See Also: System.CapsLock, System.NumLock

SupportsGammaControl property

readonly static bool System.SupportsGammaControl;

Gets whether the player's PC supports changing the screen's gamma control settings.

This must return true before you try and change the System.Gamma property. The situations in which this will be supported are listed below.

Cross-Platform Support

Windows: Full-screen only
MS-DOS: No
Linux: No
MacOS: No

Example:

if (System.SupportsGammaControl) {
  Display("We can change the system gamma level!");
}

will display a message if the system supports changing the gamma

See Also: System.Gamma

Version property

(Formerly known as system.version, which is now obsolete)

readonly static String System.Version;

Returns the AGS engine version number. This could be useful from within script modules in order to use features available on a particular engine version, or work around any known bugs.

The string returned is the full version number, for example "2.71.833".

Example:

Display("AGS version: %s", System.Version);

will display the AGS version number

ViewportHeight property

(Formerly known as system.viewport_height, which is now obsolete)

readonly static int System.ViewportHeight;

Returns the height of the current viewport. This is reported in 320x200-resolution units, and allows you to find out what the maximum co-ordinates you can pass to functions like Mouse.SetPosition are.

Example:

Display("Game viewport: %d x %d", System.ViewportWidth, System.ViewportHeight);

will display the current viewport size

See Also: System.ViewportWidth

ViewportWidth property

(Formerly known as system.viewport_width, which is now obsolete)

readonly static int System.ViewportWidth;

Returns the width of the current viewport. This is reported in 320x200-resolution units, and allows you to find out what the maximum co-ordinates you can pass to functions like Mouse.SetPosition are.

Example:

Display("Game viewport: %d x %d", System.ViewportWidth, System.ViewportHeight);

will display the current viewport size

See Also: System.ViewportHeight

VSync property

(Formerly known as system.vsync, which is now obsolete)

static bool System.VSync;

Gets/sets whether AGS waits for the vertical retrace before rendering each frame. This is off by default.

If you switch this on, it can help to reduce the "tearing" effect that you can get when the screen scrolls. However, doing so will lock the game frame rate to the monitor's refresh rate, which will mean you cannot reliably set a game speed higher than 60 fps.

NOTE: This property has no effect with the Direct3D driver.

Example:

if (System.VSync) {
  Display("Vertical retrace sync is enabled!");
}

will display a message if vsync is on

Windowed property

(Formerly known as system.windowed, which is now obsolete)

readonly static bool System.Windowed;

Returns whether the game is currently running in a window (true) or full-screen (false).

Example:

if (System.Windowed) {
  Display("Game is running in a window!");
}

will display a message if the game is running in a window