@slugbugblue/trax-cli

Trax Command Line interface

This project provides a command-line for working with Trax games and puzzles.

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.

The goal of this javascript project is to allow Trax to be played from the command line.

Installation

Installation can be done in one of two ways, each for a slightly different purpose.

If you have nodejs installed on your system, you can use the trax CLI by installing it globally via npm:

npm install -g @slugbugblue/trax-cli

If you don't have node installed and want to use the CLI as a docker container:

git clone https://gitlab.com/slugbugblue/trax-cli.git ~/trax
docker build -t trax ~/trax

CLI Usage

The command-line interface is provided as trax, available in your path if installed globally, or in the node_modules/.bin directory and runnable using npx trax if installed locally.

If you installed by creating a Docker image, use the following command to launch the CLI:

• docker run --name trax -itv $HOME/trax:/mnt/data --rm trax

Since that's a bit much to type, it's recommended to create an alias in one of your startup scripts:

• alias trax="docker run --name trax -itv $HOME/trax:/mnt/data --rm trax"

Then you can launch the docker container simply by typing in trax, the same as if it were installed globally.

The CLI can be used interactively by running the command with no parameters or by passing the --interactive or -i flag. When run interactively, you can avoid worries about the need to escape certain characters from the shell, and it can be easier to run multiple commands back to back.

Help is available for the CLI through the use of the help command. Type trax help (or npx trax help with a local installation, or simply help if run interactively) to see a list of the available commands, and trax help play to see information about the play command. Aliases and abbreviations are provided to minimize typing and to try to avoid the requirement of memorizing the commands. For example, the list command has an alias of ls, help can be shortened to ?, and the select command can be activated using #.

When you first launch the CLI, you can create a new game using the new command, and then enter moves for that game using play. Since play is likely to be the most common command used, you can simply omit the command name. For example, at the interactive prompt, entering @0/ is the same as if you had entered play 1. @0/.

Multiple games can be started at once, and the CLI will remember the currently active game and apply future actions to that game. Each game will retain its #id number until it is deleted, and you can use that number to switch between games. For example, to make game #1 active, enter select 1 or select #1 or simply #1 at the interactive prompt.

For ease of working at the command line, the symbols used as the last character of the Trax notation can optionally be replaced with letters. Use s for slash symbol (/), b for backslash (\), and p for plus (+). While there is no need to escape at the interactive prompt, these substitutions will be avilable there as well.

Examples

# Start a new Trax game with Chad playing as white
> trax new Chad vs

# Start a new Loop Trax game with Chad playing as black
> trax new loop vs Chad

# Start a new 8x8 Trax game with Chad as white and Another Player as black
> trax new 8x8 Chad vs Another Player

# Switch back to the first game. Note the quoting required at the command line.
# This would not be necessary when running at the interactive prompt.
> trax '#1'

# Play two moves, using full notation
> trax play 1. @0/ 2. A0/

# Two more moves, using short notation and symbol substitution
# B2/ => b2s and A0\ => a0b
> trax b2s a0b

# See the status of all games
> trax ls

Environment variables

The CLI uses standard Windows and Linux XDG file locations as provided by the env-paths library, with current uses being user-specific config (XDG_CONFIG_HOME) and data (XDG_DATA_HOME) folders.

In addition, the CLI recognizes several environment variables to determine the glyphs to use in the user interface. Setting either NERDFONT or NERDFONTS to any non-empty string will use characters from Nerdfonts. Otherwise, any of POWERLINE, P9K_TTY, or P9K_SSH will use characters from Powerline fonts.

Support

This project is built by Chad Transtrum as part of the work on slugbugblue.com. Issues can be opened on the gitlab project page.

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.

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.

Thanks to his widow Colleen Foley-Smith for extending that courtesy to allow me to include Trax on slugbugblue.com as well.

I would also like to express my huge heartfelt appreciation to the magnanimous Donald G. Bailey, who, through his excellent book Trax Strategy for Beginners, 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.

Thanks to Martin M. S. Pedersen for contributing ideas, code, and puzzles. He's been curating Trax puzzles and coding solutions for Trax for over two decades, and has a lot of expertise in this area.

License

Copyright 2019-2023 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 are not eligible for copyright 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.