System expressions

This section outlines the expressions in the built-in System object in Construct 2. Many are common mathematical operators, and they can be listed with descriptions in the Expressions panel, but they are included here for completeness.

This section does not list the operators or syntax that can be used in expressions - just the expressions specific to the System object. For more general information on how to use expressions in Construct 2, see Expressions.

Display

OriginalWindowWidth

OriginalWindowHeight

Get the original values of the Window size project property.

WindowWidth

WindowHeight

Get the size of the canvas being displayed in device pixels. Note this is not the same as the viewport; see the ViewportLeft/Top/Right/Bottom expressions. See also Supporting multiple screen sizes. #Layers# In expressions where a layer is required, either its name (as a string) or index (as a number, zero-based) can be entered.

CanvasToLayerX(layer, x, y)

CanvasToLayerY(layer, x, y)

Calculate the layout co-ordinates underneath a position in canvas co-ordinates for a given layer.

LayerToCanvasX(layer, x, y)

LayerToCanvasY(layer, x, y)

Calculate the canvas co-ordinates above a position in layout co-ordinates for a given layer.

LayerAngle(layer)

Get the angle, in degrees, of a layer.

LayerIndex(layer)

Get the zero-based index of a layer from its name.

LayerOpacity(layer)

Get the opacity (or semitransparency) of a layer, from 0 (transparent) to 100 (opaque).

LayerParallaxX(layer)

LayerParallaxY(layer)

Get the current parallax X and Y components of a layer.

LayerScale(layer)

Get the current scale of the layer, not including the overall layout scale.

LayerScaleRate(layer)

Get the current scale rate of the layer, which defines how quickly it scales (if at all).

ViewportBottom(layer)

ViewportLeft(layer)

ViewportRight(layer)

ViewportTop(layer)

Return the viewport boundaries in layout co-ordinates of a given layer. Not all layers have the same viewport if they are parallaxed, scaled or rotated separately.

Layout

CanvasSnapshot

Contains the resulting image from a Snapshot canvas action after On canvas snapshot has run. (Note this expression is not available immediately after the Snapshot canvas action - you can only use it after On canvas snapshot triggers.) The expression returns a data URI of the image file. This can be loaded in to a Sprite or Tiled Background object via Load image from URL, sent to a server or stored locally, or opened with the Browser object in a new tab to save to disk.

LayoutAngle

Get the angle, in degrees, of the current layout. This does not include the rotation of individual layers.

LayoutScale

Get the current scale of the entire layout set by the Set layout scale action. This does not include the scaling of individual layers.

LayoutWidth

LayoutHeight

Get the size of the current layout in pixels.

LayoutName

Get the name of the current layout.

scrollx

scrolly

Get the current position the view is centered on.

Math

These expressions are simply ordinary math functions like you find on calculators. However, note that all functions using an angle take it in degrees, not radians. Angles start with 0 degrees facing right and increment clockwise.

sin(x)

, cos(x) , tan(x) , asin(x) , acos(x) , atan(x) Trigonometric functions using angles in degrees.

abs(x)

Absolute value of x e.g. abs(-5) = 5

angle(x1, y1, x2, y2)

Calculate angle between two points

anglelerp(a, b, x)

Linearly interpolate the angle a to b by x. Unlike the standard lerp, this takes in to account the cyclical nature of angles.

anglediff(a1, a2)

Return the smallest difference between two angles

anglerotate(start, end, step)

Rotate angle start towards end by the angle step, all in degrees. If start is less than step degrees away from end, it returns end.

ceil(x)

Round up x e.g. ceil(5.1) = 6

cosp(a, b, x)

Cosine interpolation of a to b by x. Calculates (a + b + (a - b) [] cos(x [] 180°)) / 2.

cubic(a, b, c, d, x)

Cubic interpolation through a, b, c and d by x. Calculates lerp(qarp(a, b, c, x), qarp(b, c, d, x), x).

distance(x1, y1, x2, y2)

Calculate distance between two points

exp(x)

Calculate e^x

floor(x)

Round down x e.g. floor(5.9) = 5

infinity

A floating point number value representing infinity.

lerp(a, b, x)

Linear interpolation of a to b by x. Calculates a + x [*] (b - a).

unlerp(a, b, y)

Reverse linear interpolation: if lerp(a, b, x) = y, then unlerp(a, b, y) = x. Calculates (y - a) / (b - a).

ln(x)

Log to base e of x.

log10(x)

Log to base 10 of x.

max(a, b [, c...])

, min(a, b [, c...]) Calculate maximum or minimum of the given numbers. Any number of parameters can be used as long as there are at least two.

pi

The mathematical constant pi (3.14159...)

qarp(a, b, c, x)

Quadratic interpolation through a, b and c by x. Calculates lerp(lerp(a, b, x), lerp(b, c, x), x).

round(x)

Round x to the nearest whole number e.g. round(5.6) = 6

sqrt(x)

Calculate square root of x e.g. sqrt(25) = 5

getbit(x, n)

Get the nth bit of x represented as a 32-bit integer. For example getbit(7, 0) will get the least significant bit of the number 7 when represented as a 32-bit integer. Returns either 0 or 1.

setbit(x, n, b)

Set the nth bit of x represented as a 32-bit integer to b (either 0 or 1). The resulting 32-bit integer is returned.

togglebit(x, n)

Toggle the nth bit of x represented as a 32-bit integer. If that bit is 0, it is set to 1; if it is 1, it is set to 0. The resulting 32-bit integer is returned.

Save & Load

SaveStateJSON

In On save complete or On load complete, returns a string of JSON data representing the savegame data. This can later be loaded using the Load from JSON action. For more information see How to make savegames.

System

