@slugbugblue/trax 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @slugbugblue/trax
 
+## 0.13.0 - 2022-11-25
+
+- Add move suggestions to `analyst.js` for CLI and bot use
+
+  - use `suggest(trax)` to get a suggestion for the current position
+  - added the `suggest` CLI command for quick access to a random suggestion
+
+- Use font glyphs for text bubbles in `tty.js` only if one of the following
+  environment variables are defined and non-empty:
+
+  - `NERDFONT`, `POWERLINE`, `P9K_TTY`, `P9K_SSH`
+
+- Begin work on documenting the javascript files using jsdoc, with the initial
+  focus on types so typescript-powered autocomplete can be more useful
+
+## 0.12.0 - 2022-10-28
+
+- `point.in()` now accepts any two opposing corners to define the bounding box
+- Fleshing out testing and debugging of `analyst.js`
+
 ## 0.11.0 - 2022-09-22
 
 - Breaking change: Refactor `play()` and `playMove()` into a single function

package/README.md

@@ -5,8 +5,8 @@ Trax game-playing engine and etc.
 ## Description
 
 Trax is a two-player boardless board game invented by David Smith. For more
-information about Trax, including its rules and history, see the official
-website at [traxgame.com][traxgame].
+information about Trax, including its [rules][traxrules] and
+[history][traxhistory], see the official website at [traxgame.com][traxgame].
 
 This goal of this javascript project is to allow Trax to be played
 programmatically. It can be used as an engine in a web browser, for example at
@@ -95,7 +95,9 @@ Examples:
 
 ## API Usage
 
-The main Trax engine is provided as `engine.js`, which can be used as follows:
+### Trax engine
+
+The main Trax engine is provided in `engine.js`, which can be used as follows:
 
 ```javascript
 import { Trax } from '@slugbugblue/trax'
@@ -115,12 +117,45 @@ let puzzle = new Trax('trax', '@0/ a0\\ @2/')
 puzzle.play('@2\\')
 ```
 
-For specifics, see the [engine.js documentation][engine-docs].
+For specifics, see the [engine.js documentation][docs-engine].
+
+### Analysis
+
+The analysis engine is provided in `analyst.js`, and it can be used as follows:
+
+```javascript
+import { Trax } from '@slugbugblue/trax'
+import { analyze } from '@slugbugblue/trax/analyst'
+
+let trax = new Trax('trax', '@0/ @1\\')
+
+let analysis = analyze(trax)
+
+console.log('Edge analysis:', analysis.edge)
+console.log('Threat analysis:', analysis.threats)
+console.log('Score analysis:', analysis.scores)
+```
+
+For additional information, refer to the [analyst.js
+documentation][docs-analyst].
+
+### Threats database
+
+The threats database is currently hand-coded in `threats.js`, so refer to that
+file if you want to try to update the analysis engine's understanding of
+threats.
+
+### Puzzles database
+
+The puzzles database is provided in `puzzles.js`, and so far just contains
+puzzles that I've been using to test the analysis engine, along with the list of
+publicly available puzzles at [the traxgame.com puzzles page][traxpuzzles].
 
 ## Roadmap
 
-- Game position analysis
-- Puzzles and Puzzlebot
+- Improve the threats database / analysis engine.
+- Add a puzzle interface to the CLI.
+- Add more puzzles.
 
 ## Support
 
@@ -174,12 +209,16 @@ David Smith and heirs, and are not to be used without permission.
 
 [ctrans]: mailto:chad@transtrum.net
 [dgb]: mailto:donald@traxgame.com
-[engine-docs]: docs/engine.md
+[docs-engine]: docs/engine.md
+[docs-analyst]: docs/analyst.md
 [env-path]: https://www.npmjs.com/package/env-paths
 [goldtoken]: https://goldtoken.com/
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
+[traxhistory]: http://www.traxgame.com/about_history.php
+[traxpuzzles]: http://www.traxgame.com/games_puzzles.php
+[traxrules]: http://www.traxgame.com/about_rules.php
 [xdg]:
   https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

package/docs/analyst.md

