[Mathias]

This article is part of a collection of editor and scripting articles: http://forums.wolflair.com/showthread.php?t=21688

I decided to add an article on a topic I don't think we've covered in much detail anywhere else. The principles I'm discussing apply to all game systems in Hero Lab, but for this article I'll be drawing my examples from Pathfinder.

In a character in Hero Lab, there are many items - each attribute is an item, each feat, level of a class, archetype, weapon, etc. is its own individual item. For the rest of this article, I'll refer to them as picks.

Very often, while writing a script, you'll want to look up information on another pick (perhaps to set the number of uses equal to an attribute modifier), or you'll want to change something about another pick (like adding a bonus to a skill). I'll be discussing how to travel around the set of picks that make up your character and the sorts of things you can do once you get somewhere and that sorts of questions you can ask once you get there.

In Hero Lab's scripting language, the period: . is used as the transition from one place to another. You are allowed to make more that one transition in a row - it's actually very common to use many transitions in a row in order to travel from one pick to another.

Every pick in a Hero Lab character is stored within a container. 98% of the picks in a character will be in a container called "hero", and there's only one "hero" container for each character. The rest will be in containers called gizmos - those are containers that exist within other picks. Each pick can only have one gizmo, and most picks will not actually have a gizmo. Gizmos are used in cases where at item is customizable - the custom versions of armor, weapons, scrolls, potions, wands, spells, and wordspells.

Although I'm using the term container here, that isn't actually related to what you'd commonly call a container - things like backpacks and houses. If you tell Hero Lab that the group of alchemist's fire bottles you own should be stored within your belt pouch, it doesn't change the underlying container for either the alchemist's fire or the belt pouch. What it does do is to set up a new relationship between the alchemist's fire and the belt pouch. Within the scripting language, that relationship is referred to as gearholding, and I'll cover that later in this article.


Let's take a look at some transitions:

hero.child[skClimb].field[Bonus].value

Breaking that down:

hero
.
child[skClimb]
.
field[Bonus]
.
value

So, what that's saying is: first, travel to the hero, then travel to the child of the hero whose Id is "skClimb" (which is the climb skill), then travel to the field on that child whose Id is "Bonus" (which is for untyped bonuses), then report the value of that field.

Here's how you might use that:

hero.child[skClimb].field[Bonus].value = hero.child[skClimb].field[Bonus].value + 2

Or in other words: "set the untyped bonus of our climb skill equal to whatever bonus has already been applied, + 2". Or, "You get +2 to climb."

That one's actually so commonly used that we've added some abbreviations, so that it takes less typing to get the same effect:

#skillbonus[skClimb] += 2

Example #2:
hero.child[skClimb].tagis[Helper.ClassSkill]

hero
.
child[skClimb]
.
tagis[Helper.ClassSkill]

In other words: "travel to the hero container, and then to the climb skill pick that's in that container, and then report whether a Tag whose Id is "Helper.ClassSkill" is present on that pick". In simpler terms: "Is climb a class skill right now?"

tagis[], like all the other TRUE/FALSE questions in Hero Lab, will report it's answer in the form of a number. It will report "0" if the answer is FALSE, and "1", if the answer is "TRUE".


Example #3:
field[usrChosen1].chosen.field[skRanks].value

field[usrChosen1]
.
chosen
.
field[skRanks]
.
value

That's saying: travel to the field (on us) called "usrChosen1" (which stores the user's choice from a drop-down menu), then travel to the pick the user chose, then travel to the skRanks field on that pick (which tells you how many ranks the user has applied to that skill), and report the value of that field.

Here's how you might use that:

 if (field[usrChosen1].ischosen <> 0) then
  if (field[usrChosen1].chosen.field[skRanks].value >= 10) then
    field[usrChosen1].chosen.field[Bonus].value += 6
  else
    field[usrChosen1].chosen.field[Bonus.value += 3
    endif
  endif

"Travel to the drop-down menu on us - has the user selected a skill yet? If so, travel to the skill they selected - does that skill have 10 ranks in it yet? If so, add an untyped bonus of +6 to that skill. If not, add an untyped bonus of +3 to that skill." aka the Skill Focus feat.

Example #4:
hero.findchild[BaseRace].field[livename].text

hero
.
findchild[BaseRace]
.
field[livename]
.
text

That's saying: Travel to the hero container, then search among all the picks in that container for the first one you find that uses the BaseRace component, then travel to the livename field on that pick (livename stores the version of the name that will be displayed to the user), and report the text stored in that field.

Here's how that might be used:

hero.findchild[BaseRace].field[livename].text = "Mountain " & hero.findchild[BaseRace].field[livename].text

"Find our race and change its name to 'Mountain ' and whatever name is already there" ("Dwarf" would become "Mountain Dwarf", for example) (note the space in 'Mountain ', so that you don't get 'MountainDwarf'). This might be used by an Alternate Racial Trait, to rename its race.

In the next few posts, I'll look at each of the types of locations you might visit, and list where you can go from there, what questions you can ask while you're there, and what orders you can give Hero Lab while you're there.

If you're writing an Eval Script or an Eval Rule, you'll start out in the pick context. If you're writing a Prereq or an Exprreq, you'll start out in the container context (either hero or gizmo, depending on what container this item will be in once it's added).