HLKitWiki - User contributions [en]

Checkbox Element (Data)

2009-03-12T22:57:47Z

Mathias: /* The "checkbox" Element */

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "checkbox" Element==

The "checkbox" element is useful whenever the user has a choice between two clearly opposite states, such as on/off, enable/disable, show/hide, etc. In addition to the traditional visual presentation of text with a box next to it, the Kit allows you to use checkboxes to present to alternate visual states. For example, within the World of Darkness data files, the abilities to promote items to the top of a list and toggle inclusion within printouts are checkboxes that merely toggle between two states and change the visuals accordingly. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|field
|Id – Specifies the unique id of the field whose contents dictate whether the checkbox is in the on or off state. The field must be a value-based field, with a non-zero value indicating "on" and a zero value indicating "off". The field must exist within the pick/thing associated with the containing template. If this portal is not defined within a template, a checkbox is not allowed.
|-
|message
|(Optional) Text – Specifies the message text to display next to the actual box. If empty, no text is displayed. Default: Empty.
|-
|dynamicfield
|(Optional) Id – Specifies the unique id of a different field from which the message text will be pulled. This allows the message text to be dynamically determined via scripts. If empty, no dynamic field is specified. Default: Empty.
|-
|readonly
|(Optional) Boolean – Indicates whether the checkbox portal is unable to be changed by the user. Default: "no".
|-
|}

==Example==

The following example demonstrates what a checkbox portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="name" style="chkNormal" showinvalid="yes"
tiptext="Click to equip this weapon">
<checkbox field="grIsEquip" dynamicfield="grStkName"/>
</portal>
</pre>

Home

2008-12-31T00:23:20Z

Mathias: /* Welcome to the Hero Lab Authoring Kit Wiki */

==Welcome to the Hero Lab Authoring Kit Wiki==

The Authoring Kit for Hero Lab provides a vast array of capabilities, and those capabilities will continue to evolve with the product. As such, we needed a means of documenting all those capabilities that could readily adapt and evolve as well. We concluded that the best way to accomplish this is to create a wiki that we can extend on an ongoing basis. As an added bonus, the wiki can also enable users to share tips and suggestions.

If you are not familiar with wikis, you can think of them as an intelligently structured assortment of web pages. For information on using this wiki, please refer to the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide].

Wikis are designed to be easily searched, so you can enter whatever term you are interested in and quickly find all the various entries pertaining to that topic. This will be invaluable as you become proficient with the Authoring Kit and want information on specific capabilities. Until you reach that point, you can simply start with this page and follow the various links below to read through all the various topics.

==Introduction to the Kit==

The goal of the Authoring Kit is to provide everything you need to create and/or edit data files for Hero Lab. When adding material to an existing game system, you can typically utilize the integrated Editor within Hero Lab. However, if you want to create data files for a new game system, you can use the information provided in the Authoring Kit to achieve that objective.

Hero Lab is the first tool that offers a versatile enough engine to handle all the complexities of virtually every RPG system. There is no practical way to develop an engine that inherently handles all this complexity without putting a substantial amount of power and flexibility in the hands of the data file author. With that power and flexibility comes a great deal of material to digest, though, which can make the Authoring Kit seem daunting at first.

To compensate for this, we've invested a great deal of time and effort to simplify and streamline everything, which extends well beyond just refining the engine and how everything works. The documentation is structured to introduce you to concepts in an incremental fashion and make it easy to find the information you need. We've provided a fully operational set of data files as a starting point for your own projects that can be readily adapted to any game system. We've even included a complete walk-through that details how to transform the starting data files into a full-fledged implementation of the Savage Worlds game system.

It's our sincere hope that you'll find the Authoring Kit reasonably straightforward to use and that we've made it possible for you to create quality data files for all your favorite games.

==Documentation Conventions==

For brevity, the Authoring Kit will often be referred to as simply the "Kit" and Hero Lab will typically be referred to as "HL".

Within the Kit documentation, there are a few conventions utilized. Anytime that important points arise within the text, they will be flagged appropriately using one of the techniques below.

