Difference between revisions of "Golem Agent Language"

From Oldunreal-Wiki
Jump to navigation Jump to search
(→‎File structure: Slight expansion)
(→‎File structure: Large expansion)
Line 35: Line 35:
== File structure ==
== File structure ==


GAL script files are divided into several different sections - ''channels'', ''inputs'', one or more ''action'', optional ''transition'' and optional ''test''.
GAL script files are divided into several different sections - ''channels'', ''inputs'', one or more ''action'', optional ''transition'' and optional ''test''. A section is a logical block for doing a specific task.


GAL uses '''keywords''', symbols, ''identifiers'', <span style="color:darkgreen">numbers</span> and <span style="color:darkorange">"strings"</span>. Whitespace is ignored. Identifiers (user-defined names) are case-insensitive, but must start with either a letter or an underscore, and the rest of the identifier should be comprised of digits, letters and underscores only.
GAL uses '''keywords''', symbols, ''identifiers'', <span style="color:darkgreen">numbers</span> and <span style="color:darkorange">"strings"</span>. Identifiers (user-defined names) are case-insensitive, but must start with either a letter or an underscore, and the rest of the identifier should be comprised of digits, letters and underscores only.
 
Whitespace is ignored. The symbols <span style="color:darkred">//</span> are used for writing comments - anything on the line after them will be ignored. <span style="color:darkred">/*</span> and <span style="color:darkred">*/</span> are used to indicate block comments – everything in between them will be ignored.


