@slugbugblue/trax 0.5.0 → 0.7.0

package/docs/point.md

@@ -0,0 +1,134 @@
+# point.js API documentation
+
+This module provides a class structure to work with `x`, `y` locations as a
+single point.
+
+Since I don't need it to be super fancy, there isn't a lot of extra
+functionality here.
+
+## Example usage
+
+```javascript
+import { Point } from '@slugbugblue/trax/point.js'
+
+const zero = new Point(0, 0)
+
+const up = zero.up
+console.log('up:', up.x, up.y) // up: 0 -1
+
+const rt = zero.right
+console.log('rt:', rt) // rt: Point(1,0)
+
+const up2 = zero.dir('up')
+console.log('up === up2 ?', up.eq(up2)) // up === up2 ? true
+
+// distances
+console.log(zero.distX(up), zero.distX(rt)) // 0 1
+console.log(up.distX(rt), up.distY(rt)) // 0 0
+console.log(zero.distance(up), zero.distance(rt)) // 1 1
+console.log(up.distance(rt)) // 1.4142135623730951
+```
+
+## API
+
+### Point class
+
+A Point instance is a representation of an immutable point in two dimensional
+space, represented by an `x` and a `y` component. Since this implementation was
+created for game boards, we assume that all points are integers, though that is
+not a requirement, and the math will work equally well on non-integers.
+
+#### constructor
+
+##### `new Point(fromPoint)`
+
+##### `new Point(x, y)`
+
+You can create a point from either a point-like object (ie, any object with both
+an `x` and a `y` key with numeric values), or from individual `x` and `y`
+numbers. Once a point is created, it cannot be changed; however, you can use its
+functions to return other points relative to it.
+
+##### `x` and `y` immutable properties
+
+You can return the individual `x` or `y` property of a point by accessing it
+directly. Attempts to change these properties will fail.
+
+##### `up`, `down`, `left`, `right` calculated properties
+
+Since points are immutable, to move a point, you need to create a new point.
+These calculated properties provide quick access to cardinal integer neighboring
+points.
+
+##### `around` calculated property
+
+Or, get an array of all four cardinal points around the existing point.
+
+##### `dir(direction)`
+
+Pass in a string named direction (ie, one of `up`, `down`, `left`, or `right`)
+to get a point one integer away from the existing point in the direction
+indicated. This does the exact same thing as the calculated properties with
+these names, but it can be done using a variable instead.
+
+##### `distX(from)`, `distY(from)`
+
+Returns the difference between the `x` or `y` properties of two points. This
+will always be represented by zero or a positive number.
+
+##### `distance(from)`
+
+Returns the distance between two points. This will never be a negative number.
+
+##### `eq(to)`
+
+Returns `true` if the given point or point-like object is at the same location
+as the existing point.
+
+#### Plays well with others
+
+The Point class also includes functionality to provide useful default results
+when used in other contexts.
+
+##### `toString()`
+
+Returns a string representation of the point in the format `Point(x,y)`. This
+allows simple logging calls with `console.log(point)`.
+
+##### `toJSON()`
+
+JSON cannot encode special classes, but this class can be stored as a bare
+object with `x` and `y` keys when converted to JSON. Note, though, that when
+parsing the resultant JSON string, all Point functionality is not restored by
+default. For example:
+
+```javascript
+const zero = new Point(0, 0)
+const json = JSON.stringify(zero)
+const jsonzero = JSON.parse(json)
+
+console.log(zero.eq(jsonzero)) // true
+jsonzero.eq(zero) // TypeError: jsonzero.eq is not a function
+const reconstituted = new Point(jsonzero)
+console.log(reconstituted.eq(zero)) // true
+```
+
+##### `util.inspect.custom()`
+
+When running in the node command line interpreter, a point will be
+pretty-printed using the magic of `util.inspect`.
+
+## License
+
+Copyright 2019-2022 Chad Transtrum
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+the files in this project except in compliance with the License. You may obtain
+a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/engine.js

@@ -15,12 +15,15 @@
 
 // Trax internals. Woot.
 
