TABLE OF CONTENTS

PREFACE

This document is intended to describe the various facets of Eamon CS.  The real documentation will be a formal set:  full source code commenting, a Player's Manual, a Dungeon Designer's Manual and a Class Reference.  It will take quite a while to put all that together, so in the meantime, hopefully, this will suffice.

Eamon CS (ECS) is a port of the Eamon roleplaying game to the C# programming language.  It is the production version of a prior system called Eamon AC (EAC), an ANSI C prototype intended to convert Eamon from BASIC.  If you have EAC on your system, you should uninstall it before using ECS, as it is now obsolete.

This system is a hybrid of Donald Brown's Classic Eamon and the most modern BASIC Eamon available, Frank Black Production's Eamon Deluxe.  It is also directly based on the EAC prototype.  Eamon CS borrows liberally from and bears a strong resemblance to all these sources in various areas.  

The game has evolved rapidly over its lifespan.  First, it moved to a plugin-based architecture unique to this branch of Eamon, then into the various flavors of Unix, and most recently into the Android mobile device space.  The game engine has improved with each one of a small but growing collection of custom-built adventures created along the way.  The different programs of Eamon CS share a common code base and collectively are referred to as Eamon CS Desktop on traditional workstations and Eamon CS Mobile on mobile devices.

PREREQUISITES

As mentioned in the README.md file, Eamon CS has no formal installer.  There are good points and bad points to this.  On the one hand, it is a simple matter of unzipping the Eamon-CS-master.zip file downloaded from GitHub to set up for play (if you did that, as opposed to doing a Git Clone).  Also, it means there is no installer to maintain, which frees up time for other things like engine enhancements or developing adventures.

A disadvantage to this approach is the ECS developer/gamer is responsible for installing all system prerequisites.  Otherwise, ECS will not run when any of the .bat or .sh QuickLaunch files are double-clicked.  The good news is that these files auto-detect the missing packages and provide the URLs referenced in the following hyperlinks.  If you find that you cannot get Eamon CS to run on Windows, your first order of business should be to download and install the following files (in order):

For programmers who want to play, step-through, or develop the source code:

• Installer option: .NET desktop development
• Installer option: Mobile development with .NET

For gamers who want to play:

