Car Wars Simulator

Car Wars Simulator
- About
  - Description
  - Example
- Help
  - User Interface
    - Build Image
    - Comparison Build
    - Workbench List
    - Menus
      - File Menu
      - Edit Menu
      - View Menu
      - Sim Menu
      - Help Menu
    - Future Ideas
- Download
  - Windows App
  - Command-Line Interface (CLI)
    - Setup
- Resources

About

╔═══════════════════════════════════════════════════════════════════════════╗
║ ┌─────────────────────────────┐                                           ║
║ │                             │                                           ║
║ │  hEBigGesTgUnSTheRiGHTofwa  │  //////////////////////////////////////// ║
║ │  BiGGEStGuNSTHeRiGhtofwaYG  │  //                                    // ║
║ │  AYgOEStoTHEbIgGeSTguNstHe  │  // Tiwahu Car Wars Simulator          // ║
║ │  FwayG ________   ___ UNst  │  // Copyright (c) 2022-2023 Tim Huber. // ║
║ │  eStG / ___/ _ | / _ \ eSt  │  // All Rights Reserved.               // ║
║ │  Tof / /__/ __ |/ , _/ GUN  │  //                                    // ║
║ │  tgU \___/_/ |_/_/|_| stOT  │  // Tiwahu.CarWars.Sim.Console         // ║
║ │   _      _____   ___  ____  │  // 1.0.5-beta+6869a8d520              // ║
║ │  | | /| / / _ | / _ \/ __/  │  //                                    // ║
║ │  | |/ |/ / __ |/ , _/\ \    │  //////////////////////////////////////// ║
║ │  |__/|__/_/ |_/_/|_/___/ I  │                                           ║
║ │                         gG  │                                           ║
║ │  GgesTGunstHerIGHtOFWAYgOE  │          an unofficial "game aid"         ║
║ │  IghTOfWAYgOeStOTHeBIgGeSt  │             (REDACTED version)            ║
║ │  NStHErI           StOtHEb  │                                           ║
║ │  ghtoFW  Simulator  oTHEbi  │                     for                   ║
║ │  GUnsTHE           OeStoTh  │                                           ║
║ │  tHEriGHtoFwaygOeStOthEbiG  │             ┌─────────────────┐           ║
║ │  GoestOthebiGGEstGUnsthERI  │             │ C A R   W A R S │           ║
║ │  sTGunStHErightOFWaygOEsTO  │             │ (sixth edition) │           ║
║ │                             │             └─────────────────┘           ║
║ └─────────────────────────────┘                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

  ┌──────────────────────────────────────────────────────────────────┐
  │ Car Wars is a trademark of Steve Jackson Games, and its rules    │
  │ and art are copyrighted by Steve Jackson Games. All rights are   │
  │ reserved by Steve Jackson Games. This game aid is the original   │
  │ creation of Timothy Huber and is released for free distribution, │
  │ and not for resale, under the permissions granted in the [Steve  │
  │ Jackson Games Online Policy][*].                                 │
  │                                                                  │
  │ [*]: http://www.sjgames.com/general/online_policy.html           │
  └──────────────────────────────────────────────────────────────────┘

╔═══════════════════════════════════╗
║ Go buy more Car Wars products at: ║
║ https://carwars.sjgames.com/      ║
╚═══════════════════════════════════╝

  ╔═══════════════════════════════════════════════════════╗
  ║ Specify '--help' for available commands and options.  ║
  ║ Specify '--about' for more ASCII art and information. ║
  ╚═══════════════════════════════════════════════════════╝

Examples:

    cwsim --help
    cwsim --about
    cwsim roll yyygyr
    cwsim list --help
    cwsim build --help

Description

Simulating a game of Car Wars 6e using human-defined car build configurations and bot player rules requires several tangential capabilities. This cross-platform console application started out as a small command-line interface (CLI) to introduce the required components. Many are presently accessible as commands in the CLI. Independent of the simulator feature, some commands are quite useful as game aids even if it retains a perpetual beta version tag and only provides limited functionality.

The command-line interface attempts to be as user-friendly as possible. Each command has its own help documentation. (Just use --help after any command.) Some commands have options to output pretty pictures (e.g., render and build).

The construction of builds with the build command is a current highlight. The pool of available cards when constructing builds is limited by the valid option rules; however, incomplete and extreme builds remain possible.

In their simplest form, builds are represented by a TCWB tag (e.g., tcwb4554xxxx264a734br11z). For convenience, tags persist to *.tcwb files, which are plain text files containing additional human-readable information about the build. (The files can be opened by your preferred text editor.) These build definitions are a keystone to running single-game and Monte Carlo simulations.

Use the -i option for interactive builds in the command line interface (e.g., cwsim build -i).
Auto-generated builds -g have many options.
- When using this option, be sure to explore the ability to apply weights to groups of cards.
- This was an experiment to generate diverse inputs for simulator runs, but it could be useful by itself.
TCWB builds can be constructed manually or automatically-generated and your creation can be saved in text-based files or images.
Specialized treatment for “Binder Builds” is an option.
The TCWB car configuration builds are decentralized codes that are easily shared and loaded by others.