Numbers can be in different forms - integer numbers (0, 1, 2), floating-point numbers (0.1, 1.6, 2.85) or boolean values (0 or 1). If a float is expected, an integer is accepted as well (it's typecast automatically). If a boolean is expected, only 0 (for false) and 1 (for true) are accepted.
Numbers can be in different forms - integer numbers (0, 1, 2), floating-point numbers (0.1, 1.6, 2.85) or boolean values (0 or 1). If a float is expected, an integer is accepted as well (it's typecast automatically). If a boolean is expected, only 0 (for false) and 1 (for true) are accepted.
== Channels section ==
'''channels'''
{
    ''channelname'';
    ''channelname'';
    ...
}
The first section is called ''channels''. This section identifies the names and the order of the entity script processes used by the agent. Each agent must have at least one defined, and the order is important. Usually channels are used to isolate animations that don't interfere with other animations (so that the entity could blink while walking, for instance). After defining them, these channel names can then be used in ''set'' and ''force'' blocks (see below).
Example:
'''channels'''
{
    ''AnimAll'';
    ''AnimUpper'';
    ''AnimLeft'';
    ''AnimRight'';
    ''AnimBlink'';
    ''AnimBrow'';
    ''AnimCheeks'';
    ''AimHead'';
    ''AnimHead'';
}
== Inputs section ==
'''inputs'''
{
    ''inputname'' = ''inputvalue'', ''inputvalue'', ...;
    ''.localinputname'' = ''inputvalue'', ''inputvalue'', ...;
    ''inputname'' = ''inputvalue'' <span style="color:darkorange">"stringalias"</span>, ''inputvalue'' <span style="color:darkorange">"stringalias"</span>,  ...;
    ''.localinputname'' = ''inputvalue'' <span style="color:darkorange">"stringalias"</span>, ''inputvalue'' <span style="color:darkorange">"stringalias"</span>,  ...;
    ...
}
The ''inputs'' section is in essence the "variables" block of GAL scripts. You can define any number of ''inputs'' here. Inputs are in essence arrays of identifiers. Any inputs defined here will be shown in the [[Golem Studio#Inputs tab|''Inputs'' subtab]] in the ''Agent'' tab in Golem Studio. Each input must have one name, and can have an unlimited amount of values. The order of the values matters in that the order will be presented as-is in Golem Studio, and the first value will be set by default.
Each value can have an optional string alias. They are defined just after the value (and enclosed in quotes, as it is a string and not an identifier). It is used by ''str'' blocks; see below.
As mentioned, inputs act very similarly to variables. Just like variables, they can be global or local. In case of GAL, there is an important distinction – global inputs can be written to only by the user in Golem Studio or the game logic, but not by anything within GAL scripts themselves (except for the ''test'' block, see below). Local inputs are the opposite, they cannot be written by the game logic, but can be written by assigning them within GAL scripts. As for reading them, both local and global inputs can be read anywhere at any time.
To define an input as local, you need to prefix its name with a period character (.). If there is no period character before an input name, it is automatically defined as a global input. Note that the period character is not part of the input name, you don't need to enter it if you are checking the value of local inputs.
Example:
'''inputs'''
{
    ''Speed'' = ''Walk'', ''Run'';                                            <span style="color:darkred">//Global (external) input, "Walk" is default</span>
    ''Mood'' = ''Good'', ''Bad'', ''Ugly'';                                        <span style="color:darkred">//Global (external) input</span>
    ''.Flavor'' = ''Chocolate'' <span style="color:darkorange">"Choc"</span>, ''Vanilla'' <span style="color:darkorange">"Vanl"</span>, ''Strawberry'' <span style="color:darkorange">"Swbr"</span>; <span style="color:darkred">//Local (internal) input with string aliases</span>
    ''.Stooge'' = ''Larry'', ''Curly'', ''Moe'', ''Shemp'';                            <span style="color:darkred">//Local (internal) input, access it by name "Stooge" and not ".Stooge"</span>
}
== Action sections ==
'''action''' ''actionname''
{
    ''statement''
    ''statement''
    ...
}


[[Category: Unreal II]] [[Category: Golem]] [[Category:Mods]] [[Category:Scripting]]
[[Category: Unreal II]] [[Category: Golem]] [[Category:Mods]] [[Category:Scripting]]

Revision as of 13:03, 14 July 2012

The Golem Agent Language (GAL) is a fairly simple text-based scripting language that is used by the Agent objects in Golem Studio of Unreal II. It is required in order to create functional Golem Entity Script Agent objects.

Overview

Agent overview

An Entity Script Agent is an object that acts as an intermediary between an entity and its Entity Scripts objects. Note that GAL scripts should not be confused with Entity Scripts (the former controls Entity Script Agent object logic, the latter define a static set of animations). The name "Agent" stems from the fact that Entity Script Agents are a higher level of abstraction than Entity Scripts, and entities normally access scripts through agents, and not directly.

While agents are entirely optional for having a working entity, agents make animating entities a lot easier. They dynamically combine different static scripts to a whole dynamic set of animations. Using Golem Studio you can easily see the difference between using entity scripts directly and using agents by enabling and disabling Agent mode in the Render window.

Agents vs Entity Scripts

There are numerous advantages of using agents as opposed to entity scripts, and especially pure animations, directly. As a comparison, games like Unreal Tournament 2004 use pure animations for all the animation needs. Compared to that system, Entity Scripts are a low more powerful, as they not only play preset animations, but also allow you to combine these pure animations with dynamically generated animations, such as surface walkers, vertex explosion effects, lipsync curves, etc. (see Abilities for a complete list), and combine several of these static or generated animations into one, with specifically set timings and external events, if needed. That alone makes the system a lot more powerful than pure animation-based solutions. However, entity scripts are still inherently static - when replayed, they will look the same every time.

Agents, on the other hand, add even more power to the system by allowing to control several different scripts at the same time with added randomness, conditions, etc. With both pure animation and Entity script systems, making an entity that can walk to all eight sides would require you to create 8 different animations/scripts. If you want to have four weapon carrying poses? You have to make 32 animations/scripts. And making the entity blink naturally during those animations would be outright impossible. Agents, however, allow you to do all of this with relative ease. Plus, agents allow for defining random events - such as playing one of the different idle animations. In pure animation solutions, that functionality was put on the shoulders of UnrealScript coders, while with Agents it can be defined by animators themselves. And that's not all - agents also allow fine control over how different scripts interact with each other under different circumstances, such as blending two animations with each other if the first animation has played over 50% of its animation.

Overall agents allow for a much easier and more precise control over how an entity should animate, without even having to interact with the game logic itself. That in itself allows for more productive separation of work - coders are no longer required to bother with all this animation business, while animators get all the control they need.

Language complexity

While the notion of needing to learn a programming language just to animate an entity can seem daunting, it is not that difficult in terms of GAL scripting. GAL is centred around a single task, instead of being multi-purpose, therefore the overall complexity is reduced. And it sure is a lot less difficult than other artist-centred languages, like 3DS MAX's MAXScript or Blender's Python. As a matter of fact, looking over an example GAL script even without knowing the specifics should make it clear how the language works.

Text vs graphical interfaces

While Golem Studio was generally created as an abstraction that allows for a more intuitive way of handling animations than working with code directly (once again, like it is the case with games that depend on pure animations), it may come as a surprise why GAL was not made into a visual tool and instead kept in text form. As a matter of fact, it was attempted to make it visual, but it was deemed too impractical and subsequently the idea was dropped. The GAL language itself was created specifically for this task. The possible complexity of input with GAL scripts is unlimited, while with a graphical tool the system would get cluttered and confusing very fast, unless it was artificially limited. In the end, this question boils down to the text versus graphical programming debate, and for this purpose a text-based approach proved to work better.

Import process

Importing GAL script files to Entity Script Agent objects is done via the context menu in Golem Studio. See the corresponding page for more information about that.

During the import process, Golem Studio checks whether the GAL script in question are syntactically and semantically valid. You cannot import invalid files. In case of an error, it will be printed in the log window.

Note that these checks do not guard against logical errors, so you should thoroughly check your scripts for any mistakes. The test section can be used to ease this process. The Immediate action box in Golem Studio also allows for quick debugging of small script parts. Testing more inside Golem Studio allows for less time needed for the reimporting routine.

File structure

GAL script files are divided into several different sections - channels, inputs, one or more action, optional transition and optional test. A section is a logical block for doing a specific task.

GAL uses keywords, symbols, identifiers, numbers and "strings". Identifiers (user-defined names) are case-insensitive, but must start with either a letter or an underscore, and the rest of the identifier should be comprised of digits, letters and underscores only.

Whitespace is ignored. The symbols // are used for writing comments - anything on the line after them will be ignored. /* and */ are used to indicate block comments – everything in between them will be ignored.

Numbers can be in different forms - integer numbers (0, 1, 2), floating-point numbers (0.1, 1.6, 2.85) or boolean values (0 or 1). If a float is expected, an integer is accepted as well (it's typecast automatically). If a boolean is expected, only 0 (for false) and 1 (for true) are accepted.

Channels section

channels
{
    channelname;
    channelname;
    ...
}

The first section is called channels. This section identifies the names and the order of the entity script processes used by the agent. Each agent must have at least one defined, and the order is important. Usually channels are used to isolate animations that don't interfere with other animations (so that the entity could blink while walking, for instance). After defining them, these channel names can then be used in set and force blocks (see below).

Example:

channels
{
    AnimAll;
    AnimUpper;
    AnimLeft;
    AnimRight;
    AnimBlink;
    AnimBrow;
    AnimCheeks;
    AimHead;
    AnimHead;
}

Inputs section

inputs
{
    inputname = inputvalue, inputvalue, ...;
    .localinputname = inputvalue, inputvalue, ...;
    inputname = inputvalue "stringalias", inputvalue "stringalias",  ...;
    .localinputname = inputvalue "stringalias", inputvalue "stringalias",  ...;
    ...
}

The inputs section is in essence the "variables" block of GAL scripts. You can define any number of inputs here. Inputs are in essence arrays of identifiers. Any inputs defined here will be shown in the Inputs subtab in the Agent tab in Golem Studio. Each input must have one name, and can have an unlimited amount of values. The order of the values matters in that the order will be presented as-is in Golem Studio, and the first value will be set by default.

Each value can have an optional string alias. They are defined just after the value (and enclosed in quotes, as it is a string and not an identifier). It is used by str blocks; see below.

As mentioned, inputs act very similarly to variables. Just like variables, they can be global or local. In case of GAL, there is an important distinction – global inputs can be written to only by the user in Golem Studio or the game logic, but not by anything within GAL scripts themselves (except for the test block, see below). Local inputs are the opposite, they cannot be written by the game logic, but can be written by assigning them within GAL scripts. As for reading them, both local and global inputs can be read anywhere at any time.

To define an input as local, you need to prefix its name with a period character (.). If there is no period character before an input name, it is automatically defined as a global input. Note that the period character is not part of the input name, you don't need to enter it if you are checking the value of local inputs.

Example:

inputs
{
    Speed = Walk, Run;                                             //Global (external) input, "Walk" is default
    Mood = Good, Bad, Ugly;                                        //Global (external) input
    .Flavor = Chocolate "Choc", Vanilla "Vanl", Strawberry "Swbr"; //Local (internal) input with string aliases
    .Stooge = Larry, Curly, Moe, Shemp;                            //Local (internal) input, access it by name "Stooge" and not ".Stooge"
}

Action sections

action actionname
{
    statement
    statement
    ...
}