@slugbugblue/trax 0.1.0

package/.eslintrc.yaml

@@ -0,0 +1,68 @@
+root: true
+
+extends:
+  - eslint:recommended
+
+parserOptions:
+  sourceType: module
+
+env:
+  node: true
+  es2021: true
+
+globals:
+  crypto: readonly
+
+rules:
+  curly:
+    - error
+    - multi-line
+    - consistent
+  dot-location:
+    - error
+    - property
+  dot-notation: warn
+  eqeqeq:
+    - warn
+    - smart
+  guard-for-in: warn
+  indent:
+    - warn
+    - 2
+    - MemberExpression: 0
+      SwitchCase: 1
+  linebreak-style:
+    - error
+    - unix
+  max-len:
+    - warn
+    - code: 119
+      tabWidth: 2
+  no-alert: error
+  no-caller: error
+  no-div-regex: warn
+  no-else-return:
+    - error
+    - allowElseIf: false
+  no-eval: error
+  no-extra-parens: warn
+  no-invalid-this: error
+  no-new: error
+  no-unused-vars: 
+    - warn
+    - vars: all
+      args: all
+      caughtErrors: all
+  no-with: error
+  quotes:
+    - warn
+    - single
+    - avoidEscape: true
+      allowTemplateLiterals: true
+  semi:
+    - error
+    - never
+    - beforeStatementContinuationChars: always
+  wrap-iife:
+    - error
+    - inside

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2021 Chad Transtrum
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file 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/README.md

