@slugbugblue/trax 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,51 +1,70 @@
 # @slugbugblue/trax
 
+## 0.7.0 - 2022-03-28
+
+- Fixed a bug when including extra characters in a starting notation
+- Added regression tests to detect/prevent this bug in the future
+
+## 0.6.0 - 2022-02-13
+
+- Completed documentation for `engine.js` at [docs/engine.md](docs/engine.md)
+- `x` and `y` locations are now handled in a `Point` class
+- Renamed `tentativeIcon()` to `dropsIcon()`
+
+## 0.5.0 - 2022-01-29
+
+This code base is now using [`xo`](https://github.com/xojs/xo) for style and
+[`ava`](https://github.com/avajs/ava) for testing. Should be no functional
+changes, but a lot of code was updated, including the names of all functions and
+variables from snake_case to camelCase.
+
 ## 0.4.0 - 2022-01-17
 
-* Testing coverage of `engine.js` is now at 100%
-* Testing revealed a few bugs, which are now fixed
-* The name and signature for provisional move handling,
-  which was broken, has been changed. It is now called
-  `provisional_moves()` and takes three arguments:
+- Testing coverage of `engine.js` is now at 100%
+- Testing revealed a few bugs, which are now fixed
+- The name and signature for provisional move handling, which was broken, has
+  been changed. It is now called `provisional_moves()` and takes three
+  arguments:
 
-  * `from`: the normalized position code of the board before the move
-  * `to`: the normalized position code of the board after the move
-  * `via`: the move notation to go from `from` to `to`
+  - `from`: the normalized position code of the board before the move
+  - `to`: the normalized position code of the board after the move
+  - `via`: the move notation to go from `from` to `to`
 
 ### 0.3.1 - 2022-01-07
 
-* Make a faster implementation of `trax.possible_locations()`
-* Display updates for tentative moves
+- Make a faster implementation of `trax.possible_locations()`
+- Display updates for tentative moves
 
 ## 0.3.0 - 2021-12-29
 
 Display a tentative move on the screen
 
-* Add `trax.tentative_icon()` function
-* `tty.display()` now accepts a tentative move
+- Add `trax.tentative_icon()` function
+- `tty.display()` now accepts a tentative move
 
 ## 0.2.0 - 2021-12-28
 
 Breaking changes:
 
-* Converted from CommonJS to ESM
-* `trax.normalized` now prepends turn information to the string
+- Converted from CommonJS to ESM
+- `trax.normalized` now prepends turn information to the string
 
 More convenience:
 
-* `trax.color`: the color of the player whose turn it is
-* `Trax.color_of[num]`: go from player number to color
-* `Trax.player_num[color]`: or from color to player number
-* `Trax.other[color]`: easily switch from 'w' to 'b' and back
+- `trax.color`: the color of the player whose turn it is
+- `Trax.color_of[num]`: go from player number to color
+- `Trax.player_num[color]`: or from color to player number
+- `Trax.other[color]`: easily switch from 'w' to 'b' and back
 
 ## 0.1.0 - 2021-12-26
 
 Initial release:
 
-* engine.js
-  * create a new Trax game with `trax = new Trax()`
-  * play one move at a time with `trax.play('@0/')`
-  * ... etc
+- engine.js
+
+  - create a new Trax game with `trax = new Trax()`
+  - play one move at a time with `trax.play('@0/')`
+  - ... etc
 
-* tty.js
-  * display a game with `tty.display(trax)`
+- tty.js
+  - display a game with `tty.display(trax)`

package/README.md

@@ -4,19 +4,15 @@ 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].
+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.
+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.
 
-The Trax engine now enjoys automated testing
-with 100% code coverage. Any future changes
-to the engine should meet the same standard.
+The Trax engine now enjoys automated testing with 100% code coverage. Any future
+changes to the engine should meet the same standard.
 
 ## Installation
 
@@ -26,11 +22,10 @@ npm install @slugbugblue/trax
 
 ## Usage
 
-The main Trax engine is provided as `engine.js`,
-which can be used as follows:
+The main Trax engine is provided as `engine.js`, which can be used as follows:
 
 ```javascript
-import Trax from '@slugbugblue/trax'
+import { Trax } from '@slugbugblue/trax'
 
 // default constructor gives you a Trax game
 let trax = new Trax()
@@ -47,87 +42,67 @@ let puzzle = new Trax('trax', '@0/ a0\\ @2/')
 puzzle.play('@2\\')
 ```
 
-Explore the file `engine.js` for more information
-until I get around to documenting the functionality.
+For specifics, see the [engine.js documentation][engine-docs].
 
 ## Roadmap
 
-* Documentation
-* Command line interface
-* Bot for solo games (?)
-* Puzzles
+- 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].
+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 courtesy
-to allow me to include Trax on [slugbugblue.com][sbb]
-as well.
-
-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.
-I found him always ready to share his insights
-on the mechanics of the game,
-as well as various approaches to encoding its complexities.
-His undeserved kindness
-and infinite patience
-in indulging my many questions
-can never be repaid.
+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.
+
+## Acknowledgments
+
+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 courtesy to allow me
+to include Trax on [slugbugblue.com][sbb] as well.
+
+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. I found him always ready to share his insights
+on the mechanics of the game, as well as various approaches to encoding its
+complexities. His undeserved kindness and infinite patience in indulging my many
+questions can never be repaid.
 
 ## 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
