Documentation/Articles/Overview of Logic Editor

From NeoAxis 3D Engine Wiki

Jump to: navigation, search
Go to higher level

Contents

Description

Logic Editor is a part of Map Editor used for creating algorithms specific for a particular map, i.e. those required for this map.

Вy means of the Logic Editor various classes can be created, as well as variables and methods can be assigned to these classes. Methods are written algorithms that can be created in two ways: in Designer Type mode (via user interface) or in Script Type mode (programming with C#).

One of the key features of the Logic Editor is the creation of subclasses for classes of game objects. This enables the creation of event handlers for game classes. An example of how they can be used is a subclass for the Region type. The class Region has an ObjectIn method, an event triggered when the character enters a region. Using the Logic Editor you can write an algorithm that makes a girder fall from a ceiling once the player enters a certain area marked with the object Region.

Starting the Logic Editor

The Logic Editor is started directly from the Map Editor. To start the Logic Editor you have to open a map and then select the button Logic Editor from the menu World.

Logic2.jpg

General View

Logic3.jpg

The Logic Editor is composed of four main areas:

  • 1 - Upper panel (menu, toolbar).
  • 2 - Class list window.
  • 3 - Working area.
  • 4 - Output window.

Let us examine each element in detail.

Menu, Toolbar

Logic4.jpg

The upper panel consists of the main menu and several shortcuts. Let us describe main functions of the main menu.

File menu.

Logic9.jpg
Save Map saves changes to the current map.

View menu.

Logic10.jpg
Adjustment of the editor window view.

Class list opens the class list window.

Output opens the display window, is case it was closed.

Tools menu.

Logic11.jpg
Run simulation starts the map.

Build test checks algorithms for syntax errors.

Class List Window

Logic5.jpg

This window is used for creating new classes of map logic. Here you can add classes, as well as add methods and variables to these classes.

Adding a New Class

Add a new class to map logic by selecting the Create Class button in the context menu of the Map Classes element of the classes list.

Logic12.jpg

First, the new class is adjusted in a special window.

Logic13.jpg

You have to name a new class and choose one of two class types:

  • Static, an ordinary class.
  • Entity, a subclass for a class of game objects. In the field Entity Class Type you have to specify the superclass for the class being created.

The Context Menu of a Class

Most actions with a class are performed through this class's context menu. Let us examine the available class adjustment functions.

Logic14.jpg

Edit changes the name of a class.

Delete removes a class.

Create Method adds a method to the class. You can create both custom user method (in Method menu) as well as a subclass for the base Entity-class. You also have to choose the way of method creation between Designer Type and Script Type.

Logic15.jpg

If you choose Designer Type you will also have to select the type of the returned value. If there is no need for the function to return value, select void. You will also need to list the input parameters if they are necessary. Each parameter is described by name and value type.

Logic17.jpg

Create Variable adds a variable to a class. You have to specify the name of the new variable and its type. The type of the variable can either be ordinary (like a number or a string) or belong to one of game object classes.

Logic16.jpg

With the check box Serialization selected the value of the variable will be saved while saving the world (Load/Save in Game.exe).

Create Custom Script Code adds a custom code to a class. This code may contain methods and variable declarations. For example Custom Script Code enables the declaration of complex variables that cannot be added through Create Variable.

Working Area

Working area contains map algorithms. Its appearance may vary dependent on the method type.

The tab bar is always at the top of the window and it can be used for switching between edit windows of various methods.

To enter the edit mode you have to double click on the class you are going to edit.

Designer Type

Working window in Designer Type mode

In Designer Type mode the working window consists of two fields: the commands list (Actions) and the command edit window.

Designer Type implies the creation of algorithms by means of user interface. There are two buttons to add and remove commands above the Actions list.

Logic19.jpg

These as well as other edit functions are also available from the context menu of the commands list.

Logic18.jpg

Let us examine each of these functions:

  • Insert adds a new command before the previous one. For more details about Designer Type see below.
  • Insert (After Current) adds a new command before the selected one. It is only available for statements including several commands within. These are such statements as if and while.
  • Copy makes a copy of the command in the buffer.
  • Paste inserts the command from the buffer before the current one.
  • Delete removes the selected command from the list.

Commands in Designer Type

This is how the add command window looks like.

Logic20.jpg

The creation of command is performed recursively. An action is chosen in Choose Action window with a double click. After that the added action is adjusted by selecting settings, statements and properties. The adjustment is performed through the Choose Action window. However, in this case the list of methods available is limited by those relevant for the command added to the first window. An action added in a new window is adjusted through the same window. The Choose Action window appears until the command is fully adjusted. So by constantly pressing the Ok button in a succession of windows you return to the very first Choose Action window. By pressing Ok there you add the command to the list.

Окна Choose Action для изменения цвета источника света

All editable elements of the command are highlighted like a hyperlink.

Logic61.jpg

Basic Commands

Name Description
Get Entity To access a game object. By pressing [...], you can access object properties.
This Members Class-member variables i.e. those you have created with Create Variable function. Moreover it also involves the variable Owner, which refers to an owner of an object.
Control Statements.
  • If/Then/Else. Conditional statement. If the condition after if is true, the following commands are performed, otherwise the commands after the key word else are performed.
  • While. Cycle statement. The commands are performed so long as the condition after the key word while is true.
  • Return. Returns the function’s value. It is relevant for user functions with any type other than void.
Local Variables Working with local variables. With block of commands a local variable can be declared (the statement declare) or an already declared one can be used. In addition to this function parameters are also available in this block.
Static Members Gives access to static functions of various classes.
Comment Adds a user comment that can be used for better understanding of algorithms.

The types listed above may be called basic since they are used in the beginning of any command written. Let us now touch upon other action available in the Choose Action window.

Commands for game objects

Using game object trough GetEntity. By selecting this command and specifying a game object you can use this object in a number of ways.

Name Description
as Transforms the object into another class. This may be used to transform an object from MapObject class into Character class. Along with such a transformation a verification of object’s belonging to a certain class should be performed by means of statement Is.
is Returns True, if the object belongs to the given class. For example, there is an object of a common for all objects class MapObject, but it is necessary to check if this object is a character. I this case the statement Is can be used to check whether the object belongs to the class character Character.

In addition to this, objects properties and methods can be used. Each object type has its methods and properties.

Conditionals

Conditionals are used in such statements as If/Then/Else, While, and can the value of Boolean variables. The result of a conditional is either True, or False.

Logic operations can be used as conditionals. They can be found among static functions of Boolean type. Let us examine the logic operations given there.

Operation Description
Boolean == Boolean Comparison. True if the arguments have the same value.
Boolean != Boolean "Not equal". True if the arguments have different value.
! Boolean Logic NOT. Inverts argument value.
Boolean and Boolean Logic AND. True if both arguments are true.
Boolean or Boolean Logic OR. True if either argument is true.

I addition to this, comparison functions of various types can also be elements of logic expressions. These are the following operations.

Operation Descrition
== Comparison. True if arguments have the same values.
!= "Not equal". True if the arguments have different value.
< Less than. True if the first argument’s value is less than the second argument’s value.
> Greater than. True if the first argument’s value is greater than the second argument’s value.
<= Equal to or less than. True if the first argument’s value is equal to or less than the second argument’s value.
>= Equal to or greater than. True if the first argument’s value is equal to or greater than the second argument’s value.

Conditional Statement

Logic62.jpg
Conditional statement if\then\else can be found in the actions list of Control section. In general a conditional statement looks like the following:

"if condition then action1 else action2"

The field condition includes conditionals mentioned above. If the condition is fulfilled, in other words, the conditional returns True, the statements from the block then (action1) are performed. Otherwise, the statements from the block else (action2) are performed.

Filling the block else is optional. Without it the conditional statement looks even simpler:

"if condition then action"

Cycle Statement

Logic63.jpg
Cycle statement is located in Control section of the command list. In general a cycle statement looks like the following:

"while condition action"

The field condition should contain a conditional. So long as it is being fulfilled, the statements from the block while (action) are performed. I.e. the condition is checked first, and if it is true the following statements are performed. Then the condition is checked again, and if it is still true the statements are performed etc.

We would like to point out that cycles statement should be used with caution since if the conditional does not return False, this may cause an infinite loop and result into an error.

Mathematical Operations

You can also find a large number of mathematical operations in the Logic Editor. There are special member-methods in a number of numerical classes for such operations as addition, subtraction, multiplication and division. Such numerical classes are:

  • Int32 - integral, symbolic.
  • Single - fractional, symbolic.

For more complex operations a special class Math is used. Let us examine the descriptions of its methods.

Name Description
DegToRad A function converting degrees into radians.
RadToDeg A function converting radians into degrees.
Sqrt Square root function.
Sin Sine function of an angle given in radians.
Cos Cosine function of an angle given in radians.
Tan Tangent function of an angle given in radians.
ASin Arc sine function, returning the angle value in radians.
ACos Arc cosine function, returning the angle value in radians.
ATan An arctangent function. There are two variants of it.
  • ATan( Single a ). Arc tangent function, returning the angle value in radians.
  • ATan( Single y, Single x ) returns the value of the angle between cathetus and hypotenuse where, x is the length of the adjacent cathetus, y is the length of the opposite cathetus.
Pow Exponentiation function where the first number is the base number and the second one is the exponent
Exp The function returns the value of exponent (e), exponentiated to the arguments exponent.
Floor The function returns the greatest number that is lesser or equal to the argument value.
Log Logarithm function. There are two variants of this function.
  • Log( Single a ). Hyperbolic logarithm function (where e is the base number).
  • Log ( Single a, Single newBase ). Logarithm function where is the base number.
Log10 Denary logarithm function.

Basic Methods

In this part we will examine the basic operations you may need while creating the map logic.

Further we will give the static classes and the description of their members. All of these classes are located in Static Members section of the command list.

Entities class.

Name Description
Create Creation of a game object. There are two variants of this function:
  • Create( EntityType type, Entity parent )
  • Create( String type, Entity parent )

The only difference between these functions is the way of object type transfer: through EntityType or through string with a type name. The second parameter parent should include the name of game object’s owner. For objects based on MapObject the parent object will always be Map.Instance.

GetByName Getting new game object by name. After this commands the statements as and is can be used (described here).
GetUniqueName Generates a unique name for a game object.
TickDelta The time interval between ticks in seconds. Each tick all the systems of the engine are updated (game objects, input devices). By default there are 30 ticks per second, i.e. TickDelta is 1/30 second.

EntityTypes class.

Name Description
GetByName Getting entity type class by name.

Logic class.

Name Description
Wait Waiting. The performance of all following commands is suspended for the given time. The engine continues functioning.

Example: a twinkling light. You can turn on\turn off the light in cycles, calling the function Wait in any interaction. However the delay will not affect other objects and the player will still be able to control the character.

Script Type

Рабочее окно в режиме Script Type

In the Script Type mode the working window is is a text editor with a syntax highlighting in which the initial code is written in C#.

This mode is quite convenient for programmers. Writing a code in the Script Type mode is quite simular to using programming environment (for example Visual Studio).

The code compiling is performed during the map launch. Moreover, the code may be checked for mistakes by pressing hte Build Test button.

Output Window

Logic8.jpg

The output window contains all the errors and warnings, detected by the editor after the test build of logic.

Adding Logic to Map Objects

The main elements of map logic are subclasses. To add logic to a map object you have to specify the object's logic class by means of the Logic Class parameter.

Logic21.jpg

You can select a logic class for an object from the list of map logic classes available for this object. Of course only those classes are available, that are based on the same classes as the object's class.

Logic22.jpg

Tutorial: Designer Type

In this tutorial you will learn to create map logic in Designer Type mode. Let us adjust the map logic in such a way that main character's entering a sertain region triggers the light turn on and character's leaving this region triggers the light turn off.

For this test of logic you will need a map consisting of six objects:

  • Landscape (HeightmapTerrain).
  • Sky (SkyDome).
  • Directional-light source (Light).
  • Spawn point (SpawnPoint).
  • Region (Region).
  • Spot-light source (Light).
Карта для теста логики
You can learn how to create maps here.

There are two objects of interest here: Region and spot-light source. You will be applying the map logic to them.

Let us start with launching the Logic Editor. Press the Logic Editor button in the World menu.

Logic24.jpg

Your goal is to create a subclass for the class Region. Add a class by right-clicking the Map Classes element of the Class List and selecting the Create Class button.

Logic25.jpg

In the class creation window you have to enter the name of a new class (for example Region_0), select the Entity type for this class and chose the base class Region. After doing this press Ok.

Logic26.jpg

The new class has ben added to the class list. The next step is to add methods to the class. Let us start with a method responsible for characters arrival to the region. Right-click on your class and select the Create Method option. Choose the ObjectIn method from the method list (it is activated when a character enters a region). Finally, chose the Designer Type method creation mode.

Logic27.jpg

Now you have to make the method turn the light on. To do this add a command by pressing the Insert button above the Actions list.

Logic28.jpg

To get an access to the light source you will need the GetEntity function. Double-click it.

Logic29.jpg

The parameter of the GetEntity function is null. Change it by clicking it.

Logic30.jpg

The object you need is the spot-light source which in this case is called Light_0.

Logic31.jpg

Now turn to the DiffuseColor property of the light source. To do this you have to click on [...].

Logic32.jpg

Double click the DiffuseColor property in the list.

Logic33.jpg

Now assign a value to the light source. Add a binding statement by clicking [...].

Logic34.jpg

And adding the = statement by double-clicking it.

Logic35.jpg

Now, you have to enter the value. Chose the argument null.

Logic36.jpg

The color of the light source is a value of the ColorValue type. To create a new value of this type the ColorValue type from theStatic Members list. Now chose the ColorValue function (you need one with the following pearameters: r, g and b).

Logic37.jpg

The light should be bright when the character enters the region, so make the light source color white by setting all color components to 1. To do this, chose the first parameter null.

Logic38.jpg

Double-lick the Constant element. The default value is 0. Click it to change it to 1.

Logic39.jpg

Do the same thing with the other two color components and press the Ok button.

Logic40.jpg

Press Ok in the remaining windows to finish the command creation.

Logic41.jpg

You have completed the creation of an event triggered as the character enters a region. Now you have to make reverse operation for the character leaving the region. You will have to use the ObjectOut function. Moreover, since the light will be turned off all the color components have to be set to 0.

Logic42.jpg

Do not forget to save the map and its logic.

Logic43.jpg

Now move to the Map Editor window to add the logic class we created to the region. Select a region on the map and set the parameter LogicClass for it.

Logic44.jpg

Choose the Region_0 class in the list and press Ok.

Logic45.jpg

The last step is to make the light sourse turned off (i.e. black) so that we can see the color change when the event is triggered.

Logic46.jpg

Now start the map in simulation mode to see the result.

Logic47.jpg

When the character enters the region the light turns on and it turns off when the character leaves. So the logic is working!

Персонаж вне региона Персонаж внутри региона

Tutorial: Script Type

In this tutorial you will examine the resourses of the Script Type mode of the Logic Editor. The same map as in the previous tutorial will be used and as in the previous tutorial we will be using events triggered by the character entering and leaving the region. However, this time the light source will be slowly changing its color.

Start with the creation of a subclass for the class Region. Add a class by right-clicking the Map Classes element of the Class List and selecting the Create Class button.

Logic50.jpg

In the class creation window you have to enter the name of a new class (for example Region_0), select the Entity type for this class and chose the base class Region.

Logic51.jpg

To control the light sourse you have to check if the character is in the region. Create a variable for this by right-clicking on the Region_0 class and selecting the Create Variable option.

Logic52.jpg

Set the variable type to Boolean (logical type with two possible values: True or False). The name of the variable will be characterInRegion.

Logic53.jpg

After having created a variable add a control of its value. When the character enters the region the ObjectIn event is triggered. Add the corresponding function to the Region_0 class. Right click on the class and chose the Create Method menu. Then choose the Script Type method for the ObjectIn event.

Logic54.jpg

When the character enters the region the value of the characterInRegion variable should be changed to True. Write the following code in the working window:

characterInRegion = true;

Now you have to track a reverse event when the character leaves the region. You have to change the variable value to False and turn the light source off. Add an ObjectOut function to the Region_0 class and write the following code in the working window.

characterInRegion = false;
((Light) Entities.Instance.GetByName( "Light_0" )).DiffuseColor = new ColorValue(0, 0, 0);

Now the most interesting stuff! You have to make the light sourse color change with every tick. While the character is staying within the region the light sourse will be slowly changing color from green to red. An evet which is triggered every tick is the Tick method. Add it to theRegion_0 class ad type the following code.

if(characterInRegion)
{
	float t = (((int)(EngineApp.Instance.Time * 1000)) % 3000) / 3000.0f;
	float r = -4 * t * t + 4 * t;
	float g =  4 * t * t - 4 * t + 1;
	((Light) Entities.Instance.GetByName( "Light_0" )).DiffuseColor = new ColorValue(r, g, 0);
}

The color is changing is cycles. The number 3000 is the color change period in milliseconds.

Save the map logic with File -> Save Map.

Logic56.jpg

Now you only have to set a logic class for the object Region. To do this go to the Map Editor, select a region and choose the LogicClass parameter.

Logic57.jpg

Choose the Region_0 button and press Ok.

Logic58.jpg

Start the map in simulation mode.

Logic47.jpg

After having entered the region you will see the light sourse slowly changing color.

Источник света горит красным цветом