@@ -0,0 +1,119 @@
+# Trax
+
+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].
+
+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
+or in nodejs.
+
+## Installation
+
+```bash
+npm install @slugbugblue/trax
+```
+
+## Usage
+
+The main Trax engine is provided as `engine.js`,
+which can be used as follows:
+
+```javascript
+const Trax = require('@slugbugblue/trax')
+
+let trax = new Trax()
+
+trax.play('@0/')
+```
+
+Explore the file `engine.js` for more information
+until I get around to documenting the functionality.
+
+## Roadmap
+
+* Documentation
+* Test suite
+* Command line interface
+* Bot for solo games (?)
+* Puzzles
+
+## Support
+
+This project is built by [Chad Transtrum][ctrans]
+for [slugbugblue.com][sbb].
+Issues can be opened on the 
+[gitlab project page][repo].
+
+## Contributing
+
+Contributions are welcome.
+Ideally in the form of pull requests,
+but feel free to open an issue with a bug report
+or a suggestion as well.
+
+## Authors and acknowledgment
+
+Many thanks to the late David Smith
+for coming up with the idea of Trax
+and for his generosity in allowing me to
+add the game to [GoldToken.com][goldtoken].
+
+Thanks to his widow Colleen Foley-Smith
+for extending that generosity
+to allow me to include Trax on [slugbugblue.com][sbb].
+
+I would also like to extend a huge heartfelt appreciation
+to the magnanimous [Donald G. Bailey][dgb],
+who, through his excellent [book][traxbook],
+taught me the basics (and more!) of Trax
+and was always ready to share his insights
+on the mechanics of the game,
+various approaches to encoding its complexities,
+and for his undeserved kindness
+in indulging my many questions.
+
+## License
+
+Copyright 2021 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.
+
+## Trax rules copyright
+
+In the United States, game mechanics may not be copyrighted,
+however, the specific wording of game rules does fall under copyright law.
+
+The official rules for Trax are found at http://traxgame.com/about_rules.php.
+
+As Trax is a proprietary game,
+these rules are the intellectual property
+of David Smith and heirs,
+and are not to be used without permission.
+
+
+
+[ctrans]: mailto:chad@transtrum.net
+[dgb]: mailto:donald@traxgame.com
+[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/

package/engine.js

@@ -0,0 +1,496 @@
+/* Copyright 2021 Chad Transtrum
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file 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.
+ */
+
+// Trax internals. Woot.
+
+// 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
+
+const slash = { a: '\\', b: '+', c: '/', d: '/', e: '+', f: '\\' }
+
+const symmetry = {  // convert tile to different views
+  flip: { a: 'd', b: 'b', c: 'f', d: 'a', e: 'e', f: 'c' },
+  mirror: { a: 'c', b: 'b', c: 'a', d: 'f', e: 'e', f: 'd' },
+  swap: { a: 'f', b: 'e', c: 'd', d: 'c', e: 'b', f: 'a' },
+  counterclock: { a: 'c', b: 'e', c: 'f', d: 'a', e: 'b', f: 'd' },
+}
+
+const notation_regex = /^ *([@a-z]+) *(\d+) *([/\\+]) *$/i
+
+const variants = ['trax', 'traxloop', 'trax8']  // known variants
+
+// fun trax helper functions
+
+// unexpected note: str.includes(t) is true if t is '' but false if t is undefined
+const up_color = t => 'abc'.includes(t) ? 'b' : 'def'.includes(t) ? 'w' : false
+const down_color = t => 'bdf'.includes(t) ? 'b' : 'ace'.includes(t) ? 'w' : false
+const right_color = t => 'ade'.includes(t) ? 'b' : 'bcf'.includes(t) ? 'w' : false
+const left_color = t => 'cef'.includes(t) ? 'b' : 'abd'.includes(t) ? 'w' : false
+const squares_around = (x, y) => [{x:x-1,y},{x:x+1,y},{x,y:y-1},{x,y:y+1}]
+const encode_col = col => { // for notation purposes: 0 -> @, 6 -> F, 28 -> AB
+  let n = ''
+  while (col > 0) {
+    n = String.fromCharCode(65 + (col - 1) % 26) + n
+    col = Math.floor((col - 1) / 26)
+  }
+  return n || '@'
+}
+const decode_col = col => { // turn letters back into numbers
+  col = col.toUpperCase()
+  let n = 0
+  while (col.length) {
+    n = n + (col.charCodeAt(0) - 64) * Math.pow(26, col.length - 1)
+    col = col.slice(1)
+  }
+  return n
+}
+const add_blank = code => { // encode missing tiles as digits 0-9, for 1-10 missing
+  let num = code.charCodeAt(code.length - 1) // this is NaN if code is empty, which is ok
+  if (num > 47 && num < 57) return code.slice(0, code.length -1) + String.fromCharCode(num + 1)
+  return code += '0'
+}
+// ugh, this is a dirty little function to get the length of an encoded position row
+const code_row_len = row => row.replace(/[0-9]/g, n => '.'.repeat(Number(n)+1)).length
+
+// this is where the magic happens
+const Trax = class {
+  constructor (rules='trax', moves=[], id='trax') {
+    if (!variants.includes(rules)) rules = 'trax'
+    this.id = String(id)
+    this.rules = rules
+    this.move = 0
+    this.turn = 1
+    this.over = false
+    this.left = 1
+    this.right = 0
+    this.top = 1
+    this.bottom = 0
+    this.notation = ''
+    this.tiles = {}
+    this.path = []
+    this.count = 0
+    this.invalid = false
+    // moves might be a notation string
+    if (typeof moves === 'string') moves = moves.split(' ')
+    moves.forEach(move => {
+      if (typeof move === 'string') {
+        move = { move: this.move, notation: move }
+      }
+      this.play_move(move.move, move.notation)
+    })
+  }
+
+  save () { // in order to evaluate potential moves, we have to modify the state
+    return {
+      move: this.move,
+      turn: this.turn,
+      over: this.over,
+      left: this.left,
+      right: this.right,
+      top: this.top,
+      bottom: this.bottom,
+      notation: this.notation,
+      tiles: JSON.stringify(this.tiles),
+      path: JSON.stringify(this.path),
+      count: this.count,
+      invalid: this.invalid,
+    }
+  }
+
+  restore (saved) { // so we need to be able to restore it when we are done
+    this.move = saved.move
+    this.turn = saved.turn
+    this.over = saved.over
+    this.left = saved.left
+    this.right = saved.right
+    this.top = saved.top
+    this.bottom = saved.bottom
+    this.notation = saved.notation
+    this.tiles = JSON.parse(saved.tiles)
+    this.path = JSON.parse(saved.path)
+    this.count = saved.count
+    this.invalid = saved.invalid
+  }
+
+  get game_over () { // returns true if the game is over
+    return this.over
+  }
+
+  get winner () { // returns false if the game is still in progress
+    return this.over ? this.turn : false  // or 1 or 2 for a win, or 0 for a tie
+  }
+
+  tile_id (x, y) {
+    return this.id + '-' + String(x) + 'x' + String(y)
+  }
+
+  add_tile (type, x, y) { // note: no validity checking is done here
+    const id = this.tile_id(x, y)
+    const tile = { type, x, y, id, move: this.move, seq: this.count }
+    if (type === 'x') {
+      this.invalid = true // invalid tile is being played
+    } else {
+      this.tiles[id] = tile
+      this.count++
+      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)
+    }
+    return tile
+  }
+
+  tile_at (x, y) {
+    return (this.tiles[this.tile_id(x, y)] || {}).type
+  }
+
+  valid_tile (type, x, y) {
+    if (this.count === 0 && x === 0 && y === 0) return type === 'd' || type === 'e'
+    let up = down_color(this.tile_at(x, y - 1))
+    let down = up_color(this.tile_at(x, y + 1))
+    let left = right_color(this.tile_at(x - 1, y))
+    let right = left_color(this.tile_at(x + 1, y))
+    return (!up || up === up_color(type)) && (!down || down === down_color(type)) &&
+      (!left || left === left_color(type)) && (!right || right === right_color(type))
+  }
+
+  possible_tiles (x, y, s=false) { // s: slash (/ or \ or +)
+    let possibles = []
+    ;['a', 'b', 'c', 'd', 'e', 'f'].forEach(t => {
+      if ((!s || s === slash[t]) && this.valid_tile(t, x, y)) possibles.push(t)
+    })
+    return possibles
+  }
+
+  get height () {
+    return this.bottom - this.top + 1
+  }
+
+  get width () {
+    return this.right - this.left + 1
+  }
+
+  valid_location (x, y) {
+    if (this.over) return false
+    if (this.tile_at(x, y)) return false
+    if (this.count === 0 && x === 0 && y === 0) 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
+    }
+    return this.tile_at(x-1, y) || this.tile_at(x+1, y) || this.tile_at(x, y-1) || this.tile_at(x, y+1)
+  }
+
+  possible_locations () {
+    let possibles = []
+    for (let x = this.left - 1 ; x <= this.right + 1 ; x++) {
+      for (let y = this.top -1 ; y <= this.bottom + 1 ; y ++) {
+        if (this.valid_location(x, y)) possibles.push({x, y})
+      }
+    }
+    return possibles
+  }
+
+  possible_moves () { // returns a list of every currently possible move
+    // as notations, ie ['@1+', '@1/', '@1\\', ...]
+    let possibles = []
+    if (this.over) return possibles  // shortcut if the game is over
+    this.possible_locations().forEach(loc => {
+      this.possible_tiles(loc.x, loc.y).forEach(tile => {
+        let drop = this.drop_tile(tile, loc.x, loc.y, 'tentative')
+        if (drop.valid) possibles.push(drop.notation)
+      })
+    })
+    return possibles
+  }
+
+  forced_moves (x, y) { // we just played at x, y, so return all forced moves
+    let forced = []
+    let invalids = {}
+    let check = squares_around(x, y)
+    while (check.length) {
+      let pos = check.shift()
+      if (this.valid_location(pos.x, pos.y)) {
+        let possibles = this.possible_tiles(pos.x, pos.y)
+        if (possibles.length === 1) { // only 1 possible move
+          forced.push(this.add_tile(possibles[0], pos.x, pos.y))
+          check = check.concat(squares_around(pos.x, pos.y))
+        } else if (possibles.length === 0) { // no possible moves at all
+          let invalid = this.add_tile('x', pos.x, pos.y)
+          if (!invalids[invalid.id]) forced.push(invalid)
+          invalids[invalid.id] = true
+        }
+      }
+    }
+    return forced
+  }
+
+  notate (type, x, y) { // notation depends on the position of the board BEFORE the move
+    return encode_col(x - this.left + 1) + String(y - this.top + 1) + slash[type]
+  }
+
+  decode_notation (notation) { // return {type, x, y} from a notation
+    let r = { type: 'x', x: 0, y: 0 } // default to an invalid move
+    let match = notation.match(notation_regex)
+    if (match === null) return r
+    r.x = this.left - 1 + decode_col(match[1])
+    r.y = this.top - 1 + Number(match[2])
+    let possible = this.possible_tiles(r.x, r.y, match[3])
+    if (possible) r.type = possible[0]
+    return r
+  }
+
+  follow (color, x, y, from) {
+    let path = []
+    let id = this.tile_id(x, y)
+    let tile = this.tile_at(x, y)
+    while (tile && path[0] !== id) {
+      if (from !== 'top' && up_color(tile) === color) {
+        from = 'bottom'
+        y--
+      } else if (from !== 'bottom' && down_color(tile) === color) {
+        from = 'top'
+        y++
+      } else if (from !== 'left' && left_color(tile) === color) {
+        from = 'right'
+        x--
+      } else if (from !== 'right' && right_color(tile) === color) {
+        from = 'left'
+        x++
+      }
+      path.push(id)
+      id = this.tile_id(x, y)
+      tile = this.tile_at(x, y)
+    }
+    return { x, y, path }
+  }
+
+  find_ends (color, x, y) {
+    let ends = []
+    let tile = this.tile_at(x, y)
+    if (up_color(tile) === color) ends.push(this.follow(color, x, y, 'top'))
+    if (down_color(tile) === color) ends.push(this.follow(color, x, y, 'bottom'))
+    if (left_color(tile) === color) ends.push(this.follow(color, x, y, 'left'))
+    if (right_color(tile) === color) ends.push(this.follow(color, x, y, 'right'))
+    return ends
+  }
+
+  check_win (tiles) {
+    let winner = false
+    let colors = this.turn === 1 ? ['w', 'b'] : ['b', 'w'] // check win for current player first
+    colors.forEach(color => {
+      if (winner) return // skip the second player if the first has won
+      tiles.forEach(tile => {
+        if (winner) return // skip the remaining tiles once we find a win
+        let ends = this.find_ends(color, tile.x, tile.y)
+        if (ends.length !== 2) return // this should never happen, but if it does, don't die
+        if (ends[0].x === ends[1].x && ends[0].y === ends[1].y) {
+          winner = color // loop win
+          this.path = ends[0].path // both paths are essentially the same
+        } else if (this.rules !== 'traxloop') { // check for line win
+          if (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) {
+            winner = color // line win, paths need to be combined
+            this.path = ends[0].path.reverse().concat(ends[1].path.slice(1))
+          }
+        }
+      })
+    })
+    if (winner) {
+      this.over = true
+      this.turn = winner === 'w' ? 1 : 2
+    } else {
+      // 8x8 Trax can end in a tie once there are no valid moves left
+      if (this.rules === 'trax8' && this.possible_moves().length < 1) {
+        this.over = true
+        this.turn = 0 // tie
+      }
+    }
+  }
+
+  play (notation) { // fast and easy way to play a move
+    return this.drop_tile(notation)
+  }
+
+  play_move (move_num, notation) { // generic API call for drop_tile
+    if (move_num === this.move) return this.drop_tile(notation)
+    return { valid: false }
+  }
+
+  update_notation (notation) {
+    this.move++
+    let note = this.move +'. ' + notation
+    let line = this.notation.split('\n').pop()
+    if (line) {
+      note = (line.length + note.length > 79 ? '\n' : ' ') + note
+    }
+    this.notation += note
+  }
+
+  get moves () {
+    return this.notation.replace(/\n/g, ' ').split(' ').filter(n => !n.endsWith('.'))
+  }
+
+  drop_tile (type, x, y, tentative=false) { // pass in tentative to not save the move
+    let dropped = []
+    let notation = ''
+    let valid = false
+    if (['timeout', 'resign', 'draw', 'puzzled'].includes(type)) { // handle special events
+      this.over = true
+      if (type !== 'puzzled') {  // puzzled: puzzle was not completed; this player wins
+        this.turn = this.turn === 1 ? 2 : 1 // timeout, resign means the other player wins
+        if (type === 'draw') this.turn = 0 // draw means we both win
+      }
+      this.update_notation(type)
+      notation = type
+      valid = true
+    } else {
+      if (type.search(notation_regex) === 0) { // we were passed a notation
+        ({ type, x, y } = this.decode_notation(type))
+      }
+      if (this.valid_location(x, y) && this.valid_tile(type, x, y)) {
+        valid = true
+        let saved = this.save() // just in case we need to roll back
+        notation = this.notate(type, x, y) // determine notation BEFORE we play the move
+        this.update_notation(notation)
+        dropped.push(this.add_tile(type, x, y)) // play the tile
+        dropped = dropped.concat(this.forced_moves(x, y)) // play all forced moves
+        if (!tentative) this.check_win(dropped, tentative)
+        if (this.invalid || tentative) {
+          valid = false
+          this.restore(saved) // abort! abort!
+        } else if (!this.over) {
+          this.turn = this.turn === 1 ? 2 : 1
+        }
+      }
+    }
+    return { dropped, notation, valid }
+  }
+
+  rotate_move (move) { // symmetry helper, rotate a move around the board
+    let match = move.match(notation_regex)
+    if (match === null) return move
+    let x = this.width + 1 - Number(match[2])
+    let y = decode_col(match[1])
+    let s = { '/': '\\', '\\': '/', '+': '+'}[match[3]]
+    return encode_col(x) + String(y) + s
+  }
+
+  provisional_notation (provisional) { // test a provisional move against the current state
+    let prov = provisional.split(';') // return false if the provisional move does not match
+    if (prov.length !== 4) return 'delete-provisional' // <-- if the provisional move is bad
+    let notation = false // otherwise, return the notation required to make the move
+    let rows = prov[1].split(':')
+    let cols = rows.reduce((acc, cur) => Math.max(acc, code_row_len(cur)), 0)
+    rows = rows.length
+    if (this.width > rows && this.height > cols || this.width > cols && this.height > rows) {
+      return 'delete-provisional' // current board is bigger than the provisional move
+    }
+    if (prov[1] === this.normalized) {
+      let move = prov[2]
+      let saved = this.save() // save this position
+      for (let i = 0 ; i < 4 && !notation; i++) { // try all four orientations because symmetry
+        this.drop_tile(move)
+        if (prov[3] === this.normalized) notation = move // this move matched!
+        this.restore(saved) // put the board back how it was
+        move = this.rotate_move(move) // rotate to the next orientation
+      }
+    }
+    return notation
+  }
+
+  get icon () {
+    return this.position_code()
+  }
+
+  // symmetry helper
+  position_code (right_to_left, bottom_to_top, rotate, swap_colors) {
+    const start_x = right_to_left ? this.right : this.left
+    const start_y = bottom_to_top ? this.bottom : this.top
+    const inc_x = right_to_left ? -1 : 1
+    const inc_y = bottom_to_top ? -1 : 1
+    let code = []
+    let line = ''
+    let x = start_x
+    let y = start_y
+    do {
+      let tile = this.tile_at(x, y) // normal tile for normal orientation
+      if (tile) {
+        if (right_to_left) tile = symmetry.mirror[tile]
+        if (bottom_to_top) tile = symmetry.flip[tile]
+        if (rotate) tile = symmetry.counterclock[tile]
+        if (swap_colors) tile = symmetry.swap[tile]
+        if (this.path.includes(this.tile_id(x, y))) {
+          tile = String.fromCharCode(tile.charCodeAt(0) + this.turn * 6)
+        }
+        line += tile
+      } else {
+        line = add_blank(line)
+      }
+      if (rotate) { // increment y more often than x
+        y += inc_y
+        if (y < this.top || y > this.bottom) {
+          y = start_y
+          x += inc_x
+          // remove final number and add to code
+          code.push(line.replace(/[0-9]+$/, ''))
+          line = ''
+        }
+      } else { // this is the standard order
+        x += inc_x
+        if (x < this.left || x > this.right) {
+          x = start_x
+          y += inc_y
+          // remove final number and add to code
+          code.push(line.replace(/[0-9]+$/, ''))
+          line = ''
+        }
+      }
+    } while (x >= this.left && x <= this.right && y >= this.top && y <= this.bottom)
+    if (rotate) code.reverse()
+    return code.join(':')
+  }
+
+  normalize (swap_colors=false) {
+    // trax has the potential for symmetry, so this gives us the ability to
+    // examine horizontal, vertical, and rotational symmetry for a color
+    // --- pass in a truthy value to get a position for the opposite color
+    let norm = 'z'
+    let bools = [true, false]
+    bools.forEach(r_to_l => {
+      bools.forEach(b_to_t => {
+        bools.forEach(rot => {
+          let code = this.position_code(r_to_l, b_to_t, rot, swap_colors)
+          if (code < norm) norm = code
+        })
+      })
+    })
+    return norm
+  }
+
+  get normalized () {
+    // the default call does not check for color symmetry, because you rarely need that
+    return this.normalize()
+  }
+}
+
+Trax.column = (col) => encode_col(col)
+Trax.variants = variants
+
+module.exports = Trax

