Guides:How to script in GearHead

# Introduction

Writing plots for Gearhead or Gearhead II requires the use of Gearheads internal scripting language. The macros and variables that make up the internal scripting language are a lost art known only to the citizens of Hwang-Sa temple, and the rare few who read the Reference files and study the original game Plots and Story arcs. This guide is to help those who come after to follow the same path into mystery and wonder.

## Learning the Internal Scripting Language

The easiest way to learn the scripting language is to read the reference files available in the Gamedata folder, and study the original plots, then try writing your own. However, not all of the macros are documented in the Reference files, or easily decipherable, and this Guide will attempt to provide definitions and examples of use for as many as possible.

*[Editor note: For those unfamaliar with different styles of programming, Gearhead uses a variation of Polish Notation or Prefix Notation. The operands (What is being done) is preceeded by the operator. Understanding this may help a writer keep track of variables and which functions get processed in what order. - Johnny]*

## The Reference Files

#### Doc Folder

The files available in the Doc folder of Gearhead 1 that are particularly relevant are:

ASL\_Reference.txt
A seperate file from the one below and only included with the Source release. Contains an explaination of some of the ASL functions listed below.
ASLref.txt
ASLMessages.txt
A file containing a brief explaination of how to write dialog for scripts.
MDLref.txt
This file contains brief explainations of some of the values and functions used in the Mecha Design Language. More for design file creation than scripting.
Typelist.txt
This file contains the variable identifiers for a variety of low-level functions. If you're brave enough to attempt to script with the lower-level macros this file is useful to help remember which number affects what part of a gear.
Terrainlist.txt
Not just a clever name, this file lists the identifier for each of the 42 terrain types.
#### GameData Folder

The files available in the Game Data folder of Gearhead 1 that are particularly relevant are:

ASLmacro.txt
The actual higher level macros used in the Arena Scripting Language. Made by stringing together the lower level hardcoded macros, with practice you can even add to this file to create new scripting macros. (Lots of practice.) Reading this file can help figure out what variables a particular macro needs to function properly.
ASVmacro.txt
Similiar but very different to the above, this is the macro file for the ArenaScript Variables. Very useful for figuring out how to call specific pieces of information.
GHPmacro.txt
Again a collection of macros, these are lower level macros for use with the GearheadParser, the section of the program that controls and builds the mecha/gears themselves.
sdl\_colors.txt
This file lists all the standardized colors used in Gearhead. It could possibly be added to if you wish to have additional standard colors to choose from, although I'm unsure as to the exact function of the prefix to each color. The three numbers in brackets are the identifier of the color, and useful if you want to write a SDL\_Color <? ? ? ? ? ? ? ? ?> tag for a mecha design file. Alternatively you can simply use Cosplay to check what the correct numbers for a color are, but this may be faster.
Randmaps.txt
Gives the names of each of the predefined Map Types for use with random generated maps (either dynamic or Scene). Also shows the Gapfill line for each, which shows which types of terrain to fill the map with.
#### Series Folder

The files available in the Series folder most likely to be useful:

ADV\_FederatedTerritories.txt
The ADV file is the main plot of the game. It is the first script loaded when you start an new adventure. It contains examples of almost anything you can do with the scripting language.
ANPCdefault.txt
The default NPC's that are called in other scenes by using the NPC string. Useful for adding new default NPC's, or checking the base stats of an NPC type that you want to use.
RCjobs.txt
The careers available to a starting character. Determine what skills a character starts with. Can be added to.
STCdefault.txt
A large list of generic and default equipment. Useful because using the STC string can easily be called within a script, rather than having to always set an Element for each item.
Wmondefault.txt
The random monsters of Gearhead. More is always better.
## The First Step

Is understanding that there is no spoon. Then understand that anything that can be named in Gearhead is an object, called a Gear in most of the reference notes, most often existing as a subcomponent of another larger Gear, and with other Gear existing either as a component of that root Gear, or in its inventory. This is true of all Personas, Plots, Mecha, Weapons, NPCs, and Monsters. Anything you can put a name to, even the main Plot itself!

As an example, imagine that the world/main plot of Gearhead is itself a giant mecha (Perhaps standing on the back of an infinite series of turtles, that's not important.) That giant mecha would be the ADV\_FederatedTerritories.txt file in Gearhead 1. This is the first file the game looks to for scripting to tell it what to do after you start a new game. All of the set pieces, such as Town and Dungeon scenes, exist as subcomponents of that giant mecha, like installed parts. And in those subcomponents are subcomponents of their own, the buildings in the town, the personas of the NPC's (but not the NPC itself), etc all the hardwired stuff. Still at the same level as the town are the 'Equipped items' that are in inventory, the NPC bodies, items on the ground, the things moving around or sitting 'on top of' that Gear.

Again, experience will help you to understand this analogy and apply it to writing script. The important thing for now is to remember to always close your tags. If you write Sub or Inv, always make sure there is an End that goes with it. Otherwise you get the Scene that never ends, it just goes on and on my friend...some people started writing it not knowing what it was, and they'll....I'll stop now. Sorry.

## The Types of Script Files

Any text file that the program looks at to create in-game content is script file. The Mecha Design files, the PCEquip and MekEquip files, NPCDefault and STCDefault, and even the main ADV file itself are script files chock fully of scripty goodness. While you may eventually want to add modifications to those files, the majority of scripting a fan-author will be doing will be on the following types of files:

Plot Files (Plot\_\*.txt)
These files are the majority of missions in the game. When looking for random plots to load the game picks from plots text files that use this naming convention. For some tips on how to write Plots see here.
Scene Files (Scene\_\*.txt)
These files are not generally randomly pulled from (although the format Scene\_NameofScene\_\*.txt could be used to call a random scene from a set of similar scenes such as Scene\_NameofScene\_1.txt Scene\_NameofScene\_2.txt etc). Instead this is a naming convention for a specific type of script file for Scenes that can be called from plots or stories in-game. These are used to create specific maps (although they still contain random elements) for a mission or encounter. Scenes can include NPCs, Monsters, and Mecha elements, allowing them to be stocked either internally or from the calling Plot.
Map Files (Map\_\*.txt)
These files are specific set maps, without randomization. They contain only the terrain itself. They can be used by either a plot called encounter or inside of a Scene file to set the terrain for the encounter, but do not contain any monsters or other features besides terrain by themselves.
The Others
There are other file types in the Series directory that deal with plots, mostly TS\_\* and TS\_XRAN\_\* text files. These files are specifically called by the main ADV file (rather than randomly chosen like Plot\_\* files) for specific factions or encounters. The XRAN files in particular relate to the main story of the game. Beginners should stick to writing standard random plots before exploring the TS\_\* files.
## The Different Types of Macros

A macro is a single word or phrase that the script reads to create several effects at once. As an example from the aslmacro.txt file in the GameData folder:

```
V= <GrabSource             GSetNAtt NAG_ScriptVar ? ?>

```

Entering V= in a script will Grab the calling source of the script (Grabsource being a hardcoded macro written into the game function) then do two things, first it declares that it is going to set a numeric variable {GSetNAtt} then it declares what to set it to. The two question marks signify variables that need to be set when using the macro.

As an example of this example, to use this macro (which will be used quite a lot) one would enter:

```
V= 1 1

```

This sets the numeric variable 1 of the calling source equal to 1.

Trust me, it's simpler when you're doing it.

### Lists of Macros

Arena Scripting Language Macros
These are the majority of the commands and triggers used in scripting.
Arena Scripting Value Macros
The scripting values are the variables that get referenced regularly in scripting.
GearHeadParser Macros
These are the common Gear types, such as Melee, Gun, BodyArmor, etc.
### Specific Definitions

Specific definitions of, and links to more information on, some of the more difficult macro/script concepts.

Elements
Elements are basically a specific set of variables that is declared at the beginning of scene or plot gears. They can be Scenes, Characters, or Prefab items. This allows you to reference those characters or items in the script without needing to know the specific UID for them.
Triggers
Triggers are commands that are set to go off if a specific circumstance is met. For instance if a specific unit is destroyed (TD), the number of units on a team chance (NU), or a member of a team moves (TM).
Type
Type is a command used to set a string of tags on a specific Gear. It is used in GH 1 to set what type of monsters will be randomly selected for a team, to set the variables for a staged Scene map, and possibly some other uses that I'm forgetting. In GH 2 it is also used with mecha gears to set which factions have access to that mecha, which makes GH 1 all kinds of jealous.
Variables
Variables are the heart and soul of Gearhead, almost every function you write will contain multiple variables. How to set and modify variables is relatively easy, but keeping track of which variable is called where, and what it relates to is critical.
## Other Functions

Name
Usage:

```
Name <TEXTHERE>
```

You can use this to set the name of a generic NPC or Monster as well as Teams in a scene.
Job
Usage:

```
Job <JOBHERE>
```

This string is used to set a Job for an NPC, basically an alternate name that can be used to Telephone them.
Chardesc
Usage:

```
Chardesc TRAITNAME TRAITNAME TRAITNAME etc
```

Example:

```
Chardesc Male Young Passionate Passionate Lawful Heroic Wangtta
```

This example would make the npc a young male with Reputation 4 (Easygoing/Passionate) -50 Reputation 2 (Lawful/Chaotic) +25 Reputation 1 (Heroic/Villianous) +25 and Reputation 6 (Renowned/Wangtta) -25
This string, which is one of the only unbracketed strings in Gearhead 1 (in fact the only one I'm aware of) sets the personality of an NPC. Each personality reputation you list adds 25 of that type of reputation, while Male, Young, Old etc set certain other parameters. Any description characteristic not set by Chardesc will be chosen randomly.
Dage
Usage:

```
Dage +/- Variable/Integer/Diceroll
```

Example:

```
Dage -d5
```

This example would lower the age of the NPC by the result of a d5 (five sided dice roll, or a random number from 1 to 5)
Adjusts the random age of the NPC.
d
Usage:

```
dINTEGER
```

Example: See above
The d function returns a random value. It is useful for creating randomized variables.
UID
Joseph Hewitt says:

> "UID is short for Unique ID. It's an identification number applied to a gear as it is deployed onto the gameboard, and is primarily used for keeping track of things like which mecha is being targeted by which character and so forth. Every time a model changes scenes it is assigned a new UID, and it doesn't get assigned this number until the scene actually begins and the combatants are deployed."
>
>

While not a function that you enter directly, this is important because several macros (in particular Takedown triggers and such) require the UID instead of Character (persona) ID. There are functions to grab the UID of a unit, but mostly just for the PC or for a random unit from a team.
Props
Props are items that act like personas, in that they can be interacted with by the PC. A Vending Machine that you can buy a sandwich from, a TV that you can turn on to recieve a news report, or a Computer that you can use Code Breaking on to recieve a clue are all props. The have a value set by the usage:

```
Prop ?
```

Which defines how much health the Prop has and how easily it will be destroyed. All interaction with the Prop has to be defines, either through the Use trigger (if the PC simply attempts to use it) or through the CLUE? function, which triggers a command line when skill ? is used on the Prop.
Clue?
This is a Trigger that tells the program what to do if a skill is used. All skills have an associated value (ranging from 1 to 42, for each of the 42 different skills) that identifies them. This trigger can be set either locally inside a Prop, or as part of a scene as follows:

```
Clue29 Print 4
```

In this example if the PC used Skill 29 (which is Science) (either on a prop if the line is local to a Prop, or on an empty hex if applied to a Scene) the program would print message number 4 in the info window.
Print ?
This command tells the program to print the msg? line in the info window, where ? is the number of the specific message (or a Variable, which allows for randomly selected dialog if you previous establish a random variable such as: V= 1 1 followed by V+ 1 d5. This example would set V1 to 1, then randomly add 1 to 5 to it, allowing you to print any message from 2 to 6 if you later used V1 with the Print command.)
Say ?
Say works like Print, except it is used inside of Character interaction dialogs. Anytime the dialog window is open and the NPC says something, it uses the Say function to pick what to say. There is a variant of Say, **SayAnything** for when no specific line of dialog is needed by the Persona. In those cases the persona says something at random, possibly including hints to available missions, local rumors, or descriptions of local NPC's.
## Hints and Tips

Items can be scaled both internally and externally, which is to say that if you call a Monster using the Monster function or perhaps a generic item using the STC phrasing you would normally get the item at the scale in which it was originally written. However, if you add the line:

```
Scale 1

```

Under it, it would be created as a Scale 1. HOWEVER, inventory and equipment inside of it would not change in scale which can cause problems. Generally it is better to simply rewrite (or copy and paste) the entire creature/item.

Always close your tags and command brackets. If there is a < there should always be a > to close it. If you write Sub or Inv, always make sure there is an End that goes with it. The most common problem in writing a plot or design file is failing to close a tag or command, making all the lines that follow try to smush into the same line until it hits a dead end or the next End line.