[Note: this document is a work in progress]
Welcome to the first of a series of documents that will detail the steps required to build a new Eamon CS game. It is a real hands-on tutorial, perhaps even laborious in places, but it should give you an idea of what is necessary to make the magic happen if you follow along. This discussion will not spare the technical jargon, but I will try to explain it clearly. A basic working understanding of C# is assumed; if needed, you can find tutorials out on the web for any complex topics skimmed over. Please let me know if there are areas that need clarification.
The first game built will be called "Riddles of the Duergar Kingdom." This adventure will dig into many facets of the Eamon CS game engine to show its capabilities. It should be mentioned - WARNING: HEAVY SPOILERS; you may wish to play the game before returning to this treatise.
I'll start by bootstrapping the game using the Adventure Support Menu:
2: Utilities1: Adventure Support2: Add Custom AdventureRiddles of the Duergar KingdomMichael PennerMPNYYAt this point, the game should exist. The EamonDD program creates a folder called Adventures\RiddlesOfTheDuergarKingdom to store the source code files, adds the appropriate .bat and .sh files under QuickLaunch, and places a compiled RiddlesOfTheDuergarKingdom.dll file in System\Bin. The game is added to the Work-In-Progress Adventures database, which is only accessible using EnterMainHallUsingCatalog.bat. To verify everything worked, I can run EditRiddlesOfTheDuergarKingdom.bat (or .sh for Unix) and ensure EamonDD loads the adventure. Then I can leave the game editor running, as the game is not yet playable and needs a few records added. That is the next section's topic.
The game will not be playable until a Module record, and Room record are added. I will omit the more involved details of both these records when entering them initially.
2: Module record maintenance1: Add a Module recordRiddles of the Duergar KingdomTODOMichael PennerMP-003011012YX3: Room record maintenance1: Add a Room record1: Add a Room record manuallyHigh Plain, Gully Base
You have arrived at the base of a rock-strewn gully on a high plain in the shadow of Mount Everdes. The extinct volcano looms to the northeast against a sunny sky. The wind blows off its arid slopes through the purple
sage and whips up an **150
1-999The oversized Room Description property requires an Effect record to be added (note **150), but I can ignore that for now as the game engine will still process it properly. The topic of Effect record chaining will be examined in the next section when I fill in the Module's Description and Intro Story properties.
It's looking good so far, but there are a few loose ends to tie up. Both records need their Description fields set, while the Module record needs its IntroStory field set. These properties can be entered individually in EamonDD through the appropriate Edit One Field record menu or manually into the corresponding .DAT file using the 7-Zip utility. For the Module's Description, I'll enter the following text:
Mount Everdes, an extinct volcano located in the Horn Belt's southern reaches, is mostly unexplored. But Eamon
University's Department of Archaeology has made a compelling discovery on its steppes and requires assistance to
quantify the site's **250
The interesting thing about this text is the **250, which is an example of Effect record chaining. That causes the game engine to look up Effect Uid 250 and then replace the link with the Effect's Description text, as such:
Mount Everdes, an extinct volcano located in the Horn Belt's southern reaches, is mostly unexplored. But Eamon
University's Department of Archaeology has made a compelling discovery on its steppes and requires assistance to
quantify the site's scope. Sharpen your sword and pack your bags, for who knows what lurks under that mountain?
This example is the simplest form of Effect record chaining; you can read all about the topic in the Eamon CS Dungeon Designer's Manual.
Next, I'll enter the Room's Description as follows:
You have arrived at the base of a rock-strewn gully on a high plain in the shadow of Mount Everdes. The extinct
volcano looms to the northeast against a sunny sky. The wind blows off its arid slopes through the purple sage
and whips up an **150
When the corresponding chained Effect Uid 150 is entered, the game engine prints the Room's Description like this:
You have arrived at the base of a rock-strewn gully on a high plain in the shadow of Mount Everdes. The extinct
volcano looms to the northeast against a sunny sky. The wind blows off its arid slopes through the purple sage
and whips up an occasional dust devil. The Main Hall and comforts of home lie many leagues to the west.
Finally, I'll enter the Module's IntroStory property; this is the Effect Uid that begins the introduction story's text. For this game, it is Uid 200:
There comes a day in late spring when you notice a great commotion in the Main Hall. Investigating, you are
informed that Eamon University's esteemed Department of Archaeology has discovered an ancient mining camp during
one of its periodic digs. **201
Notice that the Effect Description is chained to another Effect Uid 201 that provides the next section of text in the introduction story:
The site is carved into a basalt overhang on the steppes of Mount Everdes, an extinct volcano located in the
southern regions of the Horn Belt. It is heralded as the most significant find since the Department's
unfortunate encounter with the **202
Notice that the Effect Description is chained to another Effect Uid 202 that provides the next section of text in the introduction story:
infamous "Runcible Cargo" years ago.*203
The interesting thing about this text is the *203, which is a different example of Effect record chaining. That causes the game engine to look up Effect Uid 203 and then replace the link with a blank line (CRLF x 2), followed by the Effect's Description text, as such:
.
Later that week, a notice appears, and you soon discover it. You elbow your way through a small but growing
crowd outside Sam Slicker's store, coming upon a message nailed to a signpost that gives additional
information:@@PB**204
The interesting thing about this text is the @@PB**204, which is a different example of Effect record chaining. That causes the game engine to look up Effect Uid 204, process a page break request, and then replace the link with the Effect's Description text, as such:
.
------------------------------------------------------------------------------
.
Press any key to continue:
.
------------------------------------------------------------------------------
.
"To Whom It May Concern,*205
For reference, Effect Uids 200 through 211 contain the entire introduction story; you can look at these Effects to see how it is linked together. The remaining story sections will be omitted from this tutorial as they are variants of what has already been presented.
Here are a few other things I'd like to note for completeness. These aren't necessarily relevant to Riddles of the Duergar Kingdom but are used by other adventures in many cases. See the Eamon CS Dungeon Designer's Manual for more detail on these topics.
Another sophisticated form of Effect chaining injects text strings returned by functions stored in the Eamon.Game.Plugin.Engine.MacroFuncs dictionary. Introduction stories that utilize this technique can change
based on game state, for example, the use of the player character's name in Wrenhold's Secret Vigil. These lookups are specified by @YYY or @@YYY link codes, mirroring the other codes' text injection behavior. In this case,
YYY must be unique as it represents the dictionary key of each function. Functions are usually carefully-written lambdas added to MacroFuncs during game initialization.
You should be aware of the EamonRT.Game.IntroStory class, which implements the introduction story behavior for Eamon CS. This class supports both "Beginner's stories" - which prevent overpowered characters from
entering the game - and standard stories using the EamonRT.Framework.Primitive.Enums.IntroStoryType enum. You can override the various properties and methods to change completely how the introduction story is used
or presented.
The numbering sequence used for Effect Uids in Riddles of the Duergar Kingdom is deliberate. Grouping related Effects together sequentially is optional but makes them easier to find and improves the logical layout of the EFFECTS.DAT file. It may also lead to gaps between Effect Uid sets, depending on how the game's collection of Effects is created. These gaps are perfectly acceptable since Eamon CS uses a database to store records instead of arrays as with older Eamon systems. I'm using the following Effect Uid sets for this game, but you may need to adjust these depending on your game's needs:
Effects organized using this strategy can be created in one of two ways. The EFFECTS.DAT datafile can be directly edited by those familiar with its format; this may be the easiest solution. EamonDD can also be used, but its default behavior automatically assigns Uids to new records. Changing the Config record allows Uids to be set explicitly, but EamonDD will revert back to its default behavior when the program restarts:
1: Config record maintenance1: Edit a Config record2: Edit one field of a Config record3: Generate Uids0YThe game is generated with a default set of Hint records in HINTS.DAT, but they require Effect chaining for full implementation. There are two ways to accomplish this task. The first requires knowledge of text file formats and involves copying the corresponding Effect records from an existing game into the new game and backpatching where appropriate. The second involves using EamonDD in explicit Uid mode. Here are the expected Effect record Uids and Descriptions:
Now that the preliminary stuff is out of the way, I can move onto more interesting things. Developing a new Eamon adventure can be a bit daunting; each game author approaches it differently, no doubt. It has been like this from the very beginning. There are at least two obvious ways to build a new game. The first is to create a comprehensive design document that describes it. That is the best way to develop an adventure with an over-arching storyline and complex interlocking acts. Still, it can be quite challenging (I've discovered), as it requires advanced writing skills and an extended period of front-loaded planning. As a side note, The Wayfarer's Inn has stalled for this very reason; there hasn't been time to put the document together, let alone implement it. My past preference was to build games that revolved around exploration with lots to see and do, and that lends itself to a second design technique: starting with a vague but compelling premise, then building out the game as a collection of regions, and tying them together as the game evolves. The interconnections between regions deepen as monsters, artifacts, special effects, and puzzles are added; the story, such as it is, can also be fleshed out. For the simplicity of creating this tutorial, Riddles of the Duergar Kingdom will take the second approach. With that decision made, the question becomes: what to build first? The easiest approach is to create the rooms, link them together, then populate the map with monsters and artifacts, so that's where I'll start.
IMPORTANT: When using EamonDD to add or update records, always exit the program cleanly from the Main Menu, and when it asks if you want to save modifications, respond with Y (if you wish to keep them).