Note:  If you want to use Eamon CS with a .NET Standard 2.0 compliant runtime already on your system (that isn't .NET 6.X), see the POST-INSTALLATION TOPICS section for details on how to do that.

A second disadvantage on Windows leads to a useful tip regarding the downloaded .zip file.  You should always right-click on the .zip file and select "unblock" to avoid the security warnings, as shown below:

The prerequisites on Unix are similar:  a version of .NET 6.X that is compatible with the given platform.  You can download a .NET software bundle for Linux or macOS from the website referenced by the above links (and find corresponding installation instructions).  But Eamon CS on Unix should only be pursued by those confident enough to see it through via their own devices.  The game runs correctly on Ubuntu Linux and FreeBSD and may work on other Unix variants, such as macOS (OS X).

POST-INSTALLATION TOPICS

The precompiled binaries for Eamon CS use .NET 6.X, but the system should be fully compatible with all .NET versions that conform to .NET Standard 2.0.  However, using older versions may introduce additional requirements such as .NET Framework.  To use Eamon CS with a different .NET, you need to recompile the EamonPM.WindowsUnix project to target it.  To do this, you must first install Visual Studio 2022+, as described in the PREREQUISITES section.  The use of Visual Studio is described in the section called USING THE VISUAL STUDIO DEBUGGER.  The following screenshot shows how to determine from the command line which versions of .NET are present on your system:

To recompile the EamonPM.WindowsUnix project, load the Eamon.Desktop solution in Visual Studio.  Right-click on the project and choose Properties.  Select the appropriate version of .NET in the Target Framework drop-down list of the Application General section, then click the Save button:

After doing this, right-click on the EamonPM.WindowsUnix project and choose Clean.  Then right-click on the project and select Build.  If you receive no errors, Eamon CS should now work with your installed .NET.

Additionally, you will need to modify two files in the System\Bin directory that allow the QuickLaunch facility to auto-detect .NET correctly. Simply change the value highlighted in the following screenshots to include your major .NET version (e.g., use 2|6|7 for added .NET Core 2.1 support), then save the files.

The auto-detection logic requires ongoing maintenance as new versions of .NET are released. If you find in the future this logic prevents the game from running on a properly configured workstation (for whatever reason), you can disable it by renaming or deleting the WINDOWS_PREREQUISITES.TXT and/or UNIX_PREREQUISITES.TXT files.

PROGRAMS, LIBRARIES AND PLUGINS

The plugin-based architecture used by Eamon CS extends to the Main Hall, the Dungeon Designer, and all adventures.  A Plugin Manager program specific to either Desktop or Mobile environments manages them:

Additionally, you have some adventures:

Conceptually, each plugin is a discrete program.  It exposes a Program class with a Main method that takes a collection of arguments, much like any C-based program.  The difference is that the Plugin Manager is what "executes" the plugin, not the calling C# environment.  At the bottom of the software stack, you have Polenter.SharpSerializer.dll which handles loading and saving of the game's datafiles and Eamon.dll which holds code common to all ECS plugins.  EamonRT.dll contains the vanilla game engine used by all non-customized adventures.  For customized adventures, the game plugin (e.g., TheBeginnersCave.dll) contains custom code specific to that game, built by leveraging EamonRT.dll.  It is a "modded" version of the game engine.

Plugins can share any logic with this implementation.  For example, an interesting idea would be to create a "campaign library" that contains shared code for many derived adventures.

The source code for Plugin Managers and system plugins resides in the appropriate directory under System; for adventures, it is in the adventure-specific directory under Adventures.

The Main Hall datafiles reside in System\Bin, making them easily accessible to all plugins.  Game-specific datafiles (both original and save game) reside under Adventures in their respective game directories.

Here is a final note on the architectural differences between ECS Desktop and Mobile.  For Desktop, the plugins reside in the System\Bin directory and are loaded by EamonPM.WindowsUnix.dll only when needed (and reused once loaded).  In contrast, when building EamonPM.Android-Signed.apk, all plugins are statically linked in, and all datafiles are embedded, producing a monolithic application.  When delivering the .apk onto the mobile device, the datafiles copy (when appropriate) to the device's file system - the plugins remain part of the application.  In spite of this, the plugin managers are very similar internally.

BATCH FILES

The plugins take a variety of command-line parameters (described in another section). However, to get you up and running quickly, there is a QuickLaunch folder. (Since there is no formal ECS installer, you may want to create a shortcut to it on your desktop manually). Inside this folder is a set of batch or script files that you can run directly. These files organize into sub-folders based on the underlying plugin they invoke:

¹ Run these batch files to create a new character or send an existing one into the Main Hall. The only difference between the two batch files is the nature of the adventure database loaded (the same characters will be available regardless).

² Run these batch files to return to an in-progress adventure. Use the RESTORE command to pick up where you left off.

You can study the batch files to see how the system launches various programs. You can also create new batch files using these as templates if you decide to write adventures or run the system in a non-default manner.

Eamon CS Mobile mirrors this QuickLaunch hierarchy using a series of ListViews to provide a similar experience.

SUGGESTED GAMEPLAY SETTINGS

Eamon CS runs as a set of 64-bit Console applications. You can play the game using default Console settings, and it will not diminish the experience. But you might also consider doing some light reconfiguration. While the system tries to adjust the window size optimally, there are other settings you may wish to experiment with to see what appeals to you. Strangely enough, I've found aesthetics make a big difference in the quality of the gameplay and the ease of use for tools like EamonDD. The following ideas produced some interesting results:

1. When running ECS, right-click on the Console window title bar and choose properties. Windows 10 provides the following settings; the properties available on other versions may differ.

2. Options Tab -
Edit Options -

QuickEdit Mode: Checked (you can use this to enable the mouse scroll wheel if necessary)


3. Font Tab -
Size: 12-16
Font: Consolas or Deja Vu Sans Mono
Bold: Optional


4. Layout Tab -
Screen Buffer Size -

Width: 80
Height: 9999
Window Size -
Width: 80
Height: 50 (you can adjust this up or down based on screen resolution)


5. Colors Tab -
Screen Text -

Selected Color Values -
Red: 0
Green: 255
Blue: 0
Screen Background -
Selected Color Values -
Red: 0
Green: 0
Blue: 0


6. Terminal Tab - (when present)
Cursor Colors -

Use Color -

Red: [Use Screen Text Red]
Green: [Use Screen Text Green]
Blue: [Use Screen Text Blue]

Eamon CS tries to set the values on the Layout Tab to those shown above, so you shouldn't need to change them. The Screen Buffer Width and Window Width should always be 80 columns. The Screen Buffer Height is strongly suggested to be 9999. The Screen Text shown above is Green with a Black background and has a retro-vibe, like an Apple II monitor. If you prefer amber, the RGB values [255,165,0] might work for you. As time has passed, I settled on a white background with black text, as shown in the various images in this document. Once you have the settings you're happy with, click OK, and they should persist across ECS programs.

The game supports screen readers to improve accessibility for players who benefit from it. In the System\Bin directory, a GLOBAL_LAUNCH_PARAMETERS.TXT file passes command-line parameters to all Eamon CS programs. Adding the -esrm flag to this file will cause the system to reconfigure itself, altering text sequences and stripping non-game-related output. Screen readers will more accurately process the resulting output text. This file may also be modified through EamonDD using the LoadAdventureSupportMenu .bat or .sh file and menu options two, then two.

Important Note: As each new version of Windows is released, the Command Console program seems less compatible with older applications. If you encounter issues running Eamon CS on your system that you can't resolve - cursor problems, crashes, etc. - the only solution is to configure the Command Console to operate in legacy mode. To do this, query a search engine for the best method using the phrase "Windows XX command console legacy mode," where XX is your specific Windows version.

The newest versions of Windows (10+) contain a rewritten Command Console that includes a Terminal Tab. The long unfixable bug in Eamon CS involving the Inverse Color radio button and unsightly cursor artifacts has been fixed. By default configuration, the game's text output will be as intended regardless of which Cursor Colors radio button is selected.

If the Inverse Color radio button is selected, the redraw windows (-rw) flag must be included in GLOBAL_LAUNCH_PARAMETERS.TXT (and it is by default). Otherwise, if the Use Color radio button is selected, you are enabling (or keeping) the old workaround for the bug, which is still the ideal solution. Just set the RGB values to the corresponding values on the Colors Tab for Screen Text Selected Color Values and omit the -rw flag from this file since window redraws are not required in this case.

MISCELLANEOUS GAMEPLAY NOTES

Eamon systems have traditionally restricted players to using commands of the form [COMMAND] [DIRECT OBJECT] [INDIRECT OBJECT], but Eamon CS has an enhanced parser that approaches those of traditional Interactive Fiction (IF) platforms. You can enter full sentences containing multiple commands, refer to multiple direct objects in a single command, and use pronouns to identify monsters and artifacts where appropriate. The result is a level of interactivity never before seen in Eamon.

You can think of the enhanced parser as a two-layer system. The top layer takes a sequence of commands as a sentence, splits them apart, and feeds them to the bottom layer one at a time. The bottom layer, which provides legacy parsing for Eamon CS, takes a simple command in the form [COMMAND] [DIRECT OBJECT] [INDIRECT OBJECT] and executes it. This design fits nicely within the existing game engine framework, with the added benefit of allowing the enhanced parser (the top layer) to be toggled on or off, depending on your preferences. But it also has some nuances that are worth noting:

• The sentence must contain commands in the form [COMMAND] [DIRECT OBJECT] [INDIRECT OBJECT], joined together by one or more of the following tokens (in any combination): ".", "!", "?", ";", ",", "and", "then", "also". Additionally, [DIRECT OBJECT] can be a list of direct objects, separated by these same tokens.


• If the parser encounters an "out-of-band" command (such as INFO, STATUS, SAVE, RESTORE, etc.) that is not the first command in the sentence, it will discard that command and all that follow it.


• If the parser encounters a movement command in the sentence, it will discard all commands that follow it. This restriction is for technical reasons and may be lifted at a later date.


• Pronouns are set to the last appropriate monster or artifact referenced on a command by command basis, giving preference to the direct object (but note the IobjPronounAffinity flag). "Him" and "her" will refer to monsters with the corresponding gender. "It" and "that" will refer to singular monsters or artifacts. "Them" and "those" will refer to group monsters, plural artifacts, and direct object lists.


• The changing of pronoun references may lead to unexpected results when processing long, complex sentences. In that case, you can avoid (over) using pronouns or enable the ShowPronounChanges flag to get a better idea of what the parser is doing and when - see below.


• Pronoun references are reset when moving between rooms and after the RESTORE command is used.


• While IF parsers typically use recursive descent and syntax trees, the enhanced parser is more like a sophisticated macro preprocessor. That means it doesn't have as much information available and works by keeping track of context and previous player input. Consequently, it can become confused in rare circumstances, depending on player input and the objects it can access. But this situation will likely improve in due time.


• New flags are available in the SETTINGS command related to the enhanced parser. You can revert to legacy Eamon CS parsing by using the EnhancedParser flag. The IobjPronounAffinity flag indicates whether preference should be given to the indirect object (where available) when setting pronouns. The ShowPronounChanges and ShowFulfillMessages flags, originally intended to aid in debugging, have been made available due to their general utility. These enable or disable detailed messages from the parser as it goes about its work.

A document called ENHANCED_PARSER_DEMO on the Eamon CS website shows the enhanced parser being used in Test Adventure. You can refer to this transcript to get an idea of what it can do.

The Eamon CS legacy parser has been enhanced to allow more flexible input. You can enter stuff like "PUT my sword INSIDE my backpack" or "OPEN that jewelry box" or "ATTACK the rats" or "GIVE the spices TO the hermit." The standard [COMMAND] [DIRECT OBJECT] [INDIRECT OBJECT] pattern of Eamon Deluxe remains, but ECS will discard the articles before processing further. Even though it is more typing, some players may find it more immersive. Of course, you can always use the compact syntax if you prefer.

The Eamon CS game engine has been enhanced to support a variety of container artifact types. You can store contents in, on, under, or behind, depending on the container. Under and Behind Containers are similar to In Containers, but cannot be opened or closed and have no key. On Containers have special behavior, the contents are exposed and can be manipulated using any standard command.

The game engine also contains some new commands, summarized below:

1. "INFO" gives information about the played adventure.


2. "SETTINGS" allows you to control a variety of general and game-specific configuration options. You can change your settings at any point. It is a good idea to use this command when a game is started to see what's available to you.


3. "HINTS" gives you a list of hints for the current adventure. You should always carefully read EAMON CS 2.2 GENERAL HELP and EAMON CS 2.2 NEW COMMANDS as these hints may be subtly different than their Eamon Deluxe counterparts. Consider the following:


4. "GO" [door] allows you to pass through a free-standing non-directional door (e.g., the overgrown path in Test Adventure).


5. "INVENTORY" [container] is a parallel to "INVENTORY" [monster]. This command lists the container's contents, and typically only works with In Containers and On Containers.


6. "EXAMINE" or "LOOK" [in|on|under|behind] [container] can also be used to list the contents of a container. These verbs are sensitive to the preposition used and will display the appropriate content list if any. There are a variety of prepositional synonyms available. If you use a preposition unrelated to containment (or none at all), it will result in the default behavior where the description is displayed.

QUICK ARCHITECTURAL OVERVIEW

The entire Eamon CS system was written from scratch and aggressively exploits the C# language. Not just a port, this is an expansive toolkit used to build games based on the Eamon ruleset. It has more in common with traditional Interactive Fiction systems like TADS or Inform. Eamon CS games are built by sub-classing existing classes in any library/plugin, but especially Eamon.dll or EamonRT.dll, and overriding default behavior where needed. You can subclass every class in the system, and generic improvements made to individual adventures can be pushed back into the base framework for use by all games. As time goes on, the system will grow in flexibility and power.

The datafile format used by Eamon CS deserves an explanation. The game produces ASCII XML files representing C# object graphs; each file is further gzipped in its own archive to conserve space. If needed, you can open these files using the 7-Zip utility and right-click to get a context menu to View or Edit. In addition to storing data, these files play a critical role in the development of customized adventures. Take a look in the MONSTERS.DAT file in Test Adventure (a non-customized adventure), and you will see the serialized class is Eamon.Game.Monster (from Eamon.dll). But in The Beginner's Cave, you will see its TheBeginnersCave.Game.Monster (from TheBeginnersCave.dll). These are two different classes, the second is a subclass of the first, and implements custom code that is explicitly used by The Beginner's Cave. Now compare the batch file EditTestAdventure.bat, which contains the command-line argument "-pfn EamonRT.dll" with EditTheBeginnersCave.bat, which includes "-pfn TheBeginnersCave.dll". In the first, the flag instructs EamonDD to load the base game engine. In the second, it loads TheBeginnersCave.dll and uses any customized classes it finds (like the Monster class) when creating new objects. This whole topic is fairly complex and begs to be part of a formal document set, but at least this gives you an idea of how it works.

With BASIC Eamons that use files containing just data, you can bypass the Dungeon Designer program altogether and build these files by hand. You should avoid this practice in Eamon CS due to the specialized datafile format. The EamonDD program is instrumental in producing files of the correct format, and you should rely on it to do so. However, you can still manually tweak the datafiles with 7-Zip. Just be very careful not to violate the XML file format, as the Polenter.SharpSerializer.dll library can be picky.

The EamonRT.dll base adventure runtime takes the form of a Finite State Machine (FSM), which is used to model complex program behavior. The main game loop is very compact; all complex logic resides in subclasses of the State class. Player and Monster commands derive from the Command class, which is itself derived from State. Customized adventures will almost always subclass various States or Commands to provide specialized behavior. It is also straightforward to create new States or Commands and link them into the FSM if needed. Finally, if you look through the code, you will see that using GOTO has been avoided except in specific circumstances (goto Cleanup). Doing this gives the game engine a clean, deterministic quality.

USING THE VISUAL STUDIO DEBUGGER

Eamon CS was built with Visual Studio 2022, a powerful, modern integrated development environment (IDE) used by programmers worldwide. It can be obtained through a link in the PREREQUISITES section. Many tutorials on the web explore Visual Studio in detail; that topic is outside the scope of this document. If you do some research on your own, make sure to focus on using the debugger, which will be the point of this section. The IDE can be used to develop new games, modify existing games, and step through the source code to clarify its inner workings. This discussion assumes VS 2022 on Windows; if you're in a different development environment or a different OS, the steps may vary. To step through the Eamon CS source code, do the following:

1. Make a backup of your repository directory if you downloaded a .zip file. If you Git Cloned the system, you can make a new development branch and focus your work there. Your original branch (or gameplay branch) will remain pristine.


2. In the development directory or branch run EnterMainHallUsingAdventures.bat, and send a character into the adventure you want to step through. You can save the game if you wish, but it is not required; only that the character remains in the adventure. Quit the game, but don't Quit Hall. In this example, we'll step through The Beginner's Cave.

3. Open the Eamon.Desktop solution with Visual Studio.

4. Once Visual Studio loads the game, right-click on the Solution node and select Batch Build.

5. Click the Select All button, then click Clean.

6. Ensure the system is in Debug mode (shown inside red circle). In the Eamon.Desktop solution, right-click on the Solution node and click Build Solution.

7. There should be no errors in the previous steps (see Output Windows). Right-click on the EamonPM.WindowsUnix project and select Set as Startup Project.

8. Right-click on the EamonPM.WindowsUnix project and select Properties.

9. In the Debug General section, click Open debug launch profiles UI and set the Command line arguments to the appropriate string. In this case, the string comes directly from ResumeTheBeginnersCave.bat. You should also add the redraw window flag (-rw) to the end of the string as well. Make sure you save the changes (click the icon inside the red circle). Side note: you can use any string from any .bat file, depending on which program you want to step through, including the Main Hall or the Dungeon Designer. You don't need to send a character on an adventure first to debug these. See the two examples below.

10. Put your breakpoints in the code. In the following examples, the program will break just as it enters the game's main loop, as an attack occurs in combat and in the ReadCommand subclass of The Beginner's Cave. You can set breakpoints anywhere you like in the running program; in our case, that includes EamonRT.dll and TheBeginnersCave.dll.

11. Press F5 to run the program. The game will launch just as if you had double-clicked the ResumeTheBeginnersCave.bat file. If you saved any games, you can restore them at this point as you typically would. You can also start the program or step through it line by line at any point using F10 (step over) or F11 (step into).

BUILDING NEW ADVENTURES

With Eamon CS, it is still possible to send adventurers to their death for fun and profit, even after all these years! You can create new games with the tools available to you. Standard adventures - that is, those that use the EamonRT generic game engine and have no custom programming - can be built without Visual Studio 2022 Community Edition installed. But Custom adventures (like The Beginner's Cave, etc.) require the VS tool suite to be on your system. Up to this point, it has been a manual effort to bootstrap new games. But significant progress has been made towards fully automating the process. You will find in the EamonDD folder under QuickLaunch a new .bat or .sh file that when run, will enable an Adventure Support Menu under Utilities. This file is LoadAdventureSupportMenu:

The Adventure Support Menu allows Eamon CS to integrate seamlessly with Visual Studio using the dotnet.exe program. With the .NET SDK installed, this integration paradigm works in Windows and Unix, even if Visual Studio is absent. But the "gamer-only" .NET Runtime has limited support for custom games; it can generate all needed QuickLaunch and source code files but attempts to manipulate the Eamon.Desktop solution or compile the game will fail. For Custom adventures, if the integration process fails for any reason, you should add the .csproj file to the solution yourself and manually recompile the game.

Before proceeding further, if you downloaded the .zip file for Eamon CS, it might make sense to back up your repository so you can revert if necessary. For those who cloned the repository from GitHub, it might make sense to create a branch for your new adventure so you can back out at any time.

Creating adventures requires entering just a few key pieces of data. The automated process uses resources embedded within the EamonDD plugin:

• Creates the game folder under Adventures
• Generates all needed code (Custom adventures only)
• Creates all necessary QuickLaunch .bat and .sh files
• Adds the game to the appropriate Adventure database(s)
• Adds the game project to Eamon.Desktop.sln (Custom adventures only)
• Rebuilds the game project, producing game library/binary files (Custom adventures only)

Below we see an example of Custom adventure creation where a new game called Walled City of Darkness (Eamon #150) is bootstrapped using the Adventure Support Menu.

The only thing you need to do to play your game is run the corresponding Edit[YourAdventureName] .bat or .sh file and add:

• A Module record
• A Room record

For Custom adventures, a complete set of derived foundational classes (e.g., Engine, Artifact, Monster, Room, etc.) are generated and available for you to modify. The generated classes should be sufficient for many Custom games. But remember, you can always add your own new or overridden classes if you need to get exotic. Two additional menu options, detailed below, allow you to add and remove classes programmatically. Every facet of the system is built to override, so the sky is the limit here. The actual process of game customization using Visual Studio 2022 is beyond the scope of this section. It will be fully documented elsewhere, although there are games available to look at for programming ideas.

Finally, a word about submissions: anyone who wishes to build a game and have it included in Eamon CS should contact me to discuss the matter before beginning any work. The contact info is in AUTHORS.html. You should always build a new game in a unique branch off master, so it cleanly merges when completed. There may be suggestions for improvements when reviewing the code in the branch. It is no cause for concern, just part of the process of building the best game possible. The goal of doing this is to enhance the experience for people who discover Eamon CS and play it in the future. At this point, I have yet to fully work out the logistics of game developer pull requests against master.

CONVERTING EXISTING ADVENTURE DATA

Given Eamon's long history, it should be no surprise a vast back catalog of adventures exists. There is good news for authors interested in porting old games to Eamon CS. EamonDD has built-in utilities to allow easy data conversion for games built in the Apple II and Eamon Deluxe variants. Converted data may include Rooms, Monsters, Artifacts, Effects and, (where available) Hints. While most games are compatible, some may have datafile format irregularities that cause conversions to fail. In this circumstance, the data must be manually converted.

To exploit the data conversion utilities, you should create a Standard or Custom adventure, as described in the previous section; the newly created game should share the ported game's name. Exit the Adventure Support Menu, then run the game's Edit[AdventureName] .bat or .sh file. Avoid adding new records to the game, as they will be overwritten during the data conversion process. From the Main Menu choose U for Utilities, then one for Adventure conversion, and finally one or two depending on the legacy Eamon system. After following the instructions during the conversion process, you can exit to the Main Menu. If the conversion was successful, you see the imported game data; it can be browsed or edited if needed. When you exit EamonDD from the Main Menu using X, be sure to choose Y to save the data.

While the conversion process lightly validates the data coming in, Eamon CS programs aggressively validate loaded data. You may find your converted game fails validation, but the system gives a pretty good error message citing the offending datafile, record, and field. There is a useful command-line flag that can be added to any .bat or .sh file; it disables validation when records are loaded. You can add this flag to your Edit[AdventureName] .bat or .sh file while debugging or polishing the new game, then remove it when finished. You may need to repeat this process as you eliminate the validation errors one at a time.

The flag is: -dv

ADDING CUSTOM ADVENTURE CLASSES

Custom games are created in Eamon CS using the C# mechanism of sub-classing. The system has no sealed classes, and every property and method is declared virtual. You can override any aspect of the game engine to suit your needs. If you want to produce a complex, interesting game with lots of special effects, you will almost certainly need to create new classes for your adventure. There are numerous examples of this in the adventures contained in the Eamon.Desktop solution. It turns out, the layout of folders and namespaces in Eamon CS lends itself to a simple code generation mechanism based on a template discovered while studying the already-created games. You can use the Adventure Support Menu to generate custom classes, complete with matching interfaces (if needed), based on many classes in the Eamon, EamonDD or EamonRT libraries. These generated classes appear in the selected adventure, and then you are free to add your custom code. For any class with a corresponding .DAT file (e.g., Room.cs and ROOMS.DAT), the .DAT file will be updated to reflect the newly added class.

While the code generator works great with classes that fit the template, it may fail with others that don't, so this comes with a caveat. Always verify the generated code is what you are expecting. Depending on the class, sometimes the code will be flawed, and your game won't compile; other times it will compile but be subtly wrong. Visual Studio's Intellisense can help identify problematic code that needs fixing. Since this menu option is intended only as a bootstrapper, you can take the output verbatim or modify it to better suit your needs. Also, remember you can always bypass this convenience and craft your code by hand.

The following example demonstrates the adding of several new classes to the previously created Walled City of Darkness adventure. (Note the adventure has been pre-processed to remove the Hint.cs file.)

1. You have several options when using this menu item. You can generate stand-alone classes, stand-alone interfaces, or class/interface pairs. If you create an independent class and then later decide to generate its matching interface, you will have to update the class manually to derive from the new interface. If you create a matching class/interface pair, the interface won't appear if it already exists. File paths are specified relative to the working directory System.

2. The code generator places classes and interfaces (circled in red) in the adventure folder. The system automatically builds a directory hierarchy that mirrors the Eamon CS base libraries. Classes go under the Game folder, interfaces under Framework. At this point, you can add your custom code.

3. The following screenshots show what the code generator produced. If you compare this output with the games in Eamon.Desktop, you will quickly see parallels between them. You can fix anything Intellisense flags as invalid and hover the cursor over critical parts of the code to ensure it is correct.

4. When adding custom code, type public override, and choose the right property or method from the list presented by Intellisense. It is often useful to refer to (or use code from) the parent classes in the Eamon CS base libraries. The system uses project referencing throughout, allowing quick navigation to any class, method, property, or type definition through a right-click context menu. Double-click on the symbol to look up, then right-click on it and choose one of the appropriate menu options to take you to the code in question. The Peek Definition and Go To Definition menu items are what you'll probably use most often, but there are a few other useful options as well. When you have finished, click the back arrow to return to your previous location. The following example shows quick access to EamonRT's CombatComponent class.

DELETING CUSTOM ADVENTURE CLASSES

You can delete custom adventure classes just as quickly as you add them using the Adventure Support Menu. There are many reasons you may wish to do this. When you create a new adventure via the Add A Custom Adventure menu option, the system generates a complete set of foundational classes for it. But you will often find that you don't need all the classes produced. A generated class is only useful if you plan on overriding methods or properties in it; otherwise, it is just extraneous code bloat. There may be other times you are implementing some unique game behavior when you run into trouble and decide to restart the work or scrap it entirely.

Regardless of the reason, you can use the Delete Custom Adventure Classes menu option to delete one or more classes or interfaces from the game. If you have classes that are reliant on explicitly deleted interfaces your game will not compile until the classes are fixed or removed. If you delete classes, any paired interfaces will automatically delete as well. If the removed class has a corresponding .DAT file (e.g., Room.cs and ROOMS.DAT) it will be updated to reflect the appropriate parent class. There is no undoing this operation so you should back up your work if there is a chance you'll change your mind.

The following example demonstrates the removal of several classes from the Walled City of Darkness adventure.

1. You have several options when using this menu item. You can delete classes, interfaces, or both. File paths are specified relative to the adventure folder.

2. The classes selected for deletion are no longer in the project, and their matching interfaces are gone as well.

3. One of the deleted classes, Hint.cs, has a matching HINTS.DAT file. Notice that the data type is no longer WalledCityOfDarkness.Game.Hint but was reverted to the parent class Eamon.Game.Hint.

DELETING EXISTING ADVENTURES

You can also delete adventures from Eamon CS if the need arises. Maybe you were experimenting with a game scenario that didn't work out or have fully played through a title and want to make space on your file system. Perhaps you don't like an adventure and want to purge it from your Eamon CS repository. Whatever the reasons, the Adventure Support Menu has an option to do game deletion. Choosing this menu option will cause the system to prompt you for some key pieces of data and verify that you want to proceed. If so, it will completely remove all traces of the adventure from your Eamon CS system by doing the following:

• Deletes the game library/binary files (Custom adventures only)
• Removes the game project from Eamon.Desktop.sln (Custom adventures only)
• Removes the game from the appropriate Adventure database(s)
• Deletes the game folder under Adventures
• Deletes the game QuickLaunch .bat and .sh files

As you might expect, once a game has been deleted its data is not recoverable by normal means.

COMMAND-LINE PARAMETERS

Like many C-based programs, EamonPM.WindowsUnix.exe recognizes a set of command-line parameters that can profoundly or subtly impact its functioning. If the same parameter is encountered multiple times on a command line, the last instance always takes precedence. While the QuickLaunch facility hides this complexity, it is still helpful to know what flags are available if you want to run Eamon CS in a non-default manner. When it makes sense, you can integrate these parameters into the existing .bat and .sh files or create customized files of your own for ease of use. If you wish to experiment with it, you can also run ECS directly from a Command Prompt in System\Bin. The following table describes the available parameters and their purpose: