Data File Development Process

[Context: HL Kit … Basic Concepts and Terminology]

There is no "right" way to development data files for Hero Lab, and everyone will evolve their own preferred approach. However, we can offer some suggestions based on what we've found works well for us. Based on our experience, we recommend that you try the following sequence when adapting the Skeleton data files to your own game system.

Copy the Skeleton Files

Before you do anything, you need to setup your own copy of the Skeleton data files in a new folder for your game system. Hero Lab can do the basics for you automatically by going to the "Tools" menu and selecting the "Create New Game System" option. Provide the name of the game system and the folder to use, then let Hero Lab set everything up properly. After it's created, you can switch to the new game system to verify it.

Game System Details

Once the new copy of the Skeleton files is in place, the first step you should take is to modify the definition file for your game system. This entails opening the "definition.def" file and making appropriate changes to a few elements. The "game" element should be assigned appropriate values for each attribute to reflect the game system and its publisher. The "author" element should be assigned attribute values that identify you at the author. The "structure" element should already specify the appropriate default folder for the game system, but it's probably worth double-checking this detail. Once these changes have been made, verify everything is working properly by loading the new game system into Hero Lab.

Data File Compiler

HL compiles the data files you create, allowing it to catch many errors and problems before the data files are even loaded. This section outlines facets of the compiler that are fundamental to writing your own data files.

Enable Data File Debugging

Begin by making sure that you've configured Hero Lab to enable the debugging aids. By default, Hero Lab assumes that users are not editing their own data files, so various development facilities within the product are disabled. You need to make sure they are turned on. Go to the "Tools" menu and into the "Data File Debugging" submenu, where you need to turn on the "Enable Data File Debugging" option.

Compiling Data Files

During the course of developing your data files, there will be times where you want to fully test that everything is working properly. There will also be times when you simply want to verify that your changes are syntactically valid and compile successfully. You can ask Hero Lab to re-compile your data files at any time by going to the "Tools" menu and into the "Data File Debugging" submenu, where you can invoke the "Compile Data Files" option. You'll be prompted to specify the game system to re-compile, and you'll be shown any error messages that might be encountered during the compilation process.

As long as your files fail to compile, they will not load in the Hero Lab, so you should get in the habit of frequently re-compiling your data files. This will uncover problems quickly, since the error must exist in whatever changes you've made since the previous successful compile.

As a shortcut, you can use the <Ctrl-C> key combination to invoke a compile. This makes it easy to regularly verify that your data files are valid at each step along the way as you develop them. Please note that the <Ctrl-C> key combination will not work when the input focus is a text edit portal (e.g. character name), since the <Ctrl-C> is interpreted as a traditional "Copy" command within a text edit portal.

Using Quick-Reload

Whenever you make changes to your data files, you need to load those changes into Hero Lab so you can use and test them. The simplest way to do this is to go to the "File" menu and select "Switch Game System". However, this approach always shows you the release notes for the game system and potentially the "demo mode" warning, after which you'll be shown the "Configure" form for a new character. After a few dozen times, this gets really old.

So Hero Lab includes the "Quick Reload" mechanism, which can be invoked by going to the "Tools" menu and into the "Data File Debugging" submenu, where you can select the "Quick Reload" option. This mechanism re-compiles the data files, if necessary, and then reloads them into Hero Lab, bypassing the extra steps and restoring the current tab that is selected. As an added bonus, if you have a saved portfolio loaded, your portfolio is reloaded. This makes it quick and easy to incrementally modify and test out behaviors associated with selected options.

Take Snapshots Regularly

As you evolve your data files, you will be making significant changes. If you aren't extremely careful, it's likely that you will end up causing everything to break at a few points along the way. When this happens, it can be invaluable to be able to see exactly what has been changed since the last time everything was working fine. In order to do this, you need to have a saved copy of when things were last working. So we strongly recommend that you take snapshots of your data files at regular intervals, preferably at milestones where everything is working the way you want it.

The easiest way to take a snapshot is to use the "HLExport" tool that is included with the Authoring Kit. This tool is designed to package up all of the data files for a game system into a single file that can be imported back into Hero Lab. Using HLExport, you can readily take snapshots of your working data files and save them. If you need to refer back to one, you can import the file back into Hero Lab. However, be sure to import the files into a different directory from your data files, else the imported files will overwrite your recent changes.

Another simple technique is to make a copy of the entire directory contents for your game system. This allows you to do a direct file-to-file comparison of any file at any time, which can be quite handy at times. The ideal technique is to use a source control system of some sort, although this is an approach that most users will not have access to. If you don't we recommend using a combination of the other two methods for best results.

Before writing any data files, it's critical that you first do your homework. If you launch into writing the data files without a good plan, you will likely run into a number of surprises and setbacks along the way. While such events won't stop you from successfully creating the data files, they will almost certainly cause unnecessary delays and frustration. So you will fare best if you take the time upfront to develop your basic implementation strategy, map out all of the basic building blocks you'll need, and design how everything should look and behave for the user.

Implementation Strategy

The first thing you need is to figure out how you are going to go about developing your data files. We've provided you with a solid starting point in the User Manual installed with the Skeleton data files. That manual outlines a proven methodology for creating the data files for a new game system. This document you are now reading leverages the outlined strategy for the Savage Worlds game system. You are welcome to come up with your own approach, as there is no "right" way to do it, although we recommend you start with the methodology we've presented and adapt it to suit your needs.

Building Blocks

?????????????????????????????????????????????????????????????????

components and compsets

entities

things

tag groups

phases and evaluation cycle

Look and Feel

?????????????????????????????????????????????????????????????????

visual layout and organization

interactive behavior - where to use tables, choosers, menus, etc.

add scans of original sketches

Visual Skins

?????????????????????????????????????????????????????????????????

colors

fonts

graphics - textures, buttons, icons