Strange Eons

Customization Tutorial

Send Feedback      Home Page > Strange Eons > Miriam's Basement > Customization > Tutorial

Enemy Cards: A Customization Example

This tutorial demonstrates how to write an extension that adds a new kind of card ("Enemy" cards) based on the existing Ally card. You could make Enemy cards using the "Miscellaneous Small" card, but it wouldn't use the rounded portrait that appears on Ally cards.

This tutorial demonstrates one kind of customization: making small changes to a an existing component type. For more extensive changes, you can instead create an entirely new kind of component. If that is what you want to do, read the DIY Tutorial.

Prerequisites

Before getting started, there is some background information which will make this article much easier to follow. First, you should make sure you understand how to extract the Strange Eons resources to a folder. Second, you may want to have a look at the basic extension tutorial, which adds a new expansion symbol to the list of expansions that can be selected for a component.

To make our custom card type, we will modify the text and images that are used for Ally cards.  We will do this by changing the values of certain SE "settings" that can be found in the SE resources. However, we still want to be able to create "regular" Allies, so we want to add a new entry to the New Component dialog that starts by creating an Ally but then tweaks the settings just for that card to use the new settings that we want.

In order to find out which settings we need to change, we'll refer to a copy of the SE resources. If you don't already have a copy, it's easy to get one. Have a look here for instructions.

Figuring Out the Right Settings Changes

To make our new Enemy cards, we will change the ally cards so that the word "Ally" at the top of the card is replaced with "Enemy", and we will add new graphics to make the card red instead of orange. To start with, we will look through our extracted copy of the SE resources to figure out which settings to change.

First the text. The text printed on cards for a given game language is stored in that language's card-text.txt file. The files for a given language are in resources/text/XX, where XX represents your standard game language. This will be EN for English, FR for French, ES for Spanish, and so on. Normally it is best to use the English text for reference, because it is always complete. The English file can be found in the resources at resources/text/EN/card-text.txt.

Open the card-text.txt file in a plain text programmer's-style editor. (The best editor to use is the Strange Eons Text Resource Editor.) Now locate the key that defines the text used at the top of Ally cards. Here is the line:

ally-text = Ally

As you might expect, the word "Ally" would be different if the file was one for another game language. For example, in the French file, the line reads:

ally-text = Allié

Patch.card( Component, "ally-text", "Enemy" );
Editor.forceRerender();

ally-front-sheet-template = templates/ally-front.jp2
ally-back-sheet-template = templates/ally-back.jp2

Original game graphics copyright 2005
Fantasy Flight Publishing, Inc.

Make sure that you keep the front face template in .png format, because .jpg images do not support transparency. We need transparency for the portrait area in the center.

OK. So we have our modified art, and we know which settings keys we need to change in order to use it. We also know the key we need to change the title to "Enemy". Now we just need to put it all together.

Finishing Up: Making the Leap to an Extension Plug-in

Playing with private settings in the Quickscript window is fine (and useful when experimenting or debugging), but ultimately we would like to have "Enemy" component that we can create from the New Component Dialog, just like all of the standard component types. To do this, we will need to write some small programs, called scripts. If you are not a programmer, don't worry. Most customization projects don't require real programming skill; you can use one of the examples in the plug-in authoring kit as a starting point and change it to suit your needs.

Plug-ins are composed of a number of files, but to make things convenient for users of the application, we package the files for a plug-in up into a "plug-in bundle."

