| Program: | Hexkit Strategy Game System |
| Version: | 4.3.3 (History) |
| Released: | 30 September 2015 |
| Author: | Christoph Nahr (Copyright) |
| Contact: | webmaster@kynosarges.org |
| Website: | http://kynosarges.org/Hexkit.html |
Make sure that the .NET Framework 4.0 Client Profile or newer is installed on your Microsoft Windows system. Install the binary package to the default location, or to any directory of your choice.
The installer optionally creates a Hexkit group in the Start Menu, and two shortcuts on the Windows desktop. When updating an existing Hexkit installation, simply choose the same directory as before. All of your previous installation options should be pre-selected for you.
Once installation is complete, select one of the following Start Menu entries or desktop shortcuts:
That’s all. Have fun! You can get more information in the following places:
This section lists other available documentation for Hexkit, apart from this ReadMe file.
The context-sensitive online help describes the user interface of Hexkit Game and Hexkit Editor. Pressing the F1 key will bring up the help entry for the current dialog while one is shown, or for the selected menu item while browsing the main menu. Most dialogs also feature a Help button that has the same effect.
Pressing the F1 key when no dialog or menu is active will display the introduction page and a list of help topics. The menu command Help: Contents has the same effect. Alternatively, you can use the Hexkit Help start menu shortcut to show the online help without starting the Hexkit Game or Hexkit Editor programs.
The User’s Guide explains how Hexkit works. This includes fundamental concepts, gameplay procedures, scenario design issues, and so on. You should read at least the “Hexkit Game” chapter to understand what’s going on.
There is also a separate manual for the Battles of Crécy and Poitiers demo scenarios, describing the historical situation of the battles and the rationale behind the scenario design.
Both the User’s Guide and the scenario manual are Adobe PDF documents, available as a separate download at the Hexkit home page. You need the free Adobe Reader, available at the Adobe website, to view or print them.
Additional information on programming Hexkit is provided by a comprehensive class reference, available as a separate download at the Hexkit home page. This reference is a collection of HTML pages that was created from XML source code comments using the free Sandcastle help compiler.
Hexkit requires a Microsoft Windows system capable of running the Microsoft .NET Framework 4 Client Profile or any newer .NET 4.x release. This includes the following operating systems:
On all of these systems, Microsoft Internet Explorer 5.01 or later and Microsoft Windows Installer 3.1 or later are also required. Any post-XP system will already have those.
All Hexkit user settings, saved games, and temporary files are stored in a directory named Hexkit under the current user’s (My) Documents folder. Note that this directory is not automatically removed when Hexkit is uninstalled (see Deinstallation).
All Hexkit scenarios and related files are stored in the Scenario and Images folders of the Hexkit installation directory by default. The installer automatically grants all users write permission to these folders and all nested folders (but not to the installation directory itself).
Previous Hexkit versions forced users with “limited accounts” (members of the “Users” group) to employ various workarounds for editing scenario files if Hexkit was installed in its default location under Program Files. As of Hexkit 3.7.2, these workarounds are no longer necessary – anyone can edit scenarios in the default folders.
Hexkit requires a number of .NET security permissions that are available only when the executable is running with “Full Trust”. This is usually the case for all .NET programs that are run from a local hard disk or a shared network drive. Hexkit does not require administrator privileges.
Note: Although .NET executables receive “Full Trust” permissions when running from a shared network drive, you will not be able to view the online help. Microsoft’s Compiled HTML Help File format relies on an ActiveX control for Internet Explorer, and that control cannot run over a network for security reasons. Unfortunately there is no reasonable workaround, other than running Hexkit from a local hard disk.
Like all WPF applications, Hexkit Game and Hexkit Editor should scale automatically to the configured dot pitch of your monitor. This is determined by the dots-per-inch resolution (Windows Vista) or system fonts size (Windows XP) in your current Windows display settings.
The application and dialog windows were designed for a minimum screen resolution of 800x600 at 96 or 120 dpi (equivalent to Normal or Large system fonts in Windows XP, respectively). You may need to use a higher screen resolution to see the entire window if you are using higher dpi or larger system fonts.
The Hexkit Game and Hexkit Editor windows may be resized as desired, but not below a minimum size determined by the program’s display layout and your Windows display settings. Note that maximizing the application window enables “autoscrolling” (see Control Issues).
Use the menu command Display: Save Window to save the current window size and location. Window parameters are stored separately for Hexkit Game and Hexkit Editor; for each desktop resolution; and for each user of both programs.
When the Hexkit Game or Hexkit Editor window is maximized, you can “autoscroll” the map view without using the scroll bars. Place the mouse pointer on an edge or corner of the screen, and the map view will continually scroll in that direction until the mouse pointer is moved away. (Note: In Hexkit Editor, the map view is located on the Areas tab page.)
The mouse wheel, if present, changes the zoom level of the map view. Rotate the wheel up or down to zoom in or out, respectively. Clicking the mouse wheel or middle mouse button, if present, restores the standard zoom level.
Note: If you are using a mouse driver that provides customizable mouse wheel handling, such as Microsoft IntelliPoint, Hexkit may respond erratically to mouse wheel input due to conflicts with the driver software. The solution is to disable the driver’s mouse wheel support while Hexkit is running. The exact procedure depends on the driver software; the following description applies to Microsoft IntelliPoint 4.1. Please consult the manufacturer’s documentation for other mouse drivers.
Bring up the Mouse Properties window (e.g. by double-clicking the IntelliPoint icon in the taskbar), select the Wheel tab, and click the Advanced button to display the Advanced Wheel Settings dialog. Now either select the radio button that disables all IntelliPoint software wheel support, or use the Add button to add the Hexkit Game and Hexkit Editor executables to the program list. (The version numbers shown in parentheses reflect the version of the Hexkit graphics engine rather than that of the application.)
Simple MAPI is a standard e-mail protocol designed by Microsoft to facilitate interoperation between e-mail clients, such as Outlook Express, and applications such as Hexkit. This protocol is available on all Windows versions that support the .NET Framework, and fully supported by all Microsoft e-mail clients (Outlook Express, Outlook, Exchange).
Hexkit uses Simple MAPI to retrieve address book entries during player setup, and to create e-mails with attached files for play-by-email and automatic bug reporting. (The latter feature can fall back on messages without file attachments, using the default web browser’s mailto: handler which should work with any installed e-mail client.)
If you are using one of Microsoft’s e-mail clients, you generally shouldn’t have any problems with Hexkit’s e-mail features. Simply installing the program as your default e-mail client will also configure it as the system’s Simple MAPI server.
One exception is an odd bug concerning Outlook 2000 prior to SR-1a/SP2. If the Personal Folder backup utility was installed and Outlook 2000 was not already running at the time of a Simple MAPI request, the request would fail with an unspecified error message.
This bug is described in MS Knowledge Base article Q240813 (search for this code on Microsoft’s web site). As a workaround, patch your Office 2000 installation up to SR-1a/SP-2 (first apply Service Release 1a, then Service Pack 2), or simply make sure Outlook 2000 is already running before starting Hexkit.
If you are using a third-party e-mail client, such as Mozilla Thunderbird or Pegasus Mail, you may encounter problems with some or all of Hexkit’s e-mail features. Most Windows e-mail clients should be able to create e-mail messages via Simple MAPI when properly configured, but the address book feature of the Player Setup dialog may still be unusable.
Cannot create e-mail messages. Does your e-mail client support Simple MAPI, and is it configured to do so? Third-party clients may require additional configuration steps in order to act as the system’s Simple MAPI server. Please consult your program’s documentation for details.
Cannot access the address book (Player Setup). Third-party clients usually do not provide any meaningful address book services, even when they are properly configured to support Simple MAPI. There is no workaround other than installing a Microsoft program as the default e-mail client, such as the free Outlook Express that comes with Internet Explorer.
Searching your e-mail client’s support website for the Simple MAPI functions used by Hexkit might yield more information. These functions are MAPIAddress, MAPIResolveName, and MAPISendMail. Only the latter is absolutely required for PBEM support; the other two are merely needed to access the address book.
All XML files used by Hexkit are stored in Unicode UTF-8 format. This international standard encoding for text files maintains a small file size without limiting representable characters to the Latin or English alphabet. UTF-8 is also the standard encoding for HTML and XML files, and therefore widely used on the Internet and by the .NET Framework.
You might have difficulties viewing or editing these files with certain third-party programs because many tool developers have been ignoring Unicode in the past. This issue does not affect Hexkit itself because the .NET Framework provides the necessary Unicode support, but you will need a Unicode-capable program to view or edit Hexkit XML files outside of Hexkit Editor. Visual Studio 2015 Community is free and fully supports editing XML files in UTF-8 format.
The setup package creates the following files and subdirectories in the target directory:
| ReadMe.html | This file |
| WhatsNew.html | Hexkit version history |
| Hexkit.Editor.exe | Hexkit Editor executable for the .NET Framework |
| Hexkit.Game.exe | Hexkit Game executable for the .NET Framework |
| Hexkit.Help.chm | Hexkit online help for HTML Help Viewer |
| *.dll | Various .NET assemblies required by Hexkit |
| *.config | .NET application configuration files |
| *.manifest | .NET manifests to enable Windows control styling |
| Hexkit.Options.xsd | XML schema definition for options files |
| Hexkit.Scenario.xsd | XML schema definition for scenario files |
| Hexkit.Session.xsd | XML schema definition for session files |
| Images | Directory for Images section files and graphical tilesets |
| Images\DeBray Bailey Images.xml | Image definitions for some of DeBray Bailey’s PNG files |
| Images\DeBray Bailey\*.png | DeBray Bailey’s free fantasy tileset, converted to PNG format |
| Images\DeBray Bailey\readme.txt | Copyright notice and documentation for the original BMP tileset |
| Scenario | Directory for scenario files |
| Scenario\Areas | Directory for Areas section files |
| Scenario\Entities | Directory for Entities section files |
| Scenario\Factions | Directory for Factions section files |
| Scenario\Rules | Directory for rule script files |
| Scenario\Variables | Directory for Variables section files |
| Scenario\Crécy.xml | Historical scenario based on the Battle of Crécy |
| Scenario\Crécy Variant.xml | Speculative variant of the Battle of Crécy |
| Scenario\Poitiers.xml | Historical scenario based on the Battle of Poitiers |
| Scenario\Poitiers Variant.xml | Speculative variant of the Battle of Poitiers |
| Scenario\Roman Empire.xml | Historical scenario based on the Roman Empire |
| Scenario\Troll Chess.xml | Simple scenario for demonstration and testing purposes |
| Scenario\*\*.xml | Subsection files used by the demo scenarios |
| Scenario\Rules\Compile.bat | Sample batch file to compile a C# rule script file |
| Scenario\Rules\Default Rules.cs | Default rule script for new scenarios |
| Scenario\Rules\Crécy Rules.cs | Rule script used by the Crécy and Poitiers scenarios |
| Scenario\Rules\Roman Empire Rules.cs | Rule script used by the Roman Empire scenario |
| Scenario\Rules\Troll Chess Rules.cs | Rule script used by the Troll Chess scenario |
You can uninstall Hexkit via Add and Remove Programs in the Control Panel, as usual. If you chose to create a Start Menu group during installation, you can also use the Uninstall Hexkit shortcut located there.
Deinstallation will not remove any saved games, user settings, and edited scenario files. Retain or delete them as you wish.
Saved games, user settings, and temporary files can be found in subdirectory Hexkit of the (My) Documents folder of any user who executed Hexkit Game or Hexkit Editor:
Hexkit might contain temporary files (used for debugging).Hexkit\Games might contain saved games.Hexkit\Options might contain game and editor settings.Changed or added scenario files can be found in two subdirectories of the Hexkit installation folder:
Images might contain new or changed Images section files and graphical tilesets.Scenario might contain new or changed scenarios, subsections, and rule scripts.These are default locations only. Saved games and scenario files may also have been stored in arbitrary locations selected by the user.
This section provides additional information regarding the source package, available as a separate download at the Hexkit home page. The directory to which the archive was unpacked contains the source files required to build all .NET assemblies comprising the binary package.
You need either Microsoft Visual Studio (2010 or later) or the free Microsoft Windows SDK 7.1 for Windows 7 and .NET 4 to perform the build. Windows SDK 7.1 has the same system requirements as the .NET Framework 4 itself but also requires that you first install the full .NET Framework 4 – not just the Client Profile.
The subdirectory Tektosyne contains version 5.6.6 of my Tektosyne library. The current version of this class library is also available as a separate download at the Tektosyne home page, but this is not required to run or compile Hexkit.
Use Visual Studio or MSBuild to load or build the solution Hexkit\Hexkit.sln. The output directory is Hexkit\bin. This directory contains other files and subdirectories which are not created during the build process but which must be present for Hexkit to execute properly. Please refer to Installed Files for details.
Rebuilding the solution will create an “unsupported developer version” because the assemblies are no longer signed with the expected strong name. There are only two differences to the version in the binary package: the About Hexkit dialog will show a warning, and error reporting by e-mail will be disabled.
You can use the free Visual C# Express IDE instead of the full Visual Studio. However, the Express edition has several artificial limitations, including a lack of support for “solution items”. These are files that are linked to a solution but not to any particular project, such as this ReadMe file. Express users will have to locate and open these files manually. This restriction does not apply to the free Visual Studio 2015 Community edition.
The distribution package was created by running MSBuild on the separate build script Publish.proj. This script offers the following targets:
Hexkit\HexkitSource.zip, then a signed release build in subdirectory Hexkit\bin, and finally the binary package Hexkit\HexkitSetup.exe.The default target is “Publish”. You need a key container named “Kynosarges” and the applications 7-Zip and Inno Setup 5 for this target to succeed.
The directory Hexkit\Hexkit.Help contains the sources for the HTML Help file Hexkit\bin\Hexkit.Help.chm, wrapped in a Visual Studio project for convenient editing and automatic building along with the Hexkit solution.
The Hexkit.Help project appears as a C# project but is actually a customized MSBuild script because Visual Studio does not directly support editing or building HTML Help files. Therefore, you shouldn’t edit the properties of this project from within Visual Studio. Load the MSBuild file Hexkit\Hexkit.Help\Hexkit.Help.csproj into an XML text editor to view or change the build process.
Building the HTML Help file requires Microsoft’s HTML Help compiler. This compiler is part of the Microsoft HTML Help Workshop, available as a free download.
Visual Studio provides no GUI support for editing the HTML Help project file (Hexkit.Help.hhp) and the table of contents file (Hexkit.Help.hhc), whereas the HTML Help Workshop allows editing the TOC as a tree structure. However, the Workshop’s HTML editor is far inferior to that of Visual Studio, and you must manually synchronize the list of HTML files between the two environments if you decide to use both.
The HTML Help file is built using the “flat” option which means that all HTML topic files are stored without directory prefixes. This greatly simplifies cross-referencing between topic files stored in different phyiscal folders; however, it also means that most href links won’t work outside of the compiled HTML Help file. Moreover, you must ensure that all HTML topic files have unique names if you decide to add or rename files.
The Rules project holds the rule scripts for all scenarios that ship with Hexkit. This project exists only as a convenience for editing rule scripts. It is not referenced by any other project, and Hexkit Game must still load and compile the rule script for the current scenario at run time.
Since all C# files in the Rules project define the same types, all but one must bet set to “Build Action: None” at any given time. When editing a specific rule script, set it to “Build Action: Compile” to enable IntelliSense for all Hexkit and Tektosyne types. Without this trick, Visual Studio would provide IntelliSense only for BCL types.
In release mode, Hexkit Game compiles scenario rule scripts in-memory. If any temporary disk files must be created during the compilation, they are deleted automatically when compilation has finished.
In debug mode, however, Hexkit Game compiles scenario rule scripts to persistent, uniquely named DLL and PDB files in the Windows directory for temporary files. This is necessary to allow source-level debugging of scenario rule scripts. Unfortunately, Hexkit Game cannot delete them automatically because they remain locked by the .NET CLR while the program is running. You must therefore delete them manually once Hexkit Game has been closed.
Please refer to the comments in method Hexkit.Scenario.RuleScript.Compile for further details.
The file Hexkit\Hexkit.Diagrams.xml is the Class Diagrammer project file that was used to create the UML diagrams you see in the Hexkit User’s Guide. You must recompile the Hexkit solution before running this project, as Class Diagrammer reads .NET assemblies rather than source code files.
All diagram text is set in Adobe Myriad Pro, and will appear in the default GUI font for your Windows version if that font isn’t available. The output job requires the Adobe PDF printer driver which comes with Adobe Acrobat.
All files – individual files, multi-file packages, and individual files contained in multi-file packages – that constitute the original distribution of the Hexkit Strategy Game System are Copyright © 2000–2015 by Christoph Nahr, except where otherwise noted.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The fantasy tileset included in the binary and source packages is Copyright © 11 April 2000 by DeBray Bailey (used by permission). Please refer to the file Images\DeBray Bailey\readme.txt for the full copyright statement regarding this tileset.
The version history has been moved to a separate WhatsNew file.
Compilation of rule scripts written in Visual Basic and JScript.NET has not been tested. Let me know if there are any problems.
The application may appear to lock up for a second or more when a GUI control with many images, or one big image, is first displayed. Examples include displaying an overlay image on a map view; switching to the Images tab in Hexkit Editor; and switching to the Images page of the “Change Entity Class” dialog in Hexkit Editor. This is due to the sluggish layout mechanism of Windows Presentation Foundation.
The current Sandcastle release that was used to build the Class Reference still has a few bugs. You may encounter the following issues:
Collections classes.When in doubt, please refer to the source code for the correct documentation.