Chapter 13: The Expression Editor

In This Chapter You Will Learn:

•How to use the expression editor

•How to manipulate values using math functions

•How to manipulate text and text attributes using text functions

In this chapter, you will learn all about the expression editor―Gamesalad's tool for adding mathematic formulas to games. First, you’ll learn how to open and navigate the expression editor and discover what options are available from within it. Next, you will learn how to add math functions to a game and learn what some of the most common math functions are used for. Then I will show you how to use text functions to manipulate text in your projects. Finally, you will use your knowledge of both math and text functions to work through a series of exercises using the expression editor.

Expression Editor Basics

The expression editor is available for use within many of Gamesalad's behaviors. Any time you see the “e” icon in a behavior, that icon can be clicked to expose the expression editor (see Figure 13.1).

Figure 13.1: The Expression Editor can be opened by clicking on the “e” icon located next to an input box in behaviors.

From the expression editor, you have access to just about every editable setting Gamesalad has to offer. Open the expression editor from within a behavior so you can follow along or review Figure 13.2 below.

1Expression input box: This input box is where you will create and edit the expression.

2Attributes arrow: When clicked, this arrow will expose the attributes browser that is built into the expression editor. As you have already learned, this browser provides access to all of the attributes used in a game. If the actor that is being edited is an unlocked instance actor, you will also have access to the scene attributes through this menu.

3Functions menu: The insert function drop-down menu provides access to many mathematical, table, and text manipulation functions.

4Remove expression button: Pressing this button will delete any expression that is currently displayed and will also close the editor.

5Accept button: Pressing the green checkmark button will accept the expression and will also close the editor.

6Decline button: Pressing red x button will cancel any edits that have been made to an expression and will also close the editor.

Figure 13.2: The Expression Editor .

Expressions created in the expression editor can be extremely simple or very complex; the complexity will depend on the specific use of the expression. Unlike most of Gamesalad, the expression editor is very open-ended and is not a drag and drop solution. This offers a lot of power when creating games, but can also be frustrating to learn. When creating a specific expression for a game, you will often have to employ trial and error to get the expected results. For more complex expressions, the best way to approach this is to first figure out what the expression should accomplish and then try different expressions to reach the desired goal.

Mathematical Expressions

While you can use the expression editor to manipulate text and tables, the most common use is certainly to perform math functions. The most basic of all the math functions are addition, subtraction, multiplication, division, and modulus. These are all accomplished by directly using the appropriate symbol in the expression (see arithmetic operators in chapter 6).

––––––––––––––––––––––––––––––––––––––––––

Exercise 15: Basic Math Function

In this exercise, you will create a simple expression that uses addition to manually move an actor 64 pixels to the right every time the actor is clicked on.

1Create a new project for any platform and navigate to the Initial Scene.

2Add an actor and change its size to 32x32 pixels.

3Add a Rule to this actor and create a condition that reads: Actor receives event » touch » is » pressed

4Nest a Change Attribute Behavior in the rule and choose self.Position.X from the Attributes Browser for the Change Attribute field.

5Next, open the Expression Editor and Click the down arrow to expose the Attributes Browser. Choose self.Position.X and type “+64” (see Figure 13.3).

6Press Return and Click the green check mark to accept the expression and close the Expression Editor.

7Navigate to the Stage and place the actor at the far left edge of the Stage.

8Save this file. You’ll use it again in the next exercise.

––––––––––––––––––––––––––––––––––––––––––

Figure 13.3: The completed expression in the Expression Editor.

Preview the scene and you’ll see that every time you click on the actor, it moves 64 pixels to the right.

Note–Order of Operations: Equations created in the expression editor follow the standard order of operations. Equations are evaluated from left to right, with multiplication and division being evaluated before addition and subtraction. Parentheses are used to evaluate certain parts of equations first.

In addition to the standard mathematical functions, you have access to a long list of built-in functions. Some of the most commonly used built-in functions are:

•abs: The abs function will return the absolute value (positive value) of a number or attribute. For example, abs(-4.97)=4.97.

•ceil: The ceiling function will round up a value to its nearest integer. For example, ceil(7.5)=8.

•floor: Using the floor function will round down a number to its nearest integer. For example, floor(2.2)=2.

•max: The maximum function will find the higher of two numbers. For example, max(50,82)=82

•precision: This will display a real number with the specified number of decimal places. The number of decimal places shown is determined by the second number (y) in the function. For example, prec(256.47983,2)=256.47.

•random: The random function will return a random number between the two values used in the function. For example, random(1,3) could return either 1, 2, or 3.

––––––––––––––––––––––––––––––––––––––––––

Exercise 16: Randomness

Video games often rely on random numbers to help create a more natural feeling in the game. In this exercise, you’ll use the random function to place an actor at different locations around the screen each time a button is pressed.

1Begin with the file you finished in the last exercise and create a second actor in the Actors Tab.

2Change this actor's size to 32x32 and change its color to anything other than white.

3Double-Click the white square actor from the last exercise and delete the Change Attribute Behavior from the Rule.