package/jsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2020"
+  },
+  "checkJs": true,
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@slugbugblue/trax",
+  "version": "0.1.0",
+  "description": "Trax game engine and friends",
+  "keywords": [
+    "trax",
+    "traxgame",
+    "engine"
+  ],
+  "homepage": "https://gitlab.com/slugbugblue/trax",
+  "bugs": "https://gitlab.com/slugbugblue/trax/issues",
+  "license": "Apache-2.0",
+  "author": "Chad Transtrum <chad@transtrum.net>",
+  "main": "engine.js",
+  "repository": "gitlab:slugbugblue/trax",
+  "scripts": {
+    "test": "tape tests.js"
+  },
+  "devDependencies": {
+    "eslint": "8.x",
+    "tape": "5.x",
+    "typescript": "^4.5.4",
+    "typescript-language-server": "^0.8.1"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/tty.js

@@ -0,0 +1,176 @@
+/* Copyright 2021 Chad Transtrum
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file 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.
+ */
+
+// Console functions for Trax
+
+/* eslint-disable no-console */
+
+const Trax = require('./engine')
+
+// fix Javascript's broken typeof
+const TypeOf = o => ({}).toString.call(o).slice(8,-1)
+
+const esc = '\x1b['  // start of console color escape code
+const off = esc + 'm'
+
+// display a message with optional color
+const out = (message, fgcolor, bgcolor) => {
+  let ansi = fgcolor || bgcolor ? esc : ''
+  if (fgcolor) ansi += '38;5;' + fgcolor
+  if (bgcolor) ansi += '48;5;' + bgcolor
+  if (ansi) ansi += 'm'
+  console.log(ansi + message + off)
+}
+
+
+// a little magic to display the game in progress
+const color_sets = {  // Colors for terminal sequence: <Esc>[38;5;<color_num>m
+  trax: { b: 238, B: 57, e: 19, t: 74, w: 255, W: 184 },
+  trax8: { b: 236, B: 21, e: 58, t: 137, w: 254, W: 117 },
+  traxloop: { b: 235, B: 20, e: 17, t: 61, w: 253, W: 222 },
+}
+
+// return the ANSI codes to display a 3x1.5 block tile, one line at a time
+const tile_tty = (set, tile, top) => { // top: true for first line, false for second
+  const ln = 'm\u2584'  // lower half block -- with the leading m to terminate a terminal color escape sequence
+  const up = 'm\u2588'  // full block
+  const lt = 'm\u2599'  // lower half and left half block
+  const rt = 'm\u259f'  // lower half and right half block
+  const fg = n => '38;5;' + String(set[n])  // foreground color_num
+  const bg = n => '48;5;' + String(set[n])  // background color_num
+  const sp = esc + bg('e') + 'm '  // lower space
+  // tiles are displayed on two lines; the top half of the first line is empty
+  // and the second half is composed of three characters, up color surrounded by tile color
+  const uptty = clr => esc + fg('t') + ';' + bg('e') + ln + esc + fg(clr) + ln + esc + fg('t') + ln + ' '
+  // the top half of the second line has both horizontal lines with a center transition
+  // while the bottom half is the tile background color surrounding the down color
+  const horiztty = clr => esc + fg('t') + ';' + bg(clr) + ln
+  const dntty = (clr, oppclr, char) => esc + fg(clr) + (char === up ? '' : ';' + bg(oppclr)) + char
+  // list of icon_char => tile line colors for easy reference in order up, right, down, left
+  const tiles = { a: 'bbww', b: 'bwbw', c: 'bwwb', d: 'wbbw', e: 'wbwb', f: 'wwbb' }
+  // quick access to tile color and its opposite in upper case
+  const colors = { b: 'b', w: 'w', B: 'w', W: 'b' }
+  if (!(tile in tiles)) { // winning paths are represented by adding 6 to the tile char code
+    tile = String.fromCharCode(tile.charCodeAt(0) - 6)
+    if (tile in tiles) {
+      colors.w = 'W'
+      colors.B = 'W'
+    } else {  // and another six for a black win
+      tile = String.fromCharCode(tile.charCodeAt(0) - 6)
+      colors.b = 'B'
+      colors.W = 'B'
+    }
+  }
+  if (tile in tiles) {
+    tile = tiles[tile]
+    if (top) return uptty(colors[tile[0]])
+    let center_char = tile[1] === tile[2] ? rt : tile[2] === tile[3] ? lt : up
+    let centertty = dntty(colors[tile[2]], colors[tile[2].toUpperCase()], center_char)
+    return horiztty(colors[tile[3]]) + centertty + horiztty(colors[tile[1]]) + sp
+  }
+  if (top) return '??? '
+  return '\'\'\' '
+}
+
+const print_icon = (icon, set_name) => {
+  let set = color_sets[set_name] || color_sets.trax
+  const on = esc + '38;5;' + String(set.t) + ';48;5;' + String(set.e) + 'm'
+  let o1 = '   '
+  let o2 = '1  '
+  let row = 1
+  let width = 1
+  let info = []
+  let line_width = 0
+  while (icon.length) {
+    let c = icon[0]
+    icon = icon.slice(1)
+    if (c === ':') {
+      info.push({o: o1, w: line_width})
+      info.push({o: o2, w: line_width})
+      row++
+      width = Math.max(width, line_width)
+      line_width = 0
+      o1 = '   '
+      o2 = String(row).padEnd(3)
+    } else if (c >= '0' && c <= '9') {
+      let empty = Number(c) + 1
+      o1 += ' '.repeat(empty * 4)
+      o2 += ' '.repeat(empty * 4)
+      line_width += empty
+    } else {
+      o1 += tile_tty(set, c, 'top')
+      o2 += tile_tty(set, c)
+      line_width++
+    }
+  }
+  if (o1.length) {
+    info.push({o: o1, w: line_width})
+    info.push({o: o2, w: line_width})
+    width = Math.max(width, line_width)
+  }
+  let columns = process.stdout.columns || 0
+  let rows = process.stdout.rows || 0
+  if (width * 4 < columns - 4 && info.length < rows - 2) {
+    let col_out = '   '
+    for (let col = 1; col <= width; col++) {
+      col_out += ' ' + Trax.column(col).padEnd(3)
+    }
+    console.info(on + col_out.padEnd((width + 1) * 4) + off)
+    info.forEach(line => console.info(on + line.o + ''.padEnd((width - line.w) * 4) + ' ' + off))
+    console.info(on + ''.padEnd((width + 1) * 4) + off)
+  } else {
+    console.warn('Console is too small to display this game')
+  }
+}
+
+// flexible way to get a Trax game object
+//    game = existing Trax instance, or a string indicating the variant name
+//    moves = optional list or string of moves to be made on the game
+// returns a Trax instance
+const trax_game = (game='trax', moves) => {
+  let trax
+  if (game instanceof Trax) {
+    trax = game
+    if (moves) {
+      if (TypeOf(moves) === 'String') moves = moves.split(' ')
+      moves.forEach(move => trax.drop_tile(move))
+    }
+  } else {
+    trax = new Trax(game, moves, 'cli')
+  }
+  return trax
+}
+
+const display_game = (game='trax', moves='') => {
+  let trax = trax_game(game, moves)
+  console.info(trax.notation)
+  print_icon(trax.icon, trax.rules)
+  let name = {0: 'nobody', 1: 'white', 2: 'black'}[trax.turn]
+  if (trax.over) {
+    if (trax.turn) {
+      console.info(name + ' wins')
+    } else {
+      console.info('game ended in a draw')
+    }
+  } else if (trax.turn) {
+    console.info(name +' to play')
+  }
+}
+
+module.exports = {
+  display: display_game,
+  game: trax_game,
+  out,
+}