The cards command is useful for build planning, since it searches cards by several properties to display text representations or render image files.

Explore more options with cwsim cards --help.

The -t option displays full-size cards (with redacted rule text).

cwsim cards -t beer

┌───────────────────────────┐
│ Armored               (0) │
│ BEER REFRIGERATOR         │
│ Accessory ─────────────── │
│                           │
│                           │
│                           │
│  aygo StOThE I gESTgUnst  │
│     eRi HTOFW yg ESTO     │
│       hebIGgE Tguns       │
│                           │
│   IGGe TgU ST ErIG tOFW   │
│   YgOeSTO HeBig eStgunS   │
│   HEriG TO WA Goes othe   │
│           iGgEST          │
│                           │
│                           │
│                           │
│                           │
│                       <2> │
│                      Core │
└───────────────────────────┘

The list command, by default, displays human-readable ID values for cards that are used in advanced build construction scenarios.

The -f and -x options for filtering and excluding ID values can verify inputs to identical options in the build command.
The other cwsim list <TYPE> arguments provide reference material, such as cwsim list dice and cwsim list symbol.

The roll command is simple and reliable, while the interactive part is poised for future enhancements.

See how to use it with cwsim roll --help.

Some parts of the program are obfuscated or removed from the public version.

More information is in the --about option text.

Example

A future sim command runs game simulations and produces a detailed log of all events within each round and statistical records for the overall game. The same command can run a high-performance Monte Carlo simulation to generate a CSV file with various statistics and results from thousands of simulated games.

A primary use case of this feature is to compare car build configurations and evaluate the impact of alterations.

In addition to creating a detailed single game report, video output visualizes movement and combat within the game, as seen in the following example:

The already available build command constructs the TCWB car build configurations used for input to the simulator.

Help

Each command in the command-line interface has its own help documentation. (Just use --help after any command.)

User Interface

Imagine an interface that lets you build, modify, save, and share Car Wars (6e) builds. Then, imagine being able to quickly simulate that build against virtual competitors to hone the configuration before your next game night. You no longer need to imagine.

While the command-line interface is quite powerful, sometimes you want the immediate visual satisfaction that desktop apps provide. Now there is a way to quickly compare changes to prototypes against a chosen build. No network connection required to edit builds and run simulations.

Don’t be fooled by the pretty point-and-click interface. There are plenty of user-friendly keyboard accelerators for navigating the app quickly.

Build Image

See the layout of your cards change dynamically as you make changes. Toggle zoom by tapping on the build image or using the F11 key. The view can be customized with commands in the View menu.

Comparison Build

The current build is used to set the “comparison” build in simulations. Information about your current build is displayed in the bottom-left corner with the comparison build name and summary information next to it. To copy your current build configuration to the comparison slot, “mark” it as the comparison build. You can also “swap” builds, make changes, and swap the configurations back. Swap is useful when you want to make changes to the comparison build independent of your current configuration.

While simulations are one of the unique features of the app, there is no need to run simulations. You can use the build configuration and visualization features while ignoring the comparison build.

Workbench List

The workbench list area is where builds come to life. Rules constrain what cards can be added based on cards already added, but they don’t prevent you from creating invalid builds. For example, you can’t add multiple turrets or two structure cards on the same side, but you can can add cards too big for a “small” game or forget to add a gunner.

Click the name of a cards in the workbench list to see its details. Weapon cards include a unique display of probable roll results when using the weapon in an attack.

Remove cards from your build with the red X. The Delete key will remove all cards so you start from scratch.

Duplicate or swap cards with command buttons under the remove button. Tapping the cost circle on the right side of a card in the list will initiate a replacement card search.

Cards that do not have complete rules in simulations will show a warning symbol next to their name in the list. Those cards can be used in builds and simulations, but may skew simulation results. Generally, rules that earns additional Ace or Control tokens each round are included, even when there is a warning about other rules for the card. Of course, if you want to see how well cards with a warning will work, just try them in your next game!

Menus

Menus provide easy access to commands and show their keyboard accelerators.

Open (Ctrl+O) TCWB files from others or ones you’ve previously saved in the app.

Save (Ctrl+S) build definitions as TCWB files or images. Various image layouts and formats are available under the View menu. The build files themselves can be shared and modified by others. All you need is a TCWB tag (e.g., tcwb4554xxxx264a734br11z), but files make it easy.

Rename (F2) your build to change the default name. Clear the name to go back to using a default name. The allowed characters in names in TCWB tags are limited. Inputs are sanitized for embedding in tags and normalized for display.

Example Name	Display
`PascalCaseAndHyphens-are-useful`	`PASCAL CASE and HYPHENS - ARE - USEFUL`
`GunInTheGlovebox`	`GUN in the GLOVEBOX`
`SuperAceKiller-d6-v1`	`SUPER ACE KILLER - D6 - V1`

Tag (Ctrl+T) can load a build (e.g., tcwb4554xxxx264a734br11z) from others just entering it.