@@ -7,7 +7,7 @@ CLI and for bots.
 
 ```javascript
 import { Trax } from '@slugbugblue/trax'
-import { analyze } from '@slugbugblue/trax/analyst'
+import { analyze, suggest } from '@slugbugblue/trax/analyst'
 
 const trax = new Trax('trax', '@0/ @1/ B0\\')
 
@@ -16,6 +16,12 @@ const analysis = analyze(trax)
 console.log(JSON.stringify(analysis.edge, null, 2))
 console.log(JSON.stringify(analysis.threats, null, 2))
 console.log(JSON.stringify(analysis.scores, null, 2))
+
+const suggestion = suggest(trax)
+
+console.log(JSON.stringify(suggestion.options, null, 2))
+
+trax.play(suggestion.pick.move)
 ```
 
 ## API
@@ -107,7 +113,7 @@ simple count of the threats at each level can give a good first guess at the
 "score" of the current position. Each element of the array is an object with the
 following keys:
 
-- `pattern`: The threat pattern as it was fed into the threats database. This is
+- `threat`: The threat pattern as it was fed into the threats database. This is
   a simple edge string.
 - `match`: The portion of the actual edge string that matched the pattern, which
   may or may not be exactly the same as the pattern.
@@ -144,6 +150,42 @@ For any given location, determine the type of playable space. Returns one of:
 - `C`: This location is in a cave, and certain plays at this position result in
   illegal moves.
 
+### Suggestion class
+
+Accessible from `suggest(game)`, this class is returned with several useful
+pieces of information.
+
+#### properties
+
+##### `all`
+
+A list of all the moves analyzed, ordered by highest scoring move first.
+
+Each move is an object with the following properties:
+
+- `move`: the notation of the move
+- `score`: the score of the move
+- `analysis`: the analysis object of the position for this move
+
+##### `options`
+
+A smaller subset of the `all` list, with only the moves that are worth
+considering.
+
+##### `pick`
+
+A random selection of one of the `options`.
+
+##### `ms`
+
+The number of milliseconds spent performing the analyses required to create the
+suggestion.
+
+#### computed properties
+
+- `best`: quick access to the top-scoring move
+- `analyzed`: quick access to a count of the number of moves analyzed
+
 ## License
 
 Copyright 2019-2022 Chad Transtrum

package/docs/point.md

@@ -89,9 +89,10 @@ Returns the distance between two points. This will never be a negative number.
 Returns `true` if the given point or point-like object is at the same location
 as the existing point.
 
-##### `in(topLeft, bottomRight)`
+##### `in(a, b)`
 
 Pass in two points (or point-like objects) to define a rectangular bounding box.
+Each point represents opposite corners of the box.
 
 Returns `true` if the calling point is located inside the box or along any of
 its edges (ie, both bounding points are considered "inside").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -11,16 +11,15 @@
   "bugs": "https://gitlab.com/slugbugblue/trax/issues",
   "license": "Apache-2.0",
   "author": "Chad Transtrum <chad@transtrum.net>",
