PAK reorg phase 2 (#4)

- update script code to use method notation where possible
 - add READMEs specific to most plug-ins
 - update yellow sign icon
 - update Prototype plug-in's reference to an application icon

Plug-in Authoring Kit/Basics-of-scripting/benchmarks.js

@@ -1,24 +1,24 @@
 /*
- * benchmarks.js - version 4
+ * benchmarks.js - version 5
  *
  * The script runs a series of timed tests and prints the
- * results, to give you a sense of the performance of the
+ * results to give you a sense of the performance of the
  * script engine. As a side effect it also demonstrates
  * various features of the language and script engine, so
- * it may be useful for programmers who are familiar with
- * other languages to get a quick overview of JavaScript.
+ * it's helpful for programmers who are familiar with
+ * another language to get a quick overview of the flavour
+ * of JavaScript used in Strange Eons.
  *
- * Note: depending on your system, these tests may take
- * from several seconds to several minutes to complete.
+ * Note: depending on your system, these tests will take
+ * several seconds to complete.
  */
 
 importClass(java.lang.System);
 
 /**
- * time( func )
- * Calls the function <tt>func</tt> with no arguments,
- * and returns the (approximate) number of nanoseconds
- * that the function took to execute.
+ * Calls the function `func` with no arguments
+ * and returns the approximate number of nanoseconds
+ * that the function took to execute.
  */
 function time(func) {
     let start = System.nanoTime();
@@ -75,7 +75,7 @@ const TESTS = [
     function interface_implementor() {
         for (let r = 0; r < 100; ++r) {
             let listener = new java.awt.event.ActionListener() {
-                actionPerformed: function() {
+                actionPerformed() {
                     1 + 1;
                 }
             };
@@ -85,11 +85,11 @@ const TESTS = [
         }
     },
 
-    // instantiate a JavaScript object with method 100 times and call each instance 1000 times
+    // instantiate a JavaScript object with a method 100 times and call each instance 1000 times
     function function_caller() {
         for (let r = 0; r < 100; ++r) {
             let listener = new Object() {
-                actionPerformed: function() {
+                actionPerformed() {
                     1 + 1;
                 }
             };
@@ -316,9 +316,8 @@ const TESTS = [
 ]; // END OF THE ARRAY OF TEST FUNCTIONS
 
 /**
- * runTests()
- * Repeatedly times each function in tests,
- * printing the name of each test and its best time.
+ * Repeatedly times each function in `TESTS`,
+ * printing the name of each and its best time.
  */
 function runTests() {
     const REPS = 5;

Plug-in Authoring Kit/Basics-of-scripting/console-components.js

@@ -27,7 +27,7 @@ let okBtn = new JButton('OK');
 let yellowSign = ImageUtils.get('project:pak-assets/yellow-sign.png', true);
 
 okBtn.addActionListener(
-    function actionPerformed() {
+    function actionPerformed(event) {
         println('\nHey there, ' + nameField.text + '.');
         println('Tell me, have you seen the yellow sign?');
         Console.printImage(yellowSign);

Plug-in Authoring Kit/Code Snippets and Demos/fonts-in-families.js

@@ -12,25 +12,20 @@
 
 const fontMap = {};
 const allFonts = java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment()
-    .getAllFonts();
-
-for (let i = 0; i < allFonts.length; ++i) {
-    // Notice that we explicitly convert all of the Java strings
-    // to JavaScript strings; if we didn't, then JSON.stringify
-    // would not work as intended.
-    let f = allFonts[i];
-    let family = String(f.getFamily());
-    let mapping = fontMap[family];
-    if (!mapping) {
-        mapping = {
-            names: [],
-            logicalNames: []
-        };
-        fontMap[family] = mapping;
-    }
-    mapping.names.push(String(f.getFontName()));
-    mapping.logicalNames.push(String(f.getName()));
-}
+    .getAllFonts().forEach((font) => {
+        let family = String(font.getFamily());
+        let mapping = fontMap[family];
+        if (!mapping) {
+            mapping = {
+                names: [],
+                logicalNames: []
+            };
+            fontMap[family] = mapping;
+        }
+        mapping.names.push(String(font.getFontName()));
+        mapping.logicalNames.push(String(font.getName()));        
+    });
+delete fontMap.Dialog;
 
 //
 // Now fontMap["familyName"] returns an object like this:

Plug-in Authoring Kit/Game-component-examples/Bleed Margins/README.md

@@ -0,0 +1,13 @@
+# Bleed Margins
+
+This demonstrates how to include a bleed margin and/or rounded edges
+in your component design. All of the interesting bits are in
+`bleed-margin.settings`.
+
+Right click and **Run** `bleed-margin-diy.js` to play with the example.
+Then try the various **View/Edge Finish** options to see the component
+with or without its bleed margin and rounded edges.
+
+You can also try **View/Unsafe Area** and **View/True Face Edge**
+to see the effect of these options. (Try enabling them with
+**Edge Finish** set to **Include Bleed Margin** first.

Plug-in Authoring Kit/Game-component-examples/Design Support/README.md

@@ -0,0 +1,23 @@
+# Design Support
+
+This demonstrates how to create design supports. A design support
+is an extra user interface element that provides feedback on
+the design. For example, if the design breaks one of the game's
+rules, the design support could indicate that.
+
+There are three examples you can right click and **Run**.
+For each, be sure to edit the field to see how the design
+feedback changes.
+
+`design-support-diy1.js`  
+Creates a simple support using the default "verbal feedback"
+design support component.
+
+`design-support-diy2.js`  
+A more complex use of the same "verbal feedback" model that
+highlights how the user's actions change the provided
+feedback over time.
+
+`design-support-diy3.js`  
+Demonstrates how to create your own custom "view" (user interface
+element) instead of the built-in verbal feedback component.

Plug-in Authoring Kit/Game-component-examples/Design Support/resources/example/design-support-diy3.js

@@ -45,19 +45,19 @@ function createInterface(diy, editor) {
         analysis: '',
         changed: true,
         valid: true,
-        getGameComponent: function getGameComponent() {
+        getGameComponent() {
             return diy;
         },
-        markChanged: function markChanged() {
+        markChanged() {
             this.changed = true;
         },
-        isDesignValid: function isDesignValid() {
+        isDesignValid() {
             if (this.changed) {
                 this.updateAnalysis();
             }
             return this.valid;
         },
-        createSupportView: function createSupportView() {
+        createSupportView() {
             // we can return any component we like,
             // in this case we'll just return a simple label
             let view = label();
@@ -66,7 +66,7 @@ function createInterface(diy, editor) {
             view.background = new Color(0xfaffc4);
             return view;
         },
-        updateSupportView: function updateSupportView(view) {
+        updateSupportView(view) {
             // if the "analysis" is out of date, update it
             if (this.changed) {
                 this.updateAnalysis();
@@ -76,7 +76,7 @@ function createInterface(diy, editor) {
             // set its text to our analysis string
             view.text = this.analysis;
         },
-        updateAnalysis: function updateAnalysis() {
+        updateAnalysis() {
             // reset the changed flag so we don't do another analysis
             // until the component changes
             this.changed = false;

Plug-in Authoring Kit/Game-component-examples/Multiple and Custom Portraits/README.md

@@ -0,0 +1,19 @@
+# Multiple and Custom Portraits
+
+This contains three examples you can right click and **Run**
+to test some more advanced uses of portraits:
+
+`multi-portrait-diy.js`  
+Demonstrates how to create a component with more than one
+portrait. Also demonstrates how to create a portrait that
+the user can rotate.
+
+`linked-multi-portrait-diy.js`
+Demonstrates how to create a linked portrait. That is, a
+portrait that uses the same image as another portrait,
+but is drawn separately and has its own pan and scale settings.
+
+`roving-portrait-region.js`  
+Demonstrates how to create a portrait that can move to different
+locations depending on how the user changes the game component
+state.

Plug-in Authoring Kit/Game-component-examples/Prefab/README.md

@@ -0,0 +1,20 @@
+@ -0,0 +1,19 @@
+# Prefab
+
+This example includes two "prefab" components you can try by right clicking
+and **Run**ning their script files.
+
+A [prefab component](http://se3docs.cgjennings.ca/dm-diy-prefab.html)
+is one whose design is controlled by its `.settings` file.
+The `-diy` script is just a *stub* that loads the `prefab` library and
+says which setting keys to use.
+
+`prefab-diy.js`  
+This prefab includes a heading, body text, and portrait.
+
+`prefab2-diy.js`  
+This example demonstrates how the default behaviour of a prefab component
+can be customized using before and after functions. It adds a page
+shape that restricts the text to fit inside the white oval.
+(Use **View/Region Boxes** to make the page shape visible as a dashed
+blue line.)

Plug-in Authoring Kit/Game-component-examples/Prototype/README.md

@@ -0,0 +1,88 @@
+# Prototype
+
+This example plug-in registers six new game component types.
+They are intended to be used to create quick prototype cards
+for games. The six card types are two different common
+playing card sizes (poker and bridge) in portrait layout,
+landscape layout, and with a portrait image.
+
+## Running the examples
+
+One way to test the plug-in is to right click on it and choose
+**Test Plug-in**, then choose **Test**. The new card types
+will be found in the **Miscellaneous** category.
+
+You can also try it out without building it by running the
+diy scripts directly. If you try right clicking on
+`poker.js` and choosing **Run**, the card will appear but
+you will also get an error message (`#proto-deck` is not defined).
+This happens because this plug-in is designed to be translated
+into multiple languages, and the translated strings are missing.
+You can get around this by right clicking on the string table
+(`game.properties`) and choosing **Merge Strings Into/Game Language**.
+Now if you right click and **Run** `poker.js` it will work as expected.
+You still won't get the same experience as using **Test Plug-in**,
+because the custom font used by the cards hasn't been
+loaded—but it will run!
+
+## Tour of the files
+
+`plugin.js`  
+This is the main plug-in script. It loads the translatable strings,
+card template settings, custom font, and the class map (which adds
+the new card types).
+
+`plug-in.png`  
+This image is used to create an icon for the plug-in. (You'll see
+this icon in the **Plug-in Manager**, for exmaple.)
+
+`prefab-ext`  
+This is a shared library used by all of the card DIY scripts. It
+loads the standard `prefab` library and then customizes it.
+(See the **Prefab** example for an introduction to prefabs.)
+
+`bridge.js`, `bridge-ls.js`, `bridge-im.js`  
+The diy scripts for the bridge-sized cards (portrait, landscape,
+and portrait with image).
+
+`poker.js`, `poker-ls.js`, `poker-im.js`  
+The diy scripts for the poker-sized cards.
+
+*The diy scripts are all simple stubs because this example uses
+prefab components.*
+
+`poker-tpl.png`, `bridge-tpl.png`  
+The template images for the poker and bridge-sized cards.
+
+`poker-ls-tpl.js`, `bridge-ls.js`  
+These are [resource creation scripts](http://se3docs.cgjennings.ca/dm-res-image.html#resource-creation-scripts).
+When loading using `ResourceKit.getImage()` they will create the
+landscape versions of the template images using script code that
+rotates the portrait images.
+This is a fancy way to do it. You could just as easily
+rotate the templates in a paint program and save them as `.png`
+images just like the portrait images.
+
+**Note:** These scripts won't work as expected unless you install
+the plug-in or run it with **Test Plug-in**.
+
+`Unkepmpt-Regular.ttf`  
+This is the font file that contains the custom font used on the
+prototypes. As mentioned above, to see it in use you have to
+build and install the plug-in or use **Test Plug-in**. However,
+you can explore the font by double-clicking on it.
+
+`game.properties`  
+This is the string table. It assigns named keys to a set of strings.
+Then those strings can be referred to by their key, so that
+translated versions will be used when running in a different game
+language. You can add a translation by right clicking and choosing
+**Add Locale**.
+
+`layout.settings`  
+This file defines settings that direct the prefab library as to how
+to lay out the cards.
+
+`proto.classmap`  
+This is used to register the new card types with Strange Eons.
+(The registration step happens in `plugin.js`.)

Plug-in Authoring Kit/Game-component-examples/Prototype/resources/proto/layout.settings

@@ -34,7 +34,7 @@ bridge-im-content = #proto-content
 bridge-im-content-region = 20,315,298,190
 bridge-im-content-style = family: 'Unkempt'; size: 12
 bridge-im-content-alignment = left, top
-bridge-im-portrait-template = icons/application/256.png
+bridge-im-portrait-template = icons/application/app@16x.png
 bridge-im-portrait-clip-region = 20,100,298,190
 # creates an 1 pixel invisible overlay so the portrait is
 # drawn overtop of the card template instead of under
@@ -52,7 +52,7 @@ poker-im-content = #proto-content
 poker-im-content-region = 20,315,335,190
 poker-im-content-style = family: 'Unkempt'; size: 12
 poker-im-content-alignment = left, top
-poker-im-portrait-template = icons/application/256.png
+poker-im-portrait-template = icons/application/app@16x.png
 poker-im-portrait-clip-region = 20,100,298,190
 poker-im-portrait-overlay = icons/1x1.png
 poker-im-portrait-overlay-region = 0,0,1,1

Plug-in Authoring Kit/Game-component-examples/Register Game/README.md

@@ -0,0 +1,33 @@
+# Register Game
+
+This example demonstrates how to
+[register a new game, and how to register an expansion for that game](http://se3docs.cgjennings.ca/dm-register-game.html).
+
+## Registering a game
+Registering a game lets you group all of the related game components under that
+game's name. For example, in the **File/New** dialog, you can choose to filter
+the listed components so that only those from a certain game are shown.
+Plug-ins can also declare that they add on to a certain game (in their
+[root file](http://se3docs.cgjennings.ca/dm-eons-plugin.html#for-game)).
+This lets users search for plug-ins related to a given game.
+
+Games also have their own settings that are shared between all components
+for that game. This lets you load a single collection of settings for
+all of your components. These will be "inherited" automatically and
+if you change them in a future update, all components for that game
+will get those changes automatically. (This is unlike the settings
+set directly on a component's "private settings", which are are unique
+to each individual component.)
+
+## Registering an expansion
+Registering expansions for a game lets you take advantage of the built-in
+system for adding expansion symbols to your designs: a few lines each
+near the end of `register-game-plugin.js`.
+
+### Expansion symbol templates
+Most of the code in the plug-in script is used to create an
+[expansion symbol template](http://se3docs.cgjennings.ca/dm-register-game.html#custom-expansionsymboltemplates).
+This is used to add custom "variants" of expansion symbols.
+(For example, a light version for some card designs and a dark verison for others.)
+In most cases, you can ignore this code and stick with the default template
+by passing `null` to `registerGame` as the `ExpansionSymbolTemplate`.