+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
+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.
+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;
+In the United States, game mechanics are not eligible for coyright protection;
 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.
-
-
+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
+[engine-docs]: docs/engine.md
 [goldtoken]: https://goldtoken.com/
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/

package/docs/engine.md

@@ -10,7 +10,7 @@ the game state and what actions can be taken on the game.
 ## Example usage
 
 ```javascript
-import Trax from '@slugbugblue/trax'
+import { Trax } from '@slugbugblue/trax'
 
 let trax = new Trax()
 console.log(trax.possible_moves()) // "[ '@0/', '@0+' ]" -- initial moves
@@ -28,17 +28,35 @@ console.log(trax.winner) // "1" -- player 1 wins
 
 ## API
 
-### Trax object
+### Trax class
 
 The Trax object can be called as a constructor, but it also has the following
 class properties and methods:
 
-- `Trax.variants`: an array of the different rule sets the engine supports.
+- `Trax.variants`: a Set of the different rule sets the engine supports. Try
+  `Trax.variants.has(rule)` to see if your favorite rule set is supported. Or
+  `Trax.variants.forEach(s => { console.log(t) })` to list them all.
 
-- `Trax.column(col)`: a function to turn a numeric column number into the column
-  letter used in Trax notation.
+- `Trax.point(x, y)`: quick access to the [Point class][point-docs], for
+  two-dimensional locations used internally by the Trax engine and which are
+  required for some of the lower-level engine functions. Operates as a
+  constructor (without `new`) and returns a Point instance.
 
-### Trax class
+- `Trax.colorOf(playerNumber)`: Player 1 is white and Player 2 is black. So this
+  is a quick function to turn `1` into `'w'` and `2` into `'b'`. Quick and
+  dirty.
+
+- `Trax.playerNumber(color)`: Quick and dirty way to turn `'w'` into `1` and
+  `'b'` into `2`.
+
+- `Trax.other(color)`: Quick and dirty way to turn `'w'` into `'b'` and
+  vice-versa.
+
+- `Trax.encodeCol(columnNumber)`: a function to turn a numeric column number
+  into the column letter used in Trax notation. The first column is `A`. The
+  empty column just to the left is `@`.
+
+- `Trax.decodeCol(columnLetter)`: turns a column letter back into a number.
 
 #### constructor
 
@@ -46,7 +64,322 @@ class properties and methods:
 trax = new Trax(rules, moves, id)
 ```
 
