Registering New Expansions        

Adding a New Expansion

Popular commercial games are often followed up by expansions, optional add-ons that extend the game with fresh content. Strange Eons allows components and other objects to be associated with a particular expansion, which provides many opportunities. For example, it allows plug-ins to to determine the particular combination of expansions that are required by a component. The main use of expansions, though, is to include an appropriate expansion symbol on components. An expansion symbol is an icon, usually of small physical size, that may be printed on components so that they can easily be identified and separated back out from the base game. Strange Eons supports expansion symbols through the Expansion menu.

A plug-in for a game will typically register any official expansions that are available. In addition, users will often want to be able to add their own expansion symbols. Strange Eons has a built-in method for painting expansion symbols that works well for many games. It also allows components to paint the symbols themselves in order to support more complex symbol schemes. Users can easily create their own symbols, even for plug-ins that have special painting requirements.

Painting Expansion Symbols on Cards

Expansion symbols are placed on cards in one of two ways. Either Strange Eons uses a built-in standard procedure, or else a plug-in can indicate that for a particular game it will paint any expansion symbols itself. The built-in procedure is flexible enough to handle symbols for most component designs. The main restriction is that the symbol painting is always done last. If your component design calls for painting over the symbol, you'll have to use custom painting.

Standard Painting

The built-in painting mechanism is suitable for many component types. Although it may look complicated at first glance, there is actually very little to do from the plug-in developer's perspective. The following checklist summarizes what you need to do:
  1. In the extension plug-in, register your game (if applicable).
  2. If you wish to use variants other than the default, create an ExpansionSymbolTemplate that describes them and register it with the game.
  3. Register any standard expansions for the game. Each expansion will define an icon (for use in the user interface) and one or symbol images (one for each variant).
  4. For any component face that should display an expansion symbol, add a settings key with the same base name as the template key but with -expsym-region instead of -template at the end. Set this to the region where the symbol should be painted.
  5. If one of the variant versions of the symbol should be used as the default, also add a key with -expsym-invert and set it to the numeric index of the variant.
  6. If some expansions should be located in a part of the component other than the default, add variant regions for those expansions (see below).
  7. If the game's design allows for multiple expansion symbols to be present on a component, test components with multiple expansions to determine if the expsym-margin should be adjusted (see below).

The following is a detailed description of the procedure Strange Eons uses to paint expansion symbols:
  1. After all other painting is done, Strange Eons looks to see if the card has a region defined using the standard expansion symbol key. The consists of the base expansion setting key with -region appended. The base key consists of the setting key for the template image, with -tempate removed from the end (if present) and -expsym added instead. So if the template key for the component face is my-front-template, then the region would be looked for in my-front-expsym-region. If this key is not defined, then the process ends immediately.
  2. Strange Eons looks at the value of the GAME setting to find the code for the game that this component is from.
  3. It gets the matching Game instance by calling Game.get( code ).
  4. It gets the ExpansionSymbolTemplate for the game by calling Game.getSymbolTemplate().
  5. If the template's isCustomDrawn() method returns true, then Strange Eons stops using the standard mechanism.
    Note: The above steps may fail for a number of reasons. For example, the component might not have a GAME setting. In such cases, Strange Eons always proceeds with the standard mechanism as long as there is a region defined.
  6. Strange Eons looks up the code of the expansion(s), if any, associated with the component. This is stored in the active-expansion settings key. If the key not defined, then it is treated as if set to the code for the base game. (This code is NX, for no expansion.)
  7. If an expansion other then the base game expansion is set, then Strange Eons looks up which variant of the symbol it should use. This is done by first checking if the user has set a specific variant. If not, a default is looked up using a key consisting of the expansion symbol base key name with -invert appended (my-front-expsym-invert for the above example). The suffix -invert is a historical holdover from earlier versions of Strange Eons that only used dark and light (inverted) variants of a symbol. The value of the key can either be a standard boolean value (yes/no or true/false), or it can be a numeric index. If the key is undefined, false, no, or 0, then symbol variant 0 is selected. If it is true, yes, or 1, then symbol variant 1 is selected. Other non-negative integers (2, 3, etc.) select the variant with that index. If neither a user nor default variant is specified, then variant 0 will be used.
  8. Once the variant number is known, Strange Eons looks up the Expansion instances for the selected expansions using Expansion.get( expansionCode ). For each expansion, if it exists, then it is asked to provide the correct symbol image using Expansion.getSymbol( variantNumber ).
  9. At this point, Strange Eons checks to see if there is a more specific region for this combination of component type and expansion codes. If the settings key base-key-expsym-code-region is defined, then this region will substitute for the default region looked up earlier. So the key my-front-expsym-DH-region will be checked for the my-front template when the active expansion has the code DH. (Note the default region must be defined for any painting to take place; it is not enough to define only more specific keys.)
  10. Finally, Strange Eons paints the selected symbol variant(s) at the position and size determined by the region key (either the first one or the more specific one that is checked later). If there is only one expansion selected, it is fit within the region. If multiple expansions are defined, they will be drawn in a row, with each symbol sized to fit the expansion symbol region. This row will be centered over the original symbol region. It is then constrained to fit within the card, and further constrained to fit within both the bleed margin, if defined, and an additional margin. The default margin size is 6 points, but it can be customized by setting an expansion key with the suffix -margin. The following diagram illustrates this process:

Diagram depicting how expansion symbols are drawn by default
When painting a single expansion symbol (far left), the symbol is drawn to fit in the defined expansion symbol region (red dashed box). Drawing multiple symbols is a two-step process. First the symbols are drawn in a row and centered (blue dashed line, center image) over the expansion symbol region, then the ends of the row are adjusted to fit between the margins (green dashed lines, right image). If the row of expansion symbols is too wide to fit between the margins, then it will be scaled down until it just fits.

Custom Painting

If the ExpansionSymbolTemplate for a Game states it uses custom painting, then Strange Eons will not do any painting itself. It will be up to you to add your painting code to your existing paint functions. You'll need to do this, for example, if a decoration should be painted on the card to contain the expansion symbol when present, or if anything must be painted over the symbol.

Contributors to this page: Chris Jennings .
Page last modified on Wednesday 19 of December, 2012 10:55:00 EST by Chris Jennings.