Puzzle15: v0.04 with settings, formatting changes, about screen

apps.json

@@ -5393,7 +5393,7 @@
   {
     "id": "puzzle15",
     "name": "15 puzzle",
-    "version": "0.03",
+    "version": "0.04",
     "description": "A 15 puzzle game with drag gesture interface",
     "readme":"README.md",
     "icon": "puzzle15.app.png",
@@ -5404,7 +5404,9 @@
     "allow_emulator": true,
     "storage": [
       {"name":"puzzle15.app.js","url":"puzzle15.app.js"},
+      {"name":"puzzle15.settings.js","url":"puzzle15.settings.js"},
       {"name":"puzzle15.img","url":"puzzle15.app-icon.js","evaluate":true}
-    ]
+    ],
+    "data": [{"name":"puzzle15.json"}]
   }
 ]

apps/puzzle15/ChangeLog

@@ -1,3 +1,4 @@
 0.01: Initial version, UI mechanics ready, no real game play so far
 0.02: Lots of enhancements, menu system not yet functional, but packaging should be now...
 0.03: Menu logic now generally functioning, splash screen added. The first really playable version!
+0.04: Settings dialog, about screen

apps/puzzle15/README.md

@@ -4,13 +4,16 @@ This is a Bangle.js 2 adoption of the famous 15 puzzle.
 
 ## The game
 
-A board of n x n fields is filled with n²-1 numbered stones.
+A board of _n_ by _n_ fields is filled with _n^2-1_ numbered stones. So, one field, the "gap", is left free.
+
 Bring them in the correct order so that the gap is finally at the bottom right of the playing field.
 The less moves you need, the better you are.
 
+If _n_ is 4, the number of stones is _16-1=15_. Hence the name of the game.
+
 ## How to play
 
-Select whether you want to play on a board with 3 x 3, 4 x 4, or 5 x 5 fields.
+If you start the game, it shows a splash screen and then generates a shuffled 4x4 board with a 15 puzzle.
 Move the stones with drag gestures on the screen.
 If you want to move the stone below the gap upward, drag from the bottom of the screen upward.
 The drag gestures can be performed anywhere on the screen, there is no need to start or end them on the stone to be moved.
@@ -18,10 +21,37 @@ The drag gestures can be performed anywhere on the screen, there is no need to s
 If you managed to order the stones correctly, a success message appears.
 You can continue with another game, go to the game's main menu, or quit the game entirely.
 
-There is a menu button right of the board. It opens the game's main menu.
+There is a grey menu button right of the board containing the well-known three-bar menu symbol ("Hamburger menu").
+It opens the game's main menu directly from within the game.
 
-## Implemenation notes
+## The main menu
 
-The game engine always generates 15 puzzles which can be solved.
+Puzzle15 has a main menu which can be reached from the in-game menu button or the end-of-game message window.
+It features the following options:
+
+* **Continue** - Continue the currently running game. _This option is only shown if the main menu is opened during an open game._
+* **Start 3x3**, **Start 4x4**, **Start 5x5** - Start a new game on a board with the respective dimension. Any currently open game is dropped.
+* **About** Show a small "About" info box.
+* **Exit** Exit Puzzle15 and return to the default watch face.
+
+## Game settings
+
+The game has some global settings which can be accessed on the usual way through the Bangle.js' app settings user interface.
+Currently it has the following options:
+
+* **Splash** - Define whether the game should open with a splash screen. **long** shows the splash screen for five seconds, **short** shows it for two seconds. **off** starts the app _without_ a splash screen, it directly comes up with whatever the "Start with" option says.
+* **Start with** - What should happen after the splash screen (or, if it is disabled, directly at app start): **3x3**, **4x4** and **5x5** start the game with a board of the respective dimension, **menu** shows the main menu which allows to select the board size.
+
+## Implementation notes
+
+The game engine always generates puzzles which can be solved.
+
+Solvability is detected by counting inversions,
+i.e. pairs of stones where the stone at the earlier field (row-wise, left to right, top to bottom) has a number _greater than_ the stone on the later field, with all pairs of stones compared.
+The algorithm is described at https://www.geeksforgeeks.org/check-instance-15-puzzle-solvable/ .
+
+## The splash screen
+
+The Splash screen shows a part of the illustration "The 14-15-puzzle in puzzleland" from Sam Loyd. Other than Puzzle15, it depicts a 15 puzzle with the stones "14" and "15" swapped. This puzzle is indeed *not* solvable.
 
 Have fun!

apps/puzzle15/puzzle15.settings.js

@@ -0,0 +1,50 @@
+// Settings menu for the Puzzle15 app
+
+(function(back) {
+  var FILE = "puzzle15.json";
+  // Load settings
+  var settings = Object.assign({
+    splashMode: "long",
+    startWith: "4x4"
+  }, require('Storage').readJSON(FILE, true) || {});
+
+  function writeSettings() {
+    require('Storage').writeJSON(FILE, settings);
+  }
+
+  // Helper method which uses int-based menu item for set of string values
+  function stringItems(startvalue, writer, values) {
+    return {
+      value: (startvalue === undefined ? 0 : values.indexOf(startvalue)),
+      format: v => values[v],
+      min: 0,
+      max: values.length - 1,
+      wrap: true,
+      step: 1,
+      onchange: v => {
+        writer(values[v]);
+        writeSettings();
+      }
+    };
+  }
+
+  // Helper method which breaks string set settings down to local settings object
+  function stringInSettings(name, values) {
+    return stringItems(settings[name], v => settings[name] = v, values);
+  }
+
+  var mainmenu = {
+    "": {
+      "title": "15 Puzzle"
+    },
+    "< Back": () => back(),
+    "Splash": stringInSettings("splashMode", ["long", "short", "off"]),
+    "Start with": stringInSettings("startWith", ["3x3", "4x4", "5x5", "menu"])
+  };
+
+  // Actually display the menu
+  E.showMenu(mainmenu);
+
+});
+
+// end of file