-// tile type names are determined by listing the color of line at each edge, clockwise
+// Tile type names are determined by listing the color of line at each edge, clockwise
 // and then sorted alphabetically and given a single letter name, so 'bbww' becomes 'a'
 // which gives us six different tile names: a-f
 
-// fun trax helper constants
+import { Point } from './point.js'
 
+// Fun trax helper constants
+
+const zero = new Point(0, 0)
 const notationRegex = /^ *([@a-z]+) *(\d+) *([/\\+]) *$/i
 
 const slash = { a: '\\', b: '+', c: '/', d: '/', e: '+', f: '\\' }
@@ -51,18 +54,14 @@ const rightColor = (t) =>
   'ade'.includes(t) ? 'b' : 'bcf'.includes(t) ? 'w' : false
 const leftColor = (t) =>
   'cef'.includes(t) ? 'b' : 'abd'.includes(t) ? 'w' : false
-const squaresAround = (x, y) => [
-  { x: x - 1, y },
-  { x: x + 1, y },
-  { x, y: y - 1 },
-  { x, y: y + 1 },
-]
 
 const addBlank = (code) => {
   // Encode missing tiles as digits 0-9, for 1-10 missing
   const lastNumber = code.codePointAt(code.length - 1) // This is NaN if code is empty, which is ok
-  if (lastNumber > 47 && lastNumber < 57)
+  if (lastNumber > 47 && lastNumber < 57) {
     return code.slice(0, -1) + String.fromCodePoint(lastNumber + 1)
+  }
+
   return code + '0'
 }
 