Generate (Ctrl+G) a random build, if you are looking for some inspiration. Random builds attempt to match the Build (BP) and Crew (CP) of the current build, so add cards or open another build first.

Share (Ctrl+H) the TCWB build tag, file, or images.

Undo (Ctrl+Z). Redo (Ctrl+Y). Wash, rinse, repeat. We all make mistakes, so undo and redo in the app is easy. Or, maybe you don’t make mistakes and just want to go backward and forward in time. Now you can, Marty!

Copy (Ctrl+C) the current build to clipboard. The TCWB tag is copied as text along with an image of the build, so sharing either the tag or image is easy. You can copy a lighter color image to the clipboard with Ctrl+Shift+C.

Paste (Ctrl+V) a TCWB tag from clipboard to load it.

Remove all (Delete) cards from the current build to start fresh. This allows adding any card you want. It’s okay, there is an undo if you change your mind.

Add (Ctrl+F) new cards based on you current build by finding them in a search. The initial list is a random set of available cards. Search and select the card you want to add. Then, if the card requires placement on a side, choose from the available options. Only cards valid for addition to the current build are presented. For example, if you already have a Driver, you need to remove the Driver card before trying to add another Driver (or use a replacement command).

Toggle view (F11) of the workbench list display on and off to zoom into the build image.

Set the Layout to default mode or binder format, when possible.

Set the Card Size to mini or full, depending on the details you want.

Set the Tech Level you want displayed on the cards.

Refresh (F5) the view, if something looks stale.

Once you build a car, put it through a simulator against other builds for analysis. A visualization with multiple cars show what a single game looks like, but this runs hundreds or thousands of games and aggregates the results. Some cards have limitations with use by bots (or the card-specific rules haven’t been implemented yet).

Run (Ctrl+R) the simulation to see results.

Stop (Ctrl+Shift+F) a running simulation early to see the intermediate results.

Set the Sample Size desired for the simulation. More games takes longer to simulate but has a smaller margin of error. Single game simulation isn’t available, yet.

Swap (Ctrl+B) the builds used for editing and comparison. The “comparison build” is the competitor in simulations of the current build being edited.

Mark (Ctrl+Shift+B) the current build for comparison to replace the competitor with a copy of the current build. This is a destructive action (in this version), so swap and save a copy of the comparison build if you need to keep it.

Show summary (Ctrl+M) of the most recent simulation when you want to see it again. It can review results from the most recent partial simulation caused by a simulation restart. Any running simulation will restart when changes to builds or settings are made.

Drive Offensively! (Ctrl+Shift+F1) to get more Car Wars products.

Documentation (Ctrl+F1) will help you find your way back here.

About (F1) displays a bunch of information for nerds and some cool ASCII art from the command-line app.

Future Ideas

Some future ideas, in no particular order.

Rules for more cards! (Something you want? Let me know!)
Additional simulator configuration options, such as arena size, layout, and armor points.
~~Reset running simulation when builds change.~~ Done!
Estimated time to complete simulation.
More intermediate summary information during simulation. (Not just win percentage.)
Better statistical summary of simulations.
Detailed statistics in CSV format.
Video output for one-game simulations. (These are fun to watch!)
Additional competitors, including team designations.
Include changes to competitor builds in undo/redo buffer.
Card browser independent of builds.
Improved browsing of cards during construction, weapon statistics, etc.
Warning when exceeding a target AP, BP, and CP.
Generate random builds based on chosen target, rather than just current build.
Move cards between sides (e.g., when cards cannot be duplicated, like accessories).
Persist user settings (e.g., no need to set sample size to 10000 and view layout to binder builds every time).
Image preview of build files in Windows Explorer (e.g., prettier files).
Load recent builds from recently used list.
Saving images to a “printable” format (but it is already available in a few places, include Ctrl+Shift+C for copying to clipboard).
Performance improvements.

Download

Windows App

Welcome to Uncle Al’s Proving Grounds!

Car Wars Simulator is an unofficial “game aid” for the sixth edition of Steve Jackson Games’ Car Wars (6e).

BUILD your next car by searching for cards and EDIT with confidence knowing you can easily undo changes.
SAVE builds before your next game night or SHARE ideas with others.
RUN a Monte Carlo SIMULATION against another build to compare results from hundreds or thousands of games!

After downloading, read more about how to use the app above.

Command-Line Interface (CLI)

To download and run on Windows, you may need to “keep” and/or “trust” the executable multiple times.

To download and run on Linux (or Windows Subsystem for Linux), the following script may be useful for installing and verifying the cwsim executable version:
sudo wget https://www.tiwahu.com/download/cw-sim/beta/linux-x64/cwsim \
  -O /usr/local/bin/cwsim
sudo chmod +x /usr/local/bin/cwsim
cd ~
cwsim

Setup

Download the command line app for your device.
Open a command prompt in the directory of the executable.
Run cwsim --help (or cwsim <command> --help) from the command prompt for help.

Resources

Additional resources for translating code values in Car Wars Simulator. Printouts could be useful in physical Car Wars 6e games.

Tiwahu Software

getting everything just exactly perfect