4Nest a Spawn Actor Behavior in this Rule and choose Actor 2 from the Actor drop-down menu.

5Open the Expression Editor for the Position X input field (right arrow).

6From the Insert Function menu, choose Random.

7Delete the text between the parenthesis “min,max” and replace it with 0,game.Display Size.Width (see Figure 13.4).

8Open the Expression Editor for the Position Y input field (up arrow).

9Add a Random function and set it up to read: random(0,game.Display Size.Height)

10Choose Scene from the Positions Relative To menu.

––––––––––––––––––––––––––––––––––––––––––

Preview the scene and repeatedly Click on the white square actor. Each time you click, a new colored actor will appear in a random spot on the stage.

Tip–Screen Dimensions: Using the attributes “game.Display Size.Height” and “game.Display Size.Width” to determine the devices scene size is much more flexible than adding actual pixel values to behaviors. Using this method, it is possible to create games that will run on multiple devices regardless of their screen sizes.

Text Expressions

Text expressions are used to manipulate text and text attributes in a game, much the same way math functions are used with numbers. There are many uses for text and text manipulation. Text expressions can be used in conjunction with display text behaviors to write a score value in a games GUI or to display a list of high scores on a game over screen.

When entering text directly into the expression editor, the text must be surrounded with double quotation marks (e.g. “My Text”). Putting text inside quotation marks tells Gamesalad to treat it as text to be displayed on-screen and not evaluated as a formula.

The most common and simplest text expression is used to concatenate two, or more, text values. Gamesalad uses two periods in a row to indicate concatenation (..).

Note–Concatenation: Means to connect or link two or more objects together.

––––––––––––––––––––––––––––––––––––––––––

Excercise 17: Score Display

In this exercise, you will display a score value on-screen.

1Start a new project for any platform type and navigate to the Initial Scene.

2First, create a new Integer Attribute in the Attributes Tab and name it “Score”. Give it a value of 100.

3Create a new empty actor in the Actors Tab. Open the Actor Editor and change the value of Alpha to 0. This will make the actor itself invisible, but not the text that it will display.

4Add a Display Text Behavior to this actor and open the Expression Editor for the Text input field by Clicking the “e” icon to the right of the text field.

5In this field, type (this time include the quotation marks): “Score:”..

6With the cursor to the right of the two periods (..), Click the down arrow in the Expression Editor to expose the Attributes Browser and choose the Score Attribute that was just created from the Game list. The Display Text Behavior should look Figure 13.5:

7Accept this expression and return to the Scene. Place the actor in the center of the Stage, and Preview the scene.

8You should see the text “Score:100” displayed on-screen.

Figure 13.5: The completed expression for the Display Text Behavior.

While that looks pretty good, it would look better if there was a space after the colon and before the number 100. To include a space in text that is entered in the Expression Editor, you’ll need to use a special “escape character”.

1Return to the Display Text Behavior and open the Expression Editor.

2Place the cursor between the colon and the quotation mark.

3Type ‘\32’ (without the quotation marks).

4Accept the Expression and Preview the Scene.

5Now the text will display as “Score: 100.”

Escape Characters

There are certain characters that can’t be directly entered in the Expression Editor; these characters must be input as special escape characters. Below is a list of common escape characters.

Table 13.1 Common Escape Characters

Character Code Entered » Character Output

\32 » Space

\\ » \

\” » ”

\n » New Line

\r » Carriage Return

Text Functions

In addition to the math functions that were reviewed earlier in this chapter, Gamesalad offers a series of text functions as well. These functions are used to manipulate text and text attributes just like the math functions are used to manipulate numbers. Some of the most used text functions are:

•textLength: Using the textLength function will return the number of individual character in the text string. For example: textLength(“Hello”)=5.

•textReplace: This function is used to replace certain words or characters in a text string. The format of the function is textReplace(text,pattern,replacement).

•text: Represents the source text to operate on.

•pattern: Represents the word or character that will be replaced.

•replacement: Represents the word used as a replacement.
For example: textReplace(“Hello World”,”Hello”,”Goodbye”)=Goodbye World

•textSubStr: Use the textSubStr function when you need to separate some of the text from its surrounding characters. The format of the function is textSubStr(text,startIndex,endIndex).

•text: Represents the source text to manipulate.

•startIndex: Represents the number of the first character to separate.

•endIndex: Represents the number of the last character to separate. For example: textSubStr(“I Love Making Games”,15,19)=Games

Note–Spaces and Escape Characters: Spaces and escape characters are counted as one character when using any of the text functions.

Additional Functions

The function menu also contains functions that can be used to manipulate tables, which will be examined in a later chapter. Networking functions are also listed, these are part of Gamesalad's implementation of multiplayer gaming and are a pro only feature.

Summary

In the last chapter, you learned the ins and outs of Gamesalad's Expression Editor. You learned how to use mathematical functions to manipulate attributes in your games. Next, you learned all about using text functions to control and work with text in projects. Finally, you experimented with some of the various math and text functions through a series of exercises.