As with our introductory example of how to write an extension, we will create a project to manage various files needed by our plug-in. In the project we'll create a plug-in task with an eons-plugin root file and a resources folder. Inside the resources folder, we'll create a subfolder using our initials or some other unique identifier (for the purposes of the tutorial page, we'll use tut), and inside of that we'll put the materials for our plug-in.

Let's start by setting up the project and adding an empty plug-in task:

To finish the plug-in, we will need to create the following files:

1. Our plug-in script. This tells SE what to do when it starts the plug-in, and it provides basic information about the plug-in like the name and version. Our plug-in needs to tell SE to read in a new "class map", which is a file that tells SE about new kinds of game components we want to add.
2. We'll also have to create the class map file that we tell SE to read. This will tell SE about our new Enemy cards, and it will name a script that SE can run when the user wants to make a new Enemy.
3. Likewise, we'll also need to write the script that we tell SE about in the class map. The script simply makes a new Ally, then applies the changes we figured out above.
4. A root file. Every plug-in needs a "root file" with the name eons-plugin file. This file is checked by SE when it loads the plug-in, and it tells it where to find our plug-in script. The plug-in task will make it very easy to create this file.

Once we have all of the parts, we will pack them up in a bundle and install the plug-in!

Let's start by creating the script for the plug-in. Right click on the tut folder and choose New | Blank Script. Name the script enemy-extension.js (just type the name, SE will provide the .js), then open it for editing by double clicking. Delete the initial text (Edit | Clear). Carefully paste in the following code, and then save the file:

uselibrary( "extension" );

function getName() {
    return "Enemy Card Extension";
}

function getDescription() {
    return "Adds the option to create Enemy cards.";
}

function getVersion() {
    return 1;
}

GameData.parseEditors( "tut/enemy.classmap" );

The first line of this script declares it to be an "extension" type of plug-in. This type of plug-in can modify the game database, and doesn't get listed as a selectable command in the Toolbox menu. Our plug-in must be an extension in order to add a new entry to the New Component dialog. The next few lines define functions that the plug-in system calls to learn basic information about the plug-in. This information is used to describe the plug-in in the Plug-in Manager dialog.

Our class map file will only add one entry, so it will be pretty simple. To create it, right click on the tut folder and then choose New | Class Map. Open the file for editing. The comments at the top of the default file describe the syntax of class map files in detail. Read it over if you like. When you are done, delete the initial text from the file and paste in:

@cat-custom
  Enemy Card = script:tut/create-enemy-card.js

I'm sure you can guess that next we'll write the create-enemy-card.js script. That script will basically just do the same things that we did by hand before by changing the card settings, but it does them only for the particular card that it creates. Create a new blank script as before, calling it create-enemy-card.js. Open the file, delete the initial content, and paste in:

// create a standard Ally card and make it the active editor
if( PluginContext.createEditor( "ally" ) ) {
    var editor = PluginContext.activeEditor;
    var component = editor.gameComponent;

    // customize the new component
    Patch.card( component,
        "ally-text", "Enemy",
        "ally-front-sheet-template", "tut/enemy-front.png",
        "ally-back-sheet-template", "tut/enemy-back.jpg"
    );

    // clear the example text and/or install a new example if desired
    component.clearAll();

    // once all modifications to the content of the component have been
    // made, call this method to copy the changes to the editor
    editor.replaceEditedComponent( component ); 
    component.markSaved();
} else {
    error( "Failed to create base component" );
}

The PluginContext.createEditor method creates a new component and makes its editor the active editor. The type of component that is created is determined by the single parameter, which is the name of a key in one of the registered class maps. The standard components have keys that start with "app-new-" for historical reasons. As a shortcut, you can leave this prefix off (the actual name of the Ally component key is app-new-ally). The names for other component types can be found in the in the standard SE class map, resources/editors/standard.classmap.

The next two statements obtain the editor (the window used to edit the component) and the component itself. Once we have the component, we can use the Patch object to modify the component's settings just as we did above in the Quickscript window. You'll note that we've added two more pairs of patch parameters, to patch the template images to use our red image files.

The line component.clearAll(); will clear the card's settings as if we had used the Edit | Clear command. That gets rid of the example text you normally get when you create a new component—after all, that example is for an Ally, not an Enemy. If we wanted, we could modify the name, effects, and comments to create a different example at this point. (Use the Component Viewer plug-in to list the methods that can be used to modify a component. It is built-in to SE but may be inactive by default; open the Plug-in Manager and check its "Active" box in this case.)

Once we have made all of the changes to the component that we wish, we call editor.replaceEditedComponent() so that the editor will update to reflect our changes. Finally, we call component.markSaved(). This causes the component to "forget" that it was changed (when we cleared it). If we didn't do that, the new card would appear to have unsaved changes even though the user hasn't modified it yet.

That's it for scripting, but we still need to create the plug-in root file so SE knows which file contains the plug-in code. To do that, right click on the Extension Plug-in task folder and choose New | Plug-in Root. SE will create the file and open the root editor. Since our plug-in is in enemy-extension.js, select that entry and then press Update:

Now we just need to package the plug-in up in a bundle so we can install it. Right click on the plug-in task folder and choose Make Bundle. When the rename dialog opens, enter the name EnemyExtension, then click on the .seplugin to the right of the name field. That will let us change the extension, which we need to do because this is an extension. Change the extension so that the name field reads EnemyExtension.seext and rename the bundle.

To test the plug-in, right click on the bundle and choose Test Plug-in. This will allow you to test the plug-in in a special test version of Strange Eons. On some platforms you may need to adjust the "JVM" options in order to launch the test application. If you have problems using the test command and don't know how to adjust the JVM options for your system, you can simply install the bundle and restart Strange Eons to test it that way.

EnemyExtension.seext

Return to Home Page    Send Feedback

April 28, 2008  — Updated February 27, 2010