Expressions in GameBuilder Studio are very powerful, it allows you to dynamically access many different properties in your game while the game is running. You can run math equations, get the current level index, reference the value of a property on an entity, etc. Currently you have to enter an expression by hand but very soon you will be able to click on the expression icon and open an expression editor to assist you with entering an expression. Entering an expression is as easy as writing a formula in Excel.
Math Expression Functions
You have access to a bunch of standard math functions:
- abs( Number ) - Computes and returns an absolute value for the number specified by the parameter val.
- acos( Number ) - Computes and returns the arc cosine of the number specified in the parameter val, in radians.
- asin( Number ) - Computes and returns the arc sine for the number specified in the parameter val, in radians.
- atan( Number ) - Computes and returns the value, in radians, of the angle whose tangent is specified in the parameter val.
- atan2( NumberA, NumberB ) - Computes and returns the angle of the point y/x in radians, when measured counterclockwise from a circle's x axis (where 0,0 represents the center of the circle).
- ceil( Number ) - Returns the ceiling of the specified number or expression.
- cos( Number ) - Computes and returns the cosine of the specified angle in radians.
- distance( X1, Y1, X2, Y2 ) - Computes and returns the distance / threshold between to points in space. This can be used to calculate the distance between to spatials.
- exp( Number ) - Returns the value of the base of the natural logarithm (e), to the power of the exponent specified in the parameter x.
- floor( Number ) - Returns the floor of the number or expression specified in the parameter val.
- log( Number ) - Returns the natural logarithm of the parameter val.
- magnitude( NumberA, NumberB ) - Computes the distance/magnitude between two numbers. This utilizes the pythagorean theorem.
- magnitudeOfPoint( PointA, PointB ) - Computes the distance/magnitude between two Points. This utilizes the pythagorean theorem.
- max( Number1, Number2 ) - Evaluates val1 and val2 (or more values) and returns the largest value.
- min( Number1, Number2 ) - Evaluates val1 and val2 (or more values) and returns the smallest value.
- pow( [base] Number, [pow] Number) - Computes and returns base to the power of pow.
- random( ) - Returns a pseudo-random number n, where 0 <= n < 1.
- rotationOfAngle( PointA, PointB ) - Computes and returns the rotation amount of two points.
- round( Number ) - Rounds the value of the parameter val up or down to the nearest integer and returns the value.
- sin( degrees * 3.14159265 / 180 ) - Computes and returns the sine of the specified angle in radians. (If angle is in degrees it has to be converted to radians as shown)
- sqrt( Number ) - Computes and returns the square root of the specified number.
- tan( degrees * 3.14159265 / 180 ) - Computes and returns the tangent of the specified angle. (If angle is in degrees it has to be converted to radians as shown)
**The ones in bold are the ones you will probably use the most.
There are a few other special functions that have been made available to make your life easier:
- setPoint( XNumber, YNumber ) - Will return a Point Object with the X and Y values that you pass
- Entity( "ENTITY NAME" ) - Will return a reference to the entity so that you can reference components on an outside entity. (i.e. Entity("HeroObject").Renderer.alpha )
We will continue to add functions to the expressions field as we add more functionality.
If you want to reference a property on the same entity that the expression lives on you need to use the "Self" property to point to a component. (i.e. Self.Renderer.alpha )
The "Game" property will give you access to all of the global game properties that are available to you such as:
- Game.Mouse.x - the X position of the users' mouse
- Game.Mouse.y - the Y position of the users' mouse
- Game.Time.virtualTime - The amount of time that has been processed by the process manager. This does take the time scale into account. Time is in milliseconds.
- Game.Time.timeScale - The scale at which time advances. If this is set to 2, the game will play twice as fast. A value of 0.5 will run the game at half speed. A value of 1 is normal.
- Game.Time.gameTime - The actual time that has passed since the game was launched this is updated consistently every frame of the game and not effected by timeScale.
- Game.Screen.width - The width of the game.
- Game.Screen.height - The height of the game.
- Game.Level.currentLevel - The index number of the current level the user is playing. This index starts at 0, so 0 is the first level in your game.
- Game.Level.levelCount - The total count of all levels in the game.