Data File Release (Savage)
Context: HL Kit … Authoring Examples … Savage Worlds Walk-Through
Overview
The data files that we've been developing are finally complete and soon ready to be shared with others. The sections below address a variety of final tasks associated with preparing our data files for distribution.
Version Requirement
Every new release of HL typically introduces new functionality within the Kit. If you utilize this functionality in your data files, you'll want to be sure that users don't try to load your files with an older version of HL. If they do, they will get errors when compiling the data files and think that the files are the problem. You can avoid this by designating the minimum version of HL that is required with your data files.
Within the definition file, the "release" element possesses a "required" attribute. This attribute can specify the minimum version of HL that your data files require. If you specify this correctly, any attempt by the user to load your data files into an older copy of HL will result in an appropriate error being reported. The user will be we told he needs a newer version of HL and pointed to the Updates mechanism to retrieve the update.
Since our data files are utilizing functionality introduced in V3.1 of HL, we need to specify that as our requirement. So the attribute is must be assigned the value "3.1".
Version Number
When we release new updates to our data files, we're going to want to differentiate the newer version from any older versions. To accomplish this, each new release of our data files must be assigned a distinct version number.
The data file version number is used by HL to determine whether a new version is available. It is also used to detect when a loaded portfolio requires a newer version of the data files. This can happen if the portfolio is created on one computer and then loaded on a different one with a different version of the data files.
Just like HL itself, the version number used by data files has two pieces. There are both a major and minor version. In general, increasing the major version indicates that major changes and/or enhancements have been made to the data files. If the revision are relatively small in a new release, then the minor version number should typically be increased instead. When you increase the major version number, you should normally reset the minor version number to zero. Every time you release a new update to your data files, you should always increase the version number.
If you are releasing preliminary data files to friends for testing before you release the files widely, then you should probably assign a major version of zero and increment the minor version with each such release. When you officially release your data files for the very first time, you should normally assign a version of "1.0" (i.e. a major version of one and a minor version of zero). Since we're now ready to release our data files for the first time, that's the version we'll assign to our data files.
Release Notes
Within the definition file, you can specify a block of text referred to as "release notes". This block of text is shown to the user when they load your data files for the first time. Within the release notes, you should provide basic information to the user regarding your data files, including where to find further information (like the User Manual), legal text, and the like.
You can specify whatever information you like within the release notes. However, we recommend that you use a similar approach to how the data files for other game systems are handled. This ensures that users have a consistent experience across all game systems, which makes everything easier to use.
FAQ
You should ideally maintain a FAQ for your data files. The acronym "FAQ" is short for "Frequently Asked Questions". You can define your FAQ with two different methods, and either one is perfectly acceptable. The first option is to include the FAQ as a section within the User Manual for your data files (see below). The second option is to use the built-in FAQ mechanism provided by the Kit. This latter approach allows you to define the individual FAQ entries as part of the data files and then allow the Kit to synthesize the appropriate FAQ document as an HTML file.
As implied by its name, the FAQ contains an assortment of answers to questions that users will be asking about your data files. When you first develop your data files, the list will likely be short, but you will usually be able to anticipate at least a few questions that users will ask. If you provide answers before users ask them, it will make using your data files much easier for users and eliminate the annoyance of having to answer the questions when users bug you with them.
User Manual
The odds are that you'll want other gamers to utilize your data files. You've put lots of hard work into creating them, and sharing them with others will make lots of gamers very happy. However, these others won't know how to use your data files when they first load them. You're going to need to write a User Manual to explain that process.
Fortunately, the Skeleton Files provide a basic shell of a User Manual. This will be found as the file "manual.htm" in the "docs" folder beneath your data files. You can use this file as a starting point to evolve your own User Manual, as appropriate to the game system. Since this file is an HTML file, it can be viewed by virtually anyone on any computer. However, this also assumes that you can properly edit an HTML file to add your custom content.
If you are not familiar with the creation of an HTML document, you'll find it to be pretty simple. The overall structure is very similar to the XML format used by all the data files. In addition, all you need to do is plug in content. The structure can be left unchanged. This should result in a relatively straightforward process of evolving the User Manual with content suitable to your data files.
Building an Import File
At this point, your data files should be complete and ready to distribute. However, there are lots of files involved. Sharing all these files is a recipe for problems. Explaining to users how and where to place the data files on their computer is similarly going to result in problems for less technical users. Fortunately, HL includes a tool to make this process easy.
The tool is called "HLExport" and can be found on the Start menu with Hero Lab. This tool will take a complete set of data files and compress it into a single file with a ".hl" extension. This one file will contain all the information necessary for HL to automatically install everything into the correct place on a user's computer.
When the tool launches, you will be prompted for four pieces of information. First is the game system to be exported, which is identified by selecting the definition file for the game system. If you want to customize the set of files to be included, you can toggle individual files as you see fit. However, it is generally best to keep only the files you want to export in the "data" folder for your game system, with all other files being kept elsewhere. That way, the entire process is quick and easy.
The second piece of information is any sample portfolios that you want to distribute with your data files. It is generally a good idea to includes at least one sample character for the game system. If the rulebook defines assorted sample characters, those would be perfect for inclusion.
The third piece is the export file to be created. This file can be named anything, but it should typically be named appropriately for the game system (e.g. "savage.hl"). You may include the version number information within the filename (e.g. "savage.1.0.hl") if you want, but this is not generally done. The export file will contain everything and is the one file that can be easily shared with others. Users can readily import the contents of the file by going to the "Tools" menu and selecting "Import File", or by clicking on the "Import File" button that appears on the "Select Game System" form.
The fourth and final piece is notes/comments about the data files. These notes can be anything you want, but they should generally provide summary details about the data files being distributed. As a convenience, you can include this summary text within the definition file for the game system. This is done via the "summary" attribute within the "release" element. Whatever is defined for the "summary" attribute is automatically used as the default contents of the comments section.
Once you have everything entered the way you want, simply click on the "Generate" button and wait a moment. The HLExport tool will synthesize the appropriate ".hl" file. Once created, you can verify the file by attempting to import it into HL.
WARNING! Be careful not to import the file over the data files you're developing. By default, the data files will be placed in the same folder you pull them from. If there were any problems generating the ".hl" file, proceeding with the import in the default location could result in lost material. If you select an alternate installation folder, you'll be able to test everything without any difficulties.
Publishing Your Work
Once you have a completed ".hl" file, you can share your creation with others by simply giving them the ".hl" file. This file can be posted on websites for download, attached to emails, or whatever other mechanism seems appropriate to you.
To simplify the distribution process, Lone Wolf Development has a system already in place that allows authors to easily share their data files with others. Authors can post a notification about their data file updates on the Lone Wolf server. Once posted, all HL users will be able to see and access the data files directly from within HL.
Access to this mechanism is free. Once your data files are complete, simply contact technical support for details on how to distribute your data files. We'll set you up with an authoring account and you can then manage the notifications independently, releasing new updates at any time and without any involvement by Lone Wolf staff.