@@ -76,6 +75,7 @@ export const Trax = class {
   static variants = new Set(['trax', 'traxloop', 'trax8']) // Known variants
 
   // Static class methods
+  static point = (x, y) => new Point(x, y)
   static colorOf = (playerNumber) => ({ 1: 'w', 2: 'b' }[playerNumber])
   static playerNumber = (color) => ({ b: 2, w: 1 }[color])
   static other = (color) => ({ b: 'w', w: 'b' }[color])
@@ -121,13 +121,15 @@ export const Trax = class {
     this.invalid = false
     // Moves might be a notation string
     if (moves) {
-      if (typeof moves === 'string') moves = moves.split(' ')
+      if (typeof moves === 'string') moves = moves.split(/\s+/)
       for (let move of moves) {
         if (typeof move === 'string') {
           move = { move: this.move, notation: move }
         }
 
-        this.playMove(move.move, move.notation)
+        if (notationRegex.test(move.notation)) {
+          this.playMove(move.move, move.notation)
+        }
       }
     }
   }
@@ -162,6 +164,10 @@ export const Trax = class {
     this.tiles = JSON.parse(saved.tiles)
     this.path = JSON.parse(saved.path)
     this.invalid = saved.invalid
+    // Reconstitute the locations
+    for (const tile of Object.values(this.tiles)) {
+      tile.loc = new Point(tile.loc)
+    }
   }
 
   get count() {
@@ -184,39 +190,42 @@ export const Trax = class {
     return this.over ? this.turn : false // Or 1 or 2 for a win, or 0 for a tie
   }
 
-  tileId(x, y) {
-    return this.id + '-' + String(x) + 'x' + String(y)
+  tileId(loc) {
+    return this.id + '-' + String(loc.x) + 'x' + String(loc.y)
   }
 
-  addTile(type, x, y) {
+  addTile(type, loc) {
     // Note: no validity checking is done here
-    const id = this.tileId(x, y)
-    const tile = { type, x, y, id, move: this.move, seq: this.count }
+    const id = this.tileId(loc)
+    const tile = { type, loc, id, move: this.move, seq: this.count }
     if (type === 'x') {
       this.invalid = true // Invalid tile is being played
     } else {
       this.tiles[id] = tile
-      this.left = Math.min(this.left, x)
-      this.right = Math.max(this.right, x)
-      this.top = Math.min(this.top, y)
-      this.bottom = Math.max(this.bottom, y)
+      this.left = Math.min(this.left, loc.x)
+      this.right = Math.max(this.right, loc.x)
+      this.top = Math.min(this.top, loc.y)
+      this.bottom = Math.max(this.bottom, loc.y)
     }
 
     return tile
   }
 
-  tileAt(x, y) {
-    return (this.tiles[this.tileId(x, y)] || {}).type
+  tileAt(loc) {
+    return (this.tiles[this.tileId(loc)] || {}).type
   }
 
-  validTile(type, x, y) {
-    if (this.count === 0 && x === 0 && y === 0)
+  validTile(type, loc) {
+    if (this.count === 0 && loc.x === 0 && loc.y === 0) {
       return type === 'd' || type === 'e'
-    const up = downColor(this.tileAt(x, y - 1))
-    const down = upColor(this.tileAt(x, y + 1))
-    const left = rightColor(this.tileAt(x - 1, y))
-    const right = leftColor(this.tileAt(x + 1, y))
+    }
+
+    const up = downColor(this.tileAt(loc.up))
+    const down = upColor(this.tileAt(loc.down))
+    const left = rightColor(this.tileAt(loc.left))
+    const right = leftColor(this.tileAt(loc.right))
     return (
+      (up || down || left || right) &&
       (!up || up === upColor(type)) &&
       (!down || down === downColor(type)) &&
       (!left || left === leftColor(type)) &&
@@ -224,11 +233,11 @@ export const Trax = class {
     )
   }
 
-  possibleTiles(x, y, s = false) {
+  possibleTiles(loc, s = false) {
     // S: slash (/ or \ or +)
     const possibles = []
     for (const t of ['a', 'b', 'c', 'd', 'e', 'f']) {
-      if ((!s || s === slash[t]) && this.validTile(t, x, y)) possibles.push(t)
+      if ((!s || s === slash[t]) && this.validTile(t, loc)) possibles.push(t)
     }
 
     return possibles
@@ -242,41 +251,42 @@ export const Trax = class {
     return this.right - this.left + 1
   }
 
-  validLocation(x, y) {
+  validLocation(loc) {
     if (this.over) return false
-    if (this.tileAt(x, y)) return false
-    if (this.count === 0 && x === 0 && y === 0) return true
+    if (this.tileAt(loc)) return false
+    if (this.count === 0 && loc.eq(zero)) return true
     if (this.rules === 'trax8') {
-      if (this.width > 7 && (x < this.left || x > this.right)) return false
-      if (this.height > 7 && (y < this.top || y > this.bottom)) return false
+      if (this.width > 7 && (loc.x < this.left || loc.x > this.right)) {
+        return false
+      }
+
+      if (this.height > 7 && (loc.y < this.top || loc.y > this.bottom)) {
+        return false
+      }
     }
 
-    return Boolean(
-      this.tileAt(x - 1, y) ||
-        this.tileAt(x + 1, y) ||
-        this.tileAt(x, y - 1) ||
-        this.tileAt(x, y + 1),
-    )
+    for (const location of loc.around) {
+      if (this.tileAt(location)) return true
+    }
+
+    return false
   }
 
   possibleLocations() {
-    const locs = { '0x0': { x: 0, y: 0 } } // If no tiles are placed, we can play a starting tile
-    const maybe = (x, y) => {
+    const locs = { [this.tileId(zero)]: zero } // If no tiles are placed, we can play a starting tile
+    const maybe = (loc) => {
       // Add a loc if a tile isn't already there
-      const loc = x + 'x' + y
-      locs[loc] = locs[loc] || { x, y }
+      const id = this.tileId(loc)
+      locs[id] = locs[id] || loc
     }
 
     for (const tile of Object.values(this.tiles)) {
-      locs[tile.x + 'x' + tile.y] = 'tile' // Add an existing tile
-      maybe(tile.x - 1, tile.y) // And four maybe tiles around it
-      maybe(tile.x + 1, tile.y) // Which will either be replaced by real tiles
-      maybe(tile.x, tile.y - 1) // Or will be potentially valid locations
-      maybe(tile.x, tile.y + 1)
+      locs[tile.id] = 'tile' // Add an existing tile
+      tile.loc.around.map((loc) => maybe(loc))
     }
 
     // Get rid of all the real tiles and return all the maybes
-    return Object.values(locs).filter((l) => l !== 'tile')
+    return Object.values(locs).filter((loc) => loc !== 'tile')
   }
 
   possibleMoves() {
@@ -285,8 +295,8 @@ export const Trax = class {
     const possibles = []
     if (this.over) return possibles // Shortcut if the game is over
     for (const loc of this.possibleLocations()) {
-      for (const tile of this.possibleTiles(loc.x, loc.y)) {
-        const drop = this.dropTile(tile, loc.x, loc.y, 'tentative')
+      for (const tile of this.possibleTiles(loc)) {
+        const drop = this.dropTile(tile, loc, 'tentative')
         if (drop.valid) possibles.push(drop.notation)
       }
     }
@@ -294,22 +304,22 @@ export const Trax = class {
     return possibles
   }
 
-  forcedMoves(x, y) {
-    // We just played at x, y, so return all forced moves
+  forcedMoves(loc) {
+    // We just played at loc, so return all forced moves
     const forced = []
     const invalids = {}
-    let check = squaresAround(x, y)
+    let check = loc.around
     while (check.length > 0) {
       const pos = check.shift()
-      if (this.validLocation(pos.x, pos.y)) {
-        const possibles = this.possibleTiles(pos.x, pos.y)
+      if (this.validLocation(pos)) {
+        const possibles = this.possibleTiles(pos)
         if (possibles.length === 1) {
           // Only 1 possible move
-          forced.push(this.addTile(possibles[0], pos.x, pos.y))
-          check = [...check, ...squaresAround(pos.x, pos.y)]
+          forced.push(this.addTile(possibles[0], pos))
+          check = [...check, ...pos.around]
         } else if (possibles.length === 0) {
           // No possible moves at all
-          const invalid = this.addTile('x', pos.x, pos.y)
+          const invalid = this.addTile('x', pos)
           if (!invalids[invalid.id]) forced.push(invalid)
           invalids[invalid.id] = true
         }
@@ -319,62 +329,72 @@ export const Trax = class {
     return forced
   }
 
-  notate(type, x, y) {
+  notate(type, loc) {
     // Notation depends on the position of the board BEFORE the move
-    return (
-      Trax.encodeCol(x - this.left + 1) + String(y - this.top + 1) + slash[type]
-    )
+    let notation = Trax.encodeCol(loc.x - this.left + 1)
+    notation += String(loc.y - this.top + 1)
+    notation += slash[type]
+    return notation
   }
 
   decodeNotation(notation) {
-    // Return {type, x, y} from a notation
-    const r = { type: 'x', x: 0, y: 0 } // Default to an invalid move
+    // Return {type, loc} from a notation
+    const bad = { type: 'x', loc: zero }
     const match = notation.match(notationRegex)
-    if (match === null) return r
-    r.x = this.left - 1 + Trax.decodeCol(match[1])
-    r.y = this.top - 1 + Number(match[2])
-    const possible = this.possibleTiles(r.x, r.y, match[3])
-    if (possible) r.type = possible[0]
-    return r
+    if (match === null) return bad
+    const loc = new Point(
+      this.left - 1 + Trax.decodeCol(match[1]),
+      this.top - 1 + Number(match[2]),
+    )
+    const possible = this.possibleTiles(loc, match[3])
+    if (possible.length > 0) return { type: possible[0], loc }
+    return bad
   }
 
-  follow(color, x, y, from) {
+  follow(color, loc, from) {
     const path = []
-    let id = this.tileId(x, y)
-    let tile = this.tileAt(x, y)
+    let id = this.tileId(loc)
+    let tile = this.tileAt(loc)
     while (tile && path[0] !== id) {
       if (from !== 'top' && upColor(tile) === color) {
         from = 'bottom'
-        y--
+        loc = loc.up
       } else if (from !== 'bottom' && downColor(tile) === color) {
         from = 'top'
-        y++
+        loc = loc.down
       } else if (from !== 'left' && leftColor(tile) === color) {
         from = 'right'
-        x--
+        loc = loc.left
       } else if (from !== 'right' && rightColor(tile) === color) {
         from = 'left'
-        x++
+        loc = loc.right
       }
 
       path.push(id)
-      id = this.tileId(x, y)
-      tile = this.tileAt(x, y)
+      id = this.tileId(loc)
+      tile = this.tileAt(loc)
     }
 
-    return { x, y, path }
+    return { loc, path }
   }
 
-  findEnds(color, x, y) {
+  findEnds(color, loc) {
     const ends = []
-    const tile = this.tileAt(x, y)
-    if (upColor(tile) === color) ends.push(this.follow(color, x, y, 'top'))
-    if (downColor(tile) === color) ends.push(this.follow(color, x, y, 'bottom'))
-    if (leftColor(tile) === color) ends.push(this.follow(color, x, y, 'left'))
-    if (rightColor(tile) === color) ends.push(this.follow(color, x, y, 'right'))
+    const tile = this.tileAt(loc)
+    if (upColor(tile) === color) ends.push(this.follow(color, loc, 'top'))
+    if (downColor(tile) === color) ends.push(this.follow(color, loc, 'bottom'))
+    if (leftColor(tile) === color) ends.push(this.follow(color, loc, 'left'))
+    if (rightColor(tile) === color) ends.push(this.follow(color, loc, 'right'))
     return ends
   }
 
+  lineWin(locA, locB) {
+    if (this.rules === 'traxloop') return false
+    if (this.width > 7 && locA.distX(locB) > this.width) return true
+    if (this.height > 7 && locA.distY(locB) > this.height) return true
+    return false
+  }
+
   checkWin(tiles) {
     let winner = false
     const colors = [this.color, Trax.other(this.color)] // Check win for current player first
@@ -382,15 +402,11 @@ export const Trax = class {
       if (winner) continue // Skip the second player if the first has won
       for (const tile of tiles) {
         if (winner) continue // Skip the remaining tiles once we find a win
-        const ends = this.findEnds(color, tile.x, tile.y)
-        if (ends[0].x === ends[1].x && ends[0].y === ends[1].y) {
+        const ends = this.findEnds(color, tile.loc)
+        if (ends[0].loc.eq(ends[1].loc)) {
           winner = color // Loop win
           this.path = ends[0].path // Both paths are essentially the same
-        } else if (
-          this.rules !== 'traxloop' && // Check for line win
-          ((this.width > 7 && Math.abs(ends[0].x - ends[1].x) > this.width) ||
-            (this.height > 7 && Math.abs(ends[0].y - ends[1].y) > this.height))
-        ) {
+        } else if (this.lineWin(ends[0].loc, ends[1].loc)) {
           winner = color // Line win, paths need to be combined
           this.path = [...ends[0].path.reverse(), ...ends[1].path.slice(1)]
         }
@@ -417,9 +433,9 @@ export const Trax = class {
     return this.dropTile(notation)
   }
 
-  playMove(moveNumber, notation) {
+  playMove(currentMoveNumber, nextMoveNotation) {
     // Generic API call for dropTile
-    if (moveNumber === this.move) return this.dropTile(notation)
+    if (currentMoveNumber === this.move) return this.dropTile(nextMoveNotation)
     return { valid: false }
   }
 
@@ -441,7 +457,7 @@ export const Trax = class {
       .filter((n) => !n.endsWith('.'))
   }
 
-  dropTile(type, x, y, tentative = false) {
+  dropTile(type, loc, tentative = false) {
     // Pass in tentative to not save the move
     let dropped = []
     let notation = ''
@@ -461,16 +477,18 @@ export const Trax = class {
     } else {
       if (type.search(notationRegex) === 0) {
         // We were passed a notation
-        ;({ type, x, y } = this.decodeNotation(type))
+        const decoded = this.decodeNotation(type)
+        type = decoded.type
+        loc = decoded.loc
       }
 
-      if (this.validLocation(x, y) && this.validTile(type, x, y)) {
+      if (this.validLocation(loc) && this.validTile(type, loc)) {
         valid = true
         const saved = this.save() // Just in case we need to roll back
-        notation = this.notate(type, x, y) // Determine notation BEFORE we play the move
+        notation = this.notate(type, loc) // Determine notation BEFORE we play the move
         this.updateNotation(notation)
-        dropped.push(this.addTile(type, x, y)) // Play the tile
-        dropped = [...dropped, ...this.forcedMoves(x, y)] // Play all forced moves
+        dropped.push(this.addTile(type, loc)) // Play the tile
+        dropped = [...dropped, ...this.forcedMoves(loc)] // Play all forced moves
         if (this.invalid || tentative) {
           if (this.invalid) valid = false
           this.restore(saved) // Abort! abort!
@@ -490,6 +508,8 @@ export const Trax = class {
     if (match === null) return []
     const x = Trax.decodeCol(match[1])
     const y = Number(match[2])
+    const X = this.height - x + 1
+    const Y = this.width - y + 1
     const s = match[3]
     const slashes = s === '+' ? [s] : ['/', '\\']
     const moves = new Set()
@@ -497,16 +517,8 @@ export const Trax = class {
     for (const slash of slashes) {
       moves.add(Trax.encodeCol(x) + String(y) + slash)
       moves.add(Trax.encodeCol(y) + String(x) + slash)
-      moves.add(
-        Trax.encodeCol(this.height - x + 1) +
-          String(this.width - y + 1) +
-          slash,
-      )
-      moves.add(
-        Trax.encodeCol(this.width - y + 1) +
-          String(this.height - x + 1) +
-          slash,
-      )
+      moves.add(Trax.encodeCol(X) + String(Y) + slash)
+      moves.add(Trax.encodeCol(Y) + String(X) + slash)
     }
 
     return [...moves]
@@ -547,7 +559,7 @@ export const Trax = class {
     return this.positionCode()
   }
 
-  tentativeIcon(drops) {
+  dropsIcon(drops) {
     return this.positionCode(undefined, undefined, undefined, drops)
   }
 
@@ -562,19 +574,22 @@ export const Trax = class {
     let x = startX
     let y = startY
     do {
-      let tile = this.tileAt(x, y) // Normal tile for normal orientation
+      const loc = new Point(x, y)
+      let tile = this.tileAt(loc) // Normal tile for normal orientation
       if (tile) {
         tile = applySymmetry(tile, rightToLeft, bottomToTop, rotate)
-        if (this.path.includes(this.tileId(x, y))) {
+        if (this.path.includes(this.tileId(loc))) {
           tile = String.fromCodePoint(tile.codePointAt(0) + this.turn * 6)
         }
 
         if (
           drops &&
           drops.dropped &&
-          drops.dropped.some((t) => t.x === x && t.y === y)
-        )
+          drops.dropped.some((t) => loc.eq(t.loc))
+        ) {
           tile = tile.toUpperCase()
+        }
+
         line += tile
       } else {
         line = addBlank(line)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -18,11 +18,16 @@
     "preversion": "npm test",
     "postversion": "git push && git push --tags"
   },
+  "dependencies": {
+    "env-paths": "^3.0.0",
+    "make-dir": "^3.1.0",
+    "yaml": "^2.0.0-11"
+  },
   "devDependencies": {
-    "ava": "^4.0.1",
+    "ava": "^4.1.0",
     "c8": "^7.11.0",
-    "prettier": "^2.5.1",
-    "xo": "^0.47.0"
+    "prettier": "^2.6.1",
+    "xo": "^0.48.0"
   },
   "type": "module",
   "engines": {
@@ -37,6 +42,12 @@
     "useTabs": false
   },
   "xo": {
-    "prettier": true
+    "prettier": true,
+    "rules": {
+      "curly": [
+        "error",
+        "multi-line"
+      ]
+    }
   }
 }