+  "types": "./src/types.d.ts",
   "exports": {
     ".": "./src/engine.js",
-    "./analyst": "./src/analyst.js",
-    "./analyst.js": "./src/analyst.js",
     "./point": "./src/point.js",
-    "./point.js": "./src/point.js",
+    "./analyst": "./src/analyst.js",
+    "./puzzles": "./src/puzzles.js",
     "./threats": "./src/threats.js",
-    "./threats.js": "./src/threats.js",
     "./tty": "./src/tty.js",
-    "./tty.js": "./src/tty.js"
+    "./version": "./src/version.js"
   },
   "repository": "gitlab:slugbugblue/trax",
   "bin": {
@@ -38,7 +37,7 @@
     "yaml": "^2.0.0-11"
   },
   "devDependencies": {
-    "ava": "^4.1.0",
+    "ava": "^5.1.0",
     "c8": "^7.11.0",
     "genversion": "^3.0.2",
     "prettier": "^2.6.1",

package/src/analyst.js

@@ -15,14 +15,33 @@
 
 // Analyst module: provides analysis functions for Trax games
 
-import { Point } from '@slugbugblue/trax/point.js'
+import { Point } from '@slugbugblue/trax/point'
 import { Trax } from '@slugbugblue/trax'
 
-import { threats } from '@slugbugblue/trax/threats.js'
+import { threats } from '@slugbugblue/trax/threats'
 
 // Helpers
+const id = () => {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
+  let code = ''
+  while (code.length < 6) {
+    code += chars[Math.floor(Math.random() * chars.length)]
+  }
+
+  return 'analysis-' + code
+}
+
+// A sort function for hashes with a numeric score property
+const byScoreDesc = (a, b) => b.score - a.score
+
+// A filter function factory to remove scores not within x points of the highest score
+const withinX = (highest, tolerance) => (s) =>
+  s.score === highest || highest - s.score <= tolerance
 
-// Make parseInt Array.map()-friendly
+// Return a random element of an array
+const randomDraw = (array) => array[Math.floor(Math.random() * array.length)]
+
+// Make parseInt a little shorter
 const int = (s) => Number.parseInt(s, 10)
 
 const leftTurn = { d: 'r', l: 'd', r: 'u', u: 'l' }
@@ -151,36 +170,63 @@ const label = (rawEdge) => {
   return final
 }
 
+const threatValues = (threatsArray) => {
+  return threatsArray.length
+  // Hm. Maybe we don't need this ...
+  // let count = 0
+  // for (const threat of threatsArray) count += threat.value
+  // return count
+}
+
 const attackScore = (from, level) => {
-  const count = from[level]?.length ?? 0
+  const count = threatValues(from[level] || [])
   if (level < 1) return count
   return count * 10 ** (threats.maxDepth - level + 1)
 }
 
-// Shortcut to get the number of active threats
-const threatCount = (from) =>
-  Object.entries(from).filter(([d, l]) => d > 0 && l.length > 0).length
+// Shortcut to get the number of attacks
+const attackCount = (from) => threatValues(from['1'] || [])
+
+// Shortcut to get the number of passive threats
+const threatCount = (from) => {
+  let count = 0
+  for (const [depth, array] of Object.entries(from)) {
+    count += int(depth) > 1 ? threatValues(array) : 0
+  }
+
+  return count
+}
+
+const passiveAttack = (from) =>
+  attackCount(from) > 1 || (attackCount(from) === 1 && threatCount(from) > 0)
+
+const underAttack = (from) => attackCount(from) + threatCount(from) > 0
 
 // Analysis class
 export const Analysis = class {
+  /** @type TraxVariant */
+  #rules = 'trax'
+  #id = 'analysis'
+  #moves = []
+  #notation = ''
   #edge = undefined
   #game = {}
-  #move = 0
-  #save = {}
   #scores = {}
   #threats = undefined
 
   constructor(game) {
     // Make a copy of the game
-    this.#game = game
-    this.#save = game.save()
-    this.#move = game.move
+    this.#rules = game.rules
+    this.#moves = game.moves
+    this.#id = id()
+    this.#notation = game.notation
+    this.#game = new Trax(this.#rules, this.#moves, this.#id)
   }
 
   get game() {
     // Return a fresh copy of the game as presented on init
-    if (this.#game.move !== this.#move) {
-      this.#game = new Trax().restore(this.#save)
+    if (this.#game.notation !== this.#notation) {
+      this.#game = new Trax(this.#rules, this.#moves, this.#id)
     }
 
     return this.#game
@@ -217,7 +263,7 @@ export const Analysis = class {
 
     for (const dir of Point.dirs) {
       let look = loc.dir(dir)
-      while (look.in(topLeft, bottomRight) && !game.tileAt(loc)) {
+      while (look.in(topLeft, bottomRight) && !game.tileAt(look)) {
         look = look.dir(dir)
       }
 
@@ -242,17 +288,14 @@ export const Analysis = class {
       const inactive = this.threats[Trax.other(game.color)]
       let advantage = Number.POSITIVE_INFINITY
 
-      // First examine the player who has the initiative
+      // First examine the active player
       for (const level of Object.keys(active).map((i) => int(i))) {
         if (level > 0 && level < advantage) advantage = level
         score += attackScore(active, level)
       }
 
       const passive = game.color !== color
-      const calc =
-        !passive ||
-        threatCount(this.threats[color]) > 1 ||
-        threatCount(this.threats[Trax.other(color)]) > 0
+      const calc = !passive || passiveAttack(inactive) || underAttack(active)
 
       // Calculate the effects of the passive player first
       for (const level of Object.keys(inactive).map((i) => int(i))) {
@@ -287,7 +330,7 @@ export const Analysis = class {
   // c = in a cave but has no restrictions (converted to n in edge)
   // C = a cave where some moves are not allowed (converted to c in edge)
   // n = normal space
-  // x = we cannot play here
+  // x = no tile can be played here
   spaceType(loc) {
     const { game } = this
 
@@ -300,13 +343,25 @@ export const Analysis = class {
     }
 
     // Check to see if we have an invalid move
+    let someValid = false
+    let someInvalid = false
     for (const tile of game.possibleTiles(loc)) {
       const drop = game.dropTile(tile, loc, 'tentative')
-      if (!drop.valid) {
-        return 'C'
+      if (drop.valid) {
+        someValid = true
+      } else {
+        someInvalid = true
       }
     }
 
+    if (!someValid) {
+      return 'x'
+    }
+
+    if (someInvalid) {
+      return 'C'
+    }
+
     return 'c'
   }
 
@@ -381,6 +436,7 @@ export const Analysis = class {
             threat: threat.pattern,
             match: match[0],
             at: match.index,
+            value: threat.value,
           })
         }
       }
@@ -390,6 +446,90 @@ export const Analysis = class {
 
     return matches
   }
+
+  // Make a reasonable inspect representation of the analysis
+  [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
+    const sub = (object) => inspect(object, options).replace(/\n/g, '\n  ')
+    const style = options.stylize
+    if (depth < 0) return style('<Analysis>', 'special')
+    if (options.depth !== null) options.depth -= 1
+    const tbd = style('tbd', 'undefined')
+    let custom = style('Analysis', 'special') + ' {\n'
+    custom += '  game: ' + style(this.#rules, 'special')
+    custom += '(' + style(this.#moves, 'string') + '),\n'
+    custom += '  edge: '
+    if (this.#edge) {
+      custom += '{\n    w: ' + style(this.#edge.w, 'string')
+      custom += ',\n    b: ' + style(this.#edge.b, 'string')
+      custom += ',\n    edge: ' + style('[rawEdge]', 'special')
+      custom += '\n  }'
+    } else {
+      custom += tbd
+    }
+
+    custom += ',\n  threats: '
+    custom += this.#threats ? sub(this.#threats) : tbd
+    custom += ',\n  scores: '
+    custom += 'w' in this.#scores ? sub(this.#scores) : tbd
+    custom += ',\n  score: '
+    const score = 'w' in this.#scores ? this.score : null
+    custom += score === null ? tbd : style(score, 'number')
+
+    return custom + '\n}'
+  }
 }
 
 export const analyze = (game) => new Analysis(game)
+
+export const Suggestion = class {
+  all = []
+  options = []
+  pick = {}
+  ms = 0
+
+  constructor(analyzed, ms) {
+    this.all = analyzed.sort(byScoreDesc)
+    const best = analyzed[0] || { move: '', score: 0 }
+    this.options = analyzed.filter(withinX(best.score, 5))
+    this.pick = randomDraw(this.options) || best
+    this.ms = ms
+  }
+
+  get best() {
+    return this.all[0]
+  }
+
+  get analyzed() {
+    return this.all.length
+  }
+
+  // Make a nice representation for the nodejs REPL
+  [Symbol.for('nodejs.util.inspect.custom')](_, options) {
+    const style = options.stylize
+    let out = style(this.pick.move, 'string')
+    out += ' ' + style(this.pick.score, 'number') + ' ['
+    out += this.options
+      .slice(0, 5)
+      .map((s) => style(s.move, 'string') + ' ' + style(s.score, 'number'))
+      .join(', ')
+    out += '] ' + this.analyzed + ' in ' + this.ms + 'ms'
+    return out
+  }
+}
+
+export const suggest = (game) => {
+  const start = Date.now()
+  const analyzed = {}
+  const { color, moves, rules } = game
+  for (const move of game.possibleMoves()) {
+    const trax = new Trax(rules, moves)
+    trax.play(move)
+    const unique = trax.normalized
+    if (!analyzed[unique]) {
+      const analysis = analyze(trax)
+      analyzed[unique] = { move, score: analysis.scores[color], analysis }
+    }
+  }
+
+  return new Suggestion(Object.values(analyzed), Date.now() - start)
+}