-- `rules
+- `rules`: a string used to determine which trax variant will be played. If this
+  string is missing or is not found in `Trax.variants`, the default rule set of
+  `trax` will be used.
+
+- `moves`: an array of moves or a space-separated string of moves to use as the
+  starting position of the game board. If missing, the board will be empty. Note
+  that if an array is used, each item in the array should be a notation string.
+  If a string is used instead, it is permissible to include the move numbers of
+  each move as well. As an example, the following are equivalent:
+
+  - `['@0/', '@1+', 'B0\\']`
+  - `'1. @0/ 2. @1+ 3. B0\\'`
+  - `@0/ @1+ b0\\`
+
+- `id`: an optional string id that will be prepended to the key of each tile.
+  This is useful for setting the `id` value of HTML entities, but will probably
+  not be very useful for any other situations. You can likely safely ignore
+  this. Defaults to `'trax'`.
+
+Returns an instance of the `Trax` class, which contains the following properties
+and methods:
+
+### Trax instance
+
+#### properties
+
+- `id`: the string provided to the constructor
+- `rules`: which of the `Trax.variants` is being played
+- `move`: number, how many moves have been played
+- `turn`: number, the player to make the next move
+- `over`: boolean, `true` if the game is over
+- `left`: number, the left-most column in play
+- `right`: number, the right-most column in play
+- `top`: number, the top-most row in play
+- `bottom`: number, the bottom-most row in play
+  - note that each of these four numbers are using the internal coordinates of
+    the board rather than the Trax notation coordinates, since the latter
+    potentially change after every move
+- `notation`: string, the notation of the current state, wrapped at 80 columns
+- `tiles`: object, key/value pairs of data for each tile on the board
+  - key: a string composed of the game id and location of the tile
+  - value: an object containing the following key/value pairs:
+    - `type`: a string (`a` - `f`) representing the tile
+    - `loc`: an (x, y) Point object with the tile location
+    - `id`: the key of this object, provided here for easy cross-reference
+    - `move`: the move number this tile was placed on the board
+    - `seq`: the order in which this tile was played
+- `path`: array, each item is a key of `tiles` involved in the winning path
+- `invalid`: boolean, `true` only when a tile played into a cave results in an
+  illegal move
+
+Note that while there is no protection on these properties, you should treat
+them as read-only, since changing them directly will likely result in
+unpredictable and invalid operations by the engine.
+
+#### calculated properties
+
+- `count`: number, the total number of tiles currently in play
+- `color`: string, the color (`'w'` or `'b'`) of the player whose turn it is
+- `gameOver`: boolean, `true` if the game is over
+- `winner`: `false` if the game is still in progress, number of the winning
+  player otherwise (0 = tie)
+- `height`: the number of rows in play
+- `width`: the number of columns in play
+- `moves`: an array of move notations for the current game
+- `icon`: a string containing an encoded representation of the current board
+  position, useful for quickly drawing the game board without having to iterate
+  through the list of tiles (see [Encoding the icon](#encoding-the-icon) for
+  details on the structure of this code)
+- `normalized`: the normalized code for this position
+
+#### useful methods
+
+##### `save()`
+
+This method encodes and returns the current state of the game into an object
+that can later be restored. You should treat this object as opaque, to be used
+only with the `restore()` method. Save a position before attempting tentative or
+exploratory moves, so that you can restore the original position without having
+to re-play all of the moves to arrive at that position.
+
+`save()` and `restore()` are preferable to saving the current notation and
+calling `new Trax()` with that notation, since it avoids all of the calculations
+necessary to arrive at the same state.
+
+##### `restore(savedObj)`
+
+This method accepts the returned value of the `save()` method and restores the
+previously saved position.
+
+##### `possibleMoves()`
+
+Returns a list of all moves (using game notation) that can be made from the
+current position. Since it does not examine the result of forced tiles for each
+move, it does not detect illegal cave positions, so there is no guarantee that
+each move that can be played will be legal.
+
+##### `play(notation)`
+
+Attempts to play the given `notation`. Updates the game instance if the notation
+is valid for the current position.
+
+##### `playMove(currentMoveNumber, nextMoveNotation)`
+
+Used to play a move, but with an extra safeguard around the status of the game
+so that if this is called multiple times with the same values, it will ignore
+subsequent calls, which can be useful in the context of asynchronous
+communication and retries, such as when this engine is being used as the back
+end of a web interface. For example, if no moves have been made yet in a game,
+this can be called either as `playMove(0, '@0/')` or `playMove(0, '@0+')`.
+
+##### `provisionalMove(from, to, via)`
+
+Test to see if a provisionally entered move is a match for the current position,
+as determined by the normalized `from` position, playing the move notation
+`via`, which must result in the normalized `to` position. Note that normalized
+positions match symmetrically identical positions, so it's possible that `via`
+isn't the actual move notation required. Symmetrical rotations of the notation
+will be examined as well.
+
+Returns `'delete-provisional'` if the provisional move will never be valid in
+any future position. Returns `false` if the move doesn't match but may
+potentially match a future position. Returns the potentially rotated move
+notation if the provisional move was a match.
+
+##### `dropsIcon(drops)`
+
+Returns an `icon` but with the included `drops` encoded distinctly so that they
+can be distinguished from other tiles.
+
+#### internal methods you probably don't need to use directly
+
+Since these are not likely to be used directly, the documentation is a little
+less complete.
+
+##### `tileId(location)`
+
+Takes a `location` and returns a unique string id for the tile at that location.
+The `tiles` property object uses the `tileId()` as a key for the tiles.
+
+##### `addTile(type, location)`
+
+This function is used internally to place a tile of `type` on the board at
+`location`. It has no validity checks, since that is handled in other parts of
+the interface. It is not recommended to use this directly. It returns the tile
+object that it adds to the board.
+
+##### `tileAt(location)`
+
+Checks to see if a tile is at the specified `location`, and returns the tile
+type or `undefined`.
+
+##### `validTile(type, location)`
+
+Checks to see if a tile of `type` can be played at the given `location`. Returns
+`true` if so. Note that this result is not a guarantee, since it does not check
+forced tiles for illegal cave positions.
+
+##### `possibleTiles(location, slash)`
+
+Returns a list of the possibly valid tiles at a given `location`. If the
+optional `slash` parameter is included, it limits its search to tiles that also
+match that `slash`.
+
+##### `validLocation(location)`
+
+Returns true if a piece can be played at the given `location`. However, this
+does not check for illegal cave positions.
+
+##### `possibleLocations()`
+
+Returns a list of all locations where a tile may be played. Does not check for
+illegal cave positions.
+
+##### `forcedMoves(location)`
+
+After a tile is placed at `location`, play all the forced moves that result,
+adding them to the board as well. Returns the list of all tile objects (as
+returned from `addTile()`). It is during this function when illegal cave moves
+are detected. When that happens, the tile at that location will be given a type
+of `x`, and the `invalid` property of the Trax instance will be set to `true`,
+but the tiles will not be removed. It is up to the calling function to check for
+this condition and `restore` a previous position.
+
+##### `notate(type, location)`
+
+Return the game notation when playing a tile of `type` at the given `location`.
+This has to be done before the move is played, because if the move expands the
+board to the left or upward, the notation will be invalid.
+
+##### `decodeNotation(notation)`
+
+Returns an object with two keys: `type` and `location`.
+
+##### `follow(color, location, from)`
+
+Follows the line of one `color` starting at the tile at the given `location`, in
+the direction as if coming `from` a given edge. Returns an object giving the (x,
+y) `loc` of the final tile, as well as a `path` array holding the tile id's
+
+##### `findEnds(color, location)`
+
+Uses `follow()` to trace both ends of the given `color` from the given
+`location`. Returns an array of two items, each containing an object describing
+one of the ends of the line, as returned by `follow()`.
+
+##### `lineWin(locA, locB)`
+
+Given `locA` as the (x, y) location of one end of a line and `locB` as the other
+end, does the line constitute a line win? Returns `true` or `false`.
+
+##### `checkWin(tiles)`
+
+Used after a play is made to determine if any of the played `tiles` results in a
+win. Updates the instance's `over` and `turn` properties as needed. Returns
+nothing.
+
+##### `updateNotation(notation)`
+
+Handles updating the `notation` game instance property using the `notation` of
+the current move. Returns nothing.
+
+##### `dropTile(notation, _, tentative)`
+
+##### `dropTile(type, location, tentative)`
+
+Attempts to play a tile given either a `notation` or a `type` and `location`. If
+`tentative` is provided and is truthy, the move will not actually be made, but
+the return value will be the same as if it were made.
+
+Returns an object with the following key/value pairs:
+
+- `dropped`: a list of the tiles that were played by this move
+- `notation`: the resulting notation of the move
+- `valid`: `true` if the move is valid and results in a legal position
+
+##### `moveRotations(move)`
+
+Rotates a given `move` around the board to assist with symmetry calculations.
+Returns an array of possible symmetrical meanings of the given move.
+
+##### `positionCode(rightToLeft, bottomToTop, rotate, drops)`
+
+This is a helper function to provide a string representation to a position,
+applying optional symmetrical operations on it. By default, the position code
+returned will be provided using a top to bottom, right to left, unrotated
+approach. By setting `rightToLeft`, `topToBottom`, or `rotate` to `true`,
+transformations can be applied to the position code to return any of 8 different
+codes representing the 8 possible symmetries of any given position. If `drops`
+is provided, it should be the array of `dropped` tiles returned by `dropTile()`,
+and those tiles will be encoded differently. See
+[Encoding the icon](#encoding-the-icon) for details on the encoding.
+
+##### `normalize()`
+
+Returns a normalized position code icon. Every symmetrical position will return
+the same normalized code, so you can determine if two different positions are
+the same position with only changes in symmetry by calling this on both game
+instances and comparing the resulting icon string. While this code should be
+treated as if opaque, you can read about the way it is created from an
+[encoded position code](#encoding-the-icon) in the section on
+[normalizing the position code](#normalizing-a-position).
+
+## Trax tiles
+
+There isn't an inherent order to the way in which Trax tiles are presented.
+However, to allow for some sort of ease of encoding, the Trax module names each
+tile with a lower-case letter from `a` to `f` as shown in the following
+ASCII-art representations of each tile. The `##` characters are used to
+represent black.
+
+```
+  Trax tiles
+      a         b         c         d        e         f
+  ________  ________  ________  ________  _______  ________
+  |__##  |  |__##__|  |  ##__|  |_/ |  |  | | | |  |  | \_|
+  |_ \###|  |______|  |###/ _|  |__/###|  |#| |#|  |###\__|
+  |_\_|__|  |__##__|  |__|_/_|  |__##__|  |_|_|_|  |__##__|
+
+  (white wins / black wins)
+    g  m      h  n      i  o      j  p      k q      l  r
+```
+
+### Encoding the icon
+
+The `icon` computed property encodes the position of the board by replacing each
+tile on the board with its corresponding letter as described immediately above.
+In cases where the tile in question is part of a winning line or loop, the
+character for that tile is increased by 6 letters for a white win, or by 12
+letters for a black win. In addition, when requested, the icon can also include
+information about which tiles were placed in the last move, and those tiles are
+represented by their upper-case counterparts.
+
+In the event that a given move results in an illegal position, one of the tiles
+that make up the illegal position will be replaced by an `x` instead of one of
+the listed tiles. This signifies that no possible tile can meet the forced moves
+rules of that location. Only one of the tiles will be so marked, even though it
+requires several contributing tiles to create a situation where a move is
+illegal.
+
+Spaces are encoded into the icon using single-digit numbers. `0` means there is
+one space. `9` would indicate there are 10 spaces. Spaces at the left or in
+between tiles are encoded. Empty spaces to the right of all tiles are ignored.
+
+A colon is used to separate rows.
+
+### Normalizing a position
+
+A normalized position is one where a single position code is chosen such that
+symmetrical positions will be represented by a single position code.
+
+Different from a standard position code, a normalized position code includes the
+addition of a leading character indicating the state of the game. `W` means
+either that it is white's turn or that white has won the game. `B` indicates
+that black is to play or has already won. `T` means that the game has ended in a
+tie.
 
 ## License
 
@@ -62,3 +395,5 @@ 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.
+
+[point-docs]: point.md