:{| class="infotable"
|class="leftnormal"|{{warning}}
|Used to flag the most critical items, which have significant impact on the usability and maintainability of your data files
|-
|{{important}}
|Identifies considerations that impact the way in which you create your data files, but the results won't usually be horrible if you ignore them
|-
|{{note}}
|Indicates topics that may influence your choices in data file creation in some situations
|-
|}

==PDF Available==

The Kit documentation is also available in PDF format for offline reference. The PDF version requires Adobe Acrobat Reader to view. You can download the PDF document via the link below.

[http://www.wolflair.com/download/hp/hl_kit.pdf http://www.wolflair.com/download/hp/hl_kit.pdf]

{{important}}The PDF version will usually '''not''' be as up-to-date as the online wiki, since the wiki is updated on an ongoing basis and the PDF version is updated only periodically. If there is a discrepancy between the PDF and the wiki, always treat the information here in the wiki as the most accurate.

==Data File Authoring Topics==

Each of the topics below will take you to detailed documentation on the corresponding facet of the Kit. A brief summary of each section is provided below as well. It is highly recommended that you start with the first topic in the list and work your way downward, just like you would normally read the chapters of a book in the sequence they appear within the book. Most chapters build upon the material from previous chapters, so skipping material may lead to some level confusion.

{{important}}The Authoring Kit documentation is a work-in-progress and will continue to be expanded as the capabilities of the product continue to evolve. We've mapped out an extensive long-term plan for both the product and the documentation, and the general structure can be seen herein. However, many sections have not yet been written. These sections will appear as <span class="important">red links</span> throughout the documentation and will be added over time to complete the documentation.

==={{fl|Basic Concepts and Terminology}}===

This section covers all of the fundamental topics that the Authoring Kit is built upon. It's critical that you are familiar with all of these topics before continuing with the other sections.

==={{fl|Advanced Authoring Concepts}}===

Building on the basic concepts, this section outlines more sophisticated mechanisms that you will likely want to leverage.

==={{fl|Kit Reference}}===

Details regarding the syntax and structure for every facet of the Kit are spelled out in this section.

==={{fl|Authoring Examples}}===

This section provides concrete examples showing how to add a wide range of features to your data files. This includes a walk-through that details creation of a complete set of data files for the Savage Worlds game system.

===Techniques and Solutions {{tbd}}===

Hero Lab offers a vast array of different capabilities, with different features being appropriate for different game systems. This section provides a laundry list of how to integrate the various mechanisms to tailor your data files to a particular game system.

===Skinning the Interface {{tbd}}===

The Kit provides you with the ability to completely change the visual look and feel of your data files. Once the basic functionality is in place, you can adapt the visuals however you like, just like has been done for the games Mutants & Masterminds and World of Darkness.

===User Tips and Suggestions {{tbd}}===

This section outlines an assortment of tips and suggestions that have been submitted by other users.

==Legal Details==

Hero Lab is Copyright © 2006-2008 by Lone Wolf Development, Inc. All rights reserved. Hero Lab and the Hero Lab logo are registered trademarks of Lone Wolf Development, Inc. Lone Wolf Development is a trademark of Lone Wolf Development, Inc. Other brand or product names are trademarks or registered trademarks of their respective holders. No challenge to the status of other trademarks is intended by their use.

==Contact Information==

Company Website: [http://www.wolflair.com www.wolflair.com]
<br>
Technical Support Email: [mailto:support@wolflair.com support@wolflair.com]
<br>
Discussion Forum: [http://support.wolflair.com support.wolflair.com]

Tag Terms

2008-12-17T20:32:47Z

Mathias: /* Explicit Scope Restrictions */

{{context|Basic Concepts and Terminology|Tags and Tag Expressions}}

==Overview==

Tag expressions are built upon individual tag terms. Within a tag expression, every term is evaluated against the tags assigned to an object. Terms can either be "simple" terms or "arithmetic comparison" terms. Every individual term yields a result of either "true" or "false", allowing the terms to be combined into more complex Boolean expressions.

==Simple Terms==

Simple terms are just that – simple. A simple term must be one of the following:

:{| class="infotable"
|class="leftnormal"|TRUE
|The literal value "TRUE" can be specified (case '''is''' important).
|-
|FALSE
|The literal value "FALSE" can be specified (case '''is''' important).
|-
|tag template
|A tag template can be specified, with the term returning a Boolean result of true or false. When a tag template is evaluated as a simple term, the result is true if the object contains one or more tags that match the tag template and false if no tags match the template.
|-
|}

==Arithmetic Comparison Terms==

There are times when you will need to identify objects which satisfy criteria that don't simply yield a "match" or "no match" result. In these instances, the object is required to comply with numeric constraints associated with the tags assigned. For example, a rule might pertain only to spells with a level of 5 or more. In situations like this, it’s not appropriate to test for all the possible values (e.g. for the proposed sample rule, you would not want to test separately for spells of levels 5, 6, 7, 8, etc.). To handle special relationships like this, tag terms can be defined using arithmetic comparisons.

Arithmetic comparison terms always take the traditional form "left oper right", where "oper" is one of the arithmetic comparison operators: '<', '<=', '>', '>=', '=', or '<>' (the last one indicating "not equal"). Both "left" and "right" must evaluate to numeric values, with the comparison term yielding a "true" or "false" result based on the relationship between the values for "left" and "right". In this type of usage, the left and right sides of the comparison must be one of the following:

:{| class="infotable"
|class="leftnormal"|integer
|A literal integer value can be specified (e.g. "1234"). Use of a literal integer value is restricted to the '''right''' side of an arithmetic comparison term only. An error occurs if a literal integer value is used on the left side. The integer value may '''not''' be negative.
|-
|count:template
|A standard tag template of the form "group.template", subscribing to the syntax set forth previously (e.g. "color.bl?"). The value generated is the number of tags that have been assigned to the object which match the template (wildcards are allowed per standard tag template syntax).
|-
|low:template
|All tags that match the specified template are identified, and an integer value is extracted from the end of each tag. The lowest (i.e. minimum) value of all tags is the value yielded. Integer value extraction is described below. Example: "low:cost.gold?".
|-
|high:template
|Identical to "low:template", except that the highest (i.e. maximum) value of all matching tags is yielded. Integer extraction is described below. Example: "high:cost.gold?".
|-
|val:template
|The first tag that matches the specified template is identified, and an integer value is extracted from that tag and returned. Integer value extraction is described below. Example: "val:cost.gold?".
{{note}}If the template matches multiple tags, there is no guarantee which tag will be retrieved, so this form should only be used when you know there is a single tag matching the template assigned to the object. Using this form is much more efficient that the "low" and "high" forms, so make use of it whenever it is safe to do so.
|-
|}

{{note}}The prefix may optionally be omitted from a tag term within an arithmetic expression. If no prefix is specified, then the default prefix of "count" is assumed. Therefore, the term "color.blue" is equivalent to "count:color.blue" within an arithmetic comparison term, such as below.

<pre>
(color.blue >= 1)
</pre>

==Tag Value Extraction==

Every tag can be converted to an integer value. Extracting an integer value from a tag utilizes the unique id of the tag and not its name. Starting at the '''end''' of the tag’s unique id, all digits are extracted until a non-digit is encountered. Those digits are then converted to an integer value. For example, integer value extraction from the tag "blue1234" would yield the value "1234". Similarly, the tag "blue5x123" would yield the value "123".

If a tag does not end in any digits, then the tag will yield "no" value, which will be treated as a value of zero when an integer value is required for the tag. For example, the tag "blue567xyz" would yield no value, since only the trailing digits are used and all earlier digits are ignored.

{{note}}Depending on the situation, there may be a critical distinction between a tag with "no" value and a tag with a "zero" value.

Be sure to keep the following issues in mind when dealing with tag values:

*Negative values are never extracted from tags, since only digits are considered when extracting the value.
*Under some circumstances, a tag will have no value and be referenced as if it has a value. Tags with "no" value are ignored in those situations (e.g. within summations and averages), while a tag with a "zero" value is processed with that value.
*An object that does not have any tags matching the specified template and for which a value is referenced will '''never''' satisfy an arithmetic comparison under any circumstances. For example, the comparison "val:attack.? < 3" will always fail for any object that has '''no''' tag from the "attack" group. Similarly, the comparison "val:attack.? >= 3" will also fail for those same objects. If an object has no value, it can never be compliant with a value-based comparison.

==Field Value Tests==

There are times when tracking a piece of information for an object really needs to be handled via a field value, yet you still need to test that state within tag expressions. One option would be to maintain both the field value and a corresponding tag that can be tested in a tag expression, but that approach quickly becomes difficult to maintain. To alleviate this, the Kit allows direct access to field values from within tag expressions.

You can reference field values using the syntax "fieldval:fieldid", where "fieldid" is replaced by the unique id of the field to access. Other than that, you can utilize field references just like any other arithmetic comparison term within the tag expression. For example, the tag expression "fieldval:strength < 10" would be satisfied if the object possesses a "strength" field and that field has a value of less than 10.

Only the fields for the appropriate object context can be referenced via tag expressions. Consequently, if the tag expression is being applied to a pick, only the fields defined for that pick can be referenced. If a field reference is used within a tag expression that either is not a pick/thing context or does not contain the specified field, a run-time error is reported to the user. If a tag expression will be used against things/picks that derive from different component sets and may not all possess a particular field, the author can include a test for the needed component within the tag expression to verify the presence of the field before accessing it. For example, if the field "foo" is defined within the "compid" component, the following syntax can be used to safely test the field value:

<pre>
(component.compid & (fieldval:foo >= 1))
</pre>

Be sure to keep the following important issues in mind when utilizing field values via tag expressions:

*Since only things and picks possess fields, access to field values will only work when the target object is a thing or a pick. There are times this might not be immediately obvious. For example, you might assume that field values can be referenced within a thing "condition" tag expression, except that the "condition" test is applied against the tags of the container, which means there is no thing/pick context to retrieve any fields from.
*In addition to a variety of standard tag expressions within a thing/pick context, access to field values can also be utilized from within most scripts. Any time that a pick target context is accessed from within a script, the "tagexpr[...]" target reference can safely utilize a field value references against the fields within that context.
*Do NOT use field value access as a crutch within tag expressions. Field value access from tag expressions is significantly more expensive to process than testing a tag, so use tags whenever possible and only use field values when absolutely necessary.

==Explicit Scope Restrictions==

While not common, situations will arise where you'll want to test the tags of a thing/pick and the tags of the hero to determine whether a tag expression should be satisfied. For example, consider a situation where an assortment of things is only available if the actor belongs to a particular group of classes. Assuming those classes assign an identifiable tag to the actor, you could filter the things displayed based on the presence of appropriate tags on the things and the tag on the actor.

To support these situations, any tag template used within a tag expression can specify a prefix of "hero#" on the template. When this prefix is assigned, the tag template is compared directly against the tags of the containing hero context, even if a pick or a child container is the established context. For this to work, the prefix must appear immediately prior to the tag template, such as in the examples below.

<pre>
group.tag & hero#group.tag
</pre>

OR

<pre>
val:hero#group.tag
</pre>

{{note}}Unlike with scripts, you '''cannot''' transition through the hierarchy within the tag terms. You can test tags on the current context or directly on the hero. Those are the only options, and they will be all you need 99.9% of the time.

SettingSummary Element (Data)

2008-12-16T23:03:04Z

Mathias: /* Example */

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "setting_summary" Element==

The "setting_summary" element is used in a single location within HL. This portal corresponds to the table that displays the currently selected Settings on the Configure Hero form. It's purpose is to allow you to position and size the table on the Configure Hero form. There are no attributes or child elements for this element.

==Example==

The following example demonstrates what a setting_summary portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="cnfSummary" style="special">
<setting_summary/>
</portal>
</pre>

Keying on Items Within Tables

2008-12-15T23:38:02Z

Mathias:

{{context|Basic Concepts and Terminology|Manipulation of Visual Elements|Working With Tables}}

When working with tables, there will be times where you will want to base sizing and positioning on the number of items within a particular table. This will most often occur when trying to intelligently fit multiple tables into a limited amount of space.

The Kit provides two important mechanisms for determining the items in a table. First, there is the "itemcount" target reference that returns the total number of items within the table. Second, there is the "itemsshown" target reference that returns the number of items that are actually visible within the table.

The utility of the item count is probably obvious. By checking the item count, you can determine that a particular table contains no visible items. When generating printed output, a table with no visible items should generally be completely omitted. To achieve this, you can easily check the number of items in a table and set its visibility to zero if the count is zero.

The number of items shown is equally useful. By comparing the number of items shown to another value, you can make appropriate determinations about the what's going on with the table. Most commonly, you will compare the number of items shown against the total number of items in the table. If the values are the same, then you know that the entire contents of the table are visible. When generating printed output, if the two values do not match, then you know that one or more items were not included in the table. This makes it possible to intelligently determine how to lay out the page, since you can quickly determine whether information is omitted and/or will be appearing in a subsequent spillover section of the printout.

Scripting Basics

2008-12-15T22:58:18Z

Mathias: /* Overview */

{{context|Basic Concepts and Terminology|Data Manipulation Basics}}

==Overview==

HL makes extensive use of scripts to allow the data file author substantial freedom and flexibility. In fact, scripting is such a fundamental and diverse topic that huge sections of the documentation are dedicated to various facets of writing scripts. This section merely provides a brief overview.

The scripting language syntax within the Kit is relatively simple. You can declare variables, assign values, perform simple conditional tests, and utilize a number of built-in intrinsic functions for various purposes. There is also a syntax that allows access to all of the objects within a given actor, such as the various picks and containers, plus the field values and tags that may be assigned to them. The language syntax itself is somewhat similar to the age-old Basic language. Using scripts, an author can pretty much do whatever is necessary to properly model the requirements of a given game system.

To make the writing of scripts easier, the Kit supports re-usable procedures. A procedure is nothing more than a mini-script that can be called from multiple places. The data files for each game system make extensive use of procedures so that many scripts can be reduced to simply calling one or two procedures to do all the work.

The starting data files provided by the Kit include numerous scripts and procedures that you can use, adapt, and extend according to the needs of the game system you're implementing.

==Thing-Based Scripts==

The most common type of script that you will find yourself writing the "eval script". Of all the different types of scripts, most are triggered in response to a specific action. However, an eval script is scheduled to occur at a specific phase and priority during the evaluation cycle, hence the name.

Every eval script is associated with a thing. This means that every pick derived from a given thing inherits all of the eval scripts for that thing.

Since an eval script is performed during evaluation processing, a separate task is always created for each eval script, which is then scheduled within the overall task list. If a thing is added to a container multiple times, each eval script must be processed separately for every pick. Consequently, separate eval script tasks are created and scheduled for every pick.

Eval scripts are the most commonly used script due to the ability to schedule them. So many facets of a complex game system are inter-dependent. Dependent calculations must be performed in a carefully ordered sequence to ensure that all of the game mechanics are accurately implemented within the data files. Eval scripts provide the means for this scheduling.

==Thing-Based Rules==

Sometimes, you don't need to apply a modification to anything and instead need to verify whether a required condition is satisfied. For example, the "Knowledge" skill might require that the user specify the domain to which the skill applies. This entails checking that the user has entered a suitable value.

To handle situations like this, the Kit provides "eval rules" as a companion to eval scripts, and you will likely find yourself writing a number of these as well. Just like eval scripts, eval rules are scheduled as tasks and performed with specific timing during the evaluation process. Unlike eval scripts, the purpose of an eval rule is to verify a condition, so an eval rule must always determine whether its condition is satisfied or not. If the rule is not satisfied, the corresponding pick is flagged as being invalid and an appropriate message is displayed to the user within the validation report.

==Component-Based Scripts and Rules==

There are many situations where you'll want the same script or rule to be applied to all things that derive from a particular component. For example, every piece of gear the character is wielding should be verified to not be stored in a backpack or some other container. The Kit makes it easy to handle situations like this by allowing you to actually define the script or rule directly on the component.

Whenever a script or rule is defined on a component, that script/rule is treated as if it were individually assigned to every thing that derives from the component. This means that a new task is automatically created and scheduled for the script/rule on every pick that is added to the character.

It is reasonably common to have both component scripts/rules '''and''' individual script/rules associated with a particular thing.