ImageMemoryUsage

Returns the estimated total memory usage, in megabytes, of all the currently-loaded images. Only supported in the WebGL renderer; if canvas2D rendering is in use, the expression always returns 0. Note image memory is sometimes also referred to as "VRAM", but this is not strictly correct since not all devices have video-specific memory. Also remember this expression does not include the memory use of sounds, code, or other non-image resources.

loadingprogress

Return the current load progress on a loader layout, or the current update progress while the Browser object's Is downloading update condition is true. The progress is returned as a number from 0 to 1, e.g. 0.5 for half complete. For more information, see the tutorials how to make a custom loading screen and offline games in Construct 2.

loopindex

Get the index (number of repeats so far) in any currently running loop.

loopindex(name)

Get the index (number of repeats so far) of the loop with the given name. Useful for getting indices in nested loops.

objectcount

The total number of objects currently created.

projectname

Return the name of the project as it appears in Project Properties.

projectversion

Return the version entered in to Project Properties. Note that this is always returned as a string, not a number.

renderer

The name of the renderer used to draw the game, currently either canvas2d or webgl. See Technology for more information on canvas renderers.

rendererDetail

The name of the graphics hardware in use to draw the game, such as "NVIDIA GeForce GTX 660" or "Adreno 330". This is only available in WebGL mode in certain browsers and platforms; unsupported browsers/systems will return "(unavailable)". Projects should not rely on this string having any exact contents, but it can be useful to diagnose which GPU is in use in dual-GPU systems, or to look for keywords and apply default graphics settings based on the type of hardware.

Text

find(src, text)

findCase(src, text)

Find the first index within src that text occurs, else returns -1. find is case-insensitive, and findCase is case-sensitive.

left(text, count)

Return the first count characters of text.

len(text)

Return the number of characters in text.

lowercase(text)

Convert the given text to all lowercase.

mid(text, index, count)

Return the count characters starting from index in text.

newline

A string containing a line break. Use to insert line breaks in to strings, e.g. "Hello" & newline & "World"

RegexMatchAt(String, Regex, Flags, Index)

Process the regular expression Regex on String with Flags, and in the list of results, return the entry at Index.

RegexMatchCount(String, Regex, Flags)

Process the regular expression Regex on String with Flags, and return the number of entries in the list of results.

RegexReplace(String, Regex, Flags, Replace)

In String substitute matches for the regular expression Regex (with Flags) with the string Replace. The replacement string can contain the following special characters: $$ (inserts a $), $& (inserts the matched substring), $` (inserts the portion of the string that precedes the matched substring), or $' (inserts the portion of the string that follows the matched substring).

RegexSearch(String, Regex, Flags)

Return the index of the first character in String where a match for Regex with Flags could be found.

replace(src, find, rep)

Find all occurrences of find in src and replace them with rep.

right(text, count)

Return the last count characters of text.

tokenat(src, index, separator)

Return the Nth token from src, splitting the string by separator. For example, tokenat("apples|oranges|bananas", 1, "|") returns oranges.

tokencount(src, separator)

Count how many tokens occur in src using separator. For example, tokencount("apples|oranges|bananas", "|") returns 3.

trim(src)

Return src with all whitespace (spaces, tabs etc.) removed from the beginning and end of the string.

uppercase(text)

Convert the given text to all uppercase.

URLEncode(str)

URLDecode(str)

Convert to and from a string in a format suitable for including in a URL or POST data.

zeropad(number, digits)

Pad number out to a certain number of digits by adding zeroes in front of the number, then returning the result as a string. For example, zeropad(45, 5) returns the string "00045".

Time

CPUUtilisation

The percentage of the last second that was spent in the application logic. This is for advanced users to make performance measurements. Note on hardware-accelerated devices the rendering happens on the separate GPU and therefore this measurement cannot tell you anything about how fast or slow the rendering is; for that fps is a better measure. Also note this measurement is based on timers so should be treated as an approximation, and it only measures the main Javascript thread time.

dt

Delta-time in seconds. See Delta-time and framerate independence.

fps

The current frames per second (FPS) rate, which is how many times the screen is being drawn every second. Most computers run at 60 fps if they are fast enough.

tickcount

The number of ticks that have run since the game started.

time

The number of seconds since the game started, taking in to account the time scale.

timescale

The current time scale.

wallclocktime

The number of seconds since the game started, not taking in to account the time scale (i.e. the real-world time).

Values

choose(a, b [, c...])

Choose one of the given parameters at random. E.g. choose(1, 3, 9, 20) randomly picks one of the four numbers and returns that. This also works with strings, e.g. choose("Hello", "Hi") returns either Hello or Hi. Any number of parameters can be used as long as there are at least two.

clamp(x, lower, upper)

Return lower if x is less than lower, upper if x is greater than upper, else return x.

float(x)

Convert the integer or text x to a float (fractional number). If x is text, non-numeric characters are allowed after the number, but not before. For example float("3.1xx") returns 3.1, but float("xx3.1") returns 0.

int(x)

Convert the float or text x to an integer (whole number). If x is text, non-numeric characters are allowed after the number, but not before. For example int("33xx") returns 33, but int("xx33") returns 0.

random(x)

Generate a random float from 0 to x, not including x. E.g. random(4) can generate 0, 2.5, 3.29293, but not 4. Use floor(random(4)) to generate just the whole numbers 0, 1, 2, 3.

random(a, b)

Generate a random float between a and b, including a but not including b.

rgb(r, g, b)

Generate a single number containing a color in RGB format. This is useful for conditions or actions taking a color parameter.

str(x)

Convert the integer or float x to a string. Generally not necessary since strings can be built using the & operator, e.g. "Your score is " & score