WATOR(1) General Commands Manual

NAME

wator - Simulates fish and sharks in a toroidal ocean with command-line, terminal and graphical interfaces.

SYNOPSIS

wator	{ run \| step \| reset } [ --width <width> ] [ --height <height> ] [ --fish <fish> ] [ --sharks <sharks> ] [ --fish-breed <fishBreed> ] [ --shark-breed <sharkBreed> ] [ --starvation <starvation> ] [ --seed <seed> ] [ --steps <steps> ] [ --tick-millis <tickMillis> ] [ --config <config> ] [ -v ] [ -q ] [ --debug ]
wator	--version [ -v ] [ -q ]
wator	--help \| --sysinfo
wator	--init [ --config <config> ]
wator	[ <arguments> ] --tui [ --tui-color-scheme <scheme> ]
wator	[ <arguments> ] --gui
wator

DESCRIPTION

This manual page documents the wator command supplied by funcodes-wator. Fish move and breed in a rectangular ocean, while sharks eat fish, breed and starve if they remain unfed. Opposite edges meet, so an animal leaving one edge reappears at the other. The Java application revisits the author’s Turbo Pascal experiment using the REFCODES SDK.

The model considers eight neighboring cells, including diagonals, and updates the world in place, column by column. Each animal acts once per generation, and newborn animals wait until the next generation. Breeding requires a successful move. Sharks prefer neighboring fish to empty water and die at the beginning of a turn if their hunger has already reached the configured limit.

Starting wator without arguments opens the JavaFX graphical user interface (GUI). The –gui option selects it explicitly, while –tui opens the terminal user interface (TUI). Other arguments prefill either form, and run is preselected when no action is supplied. Press Run to execute the selected action. The two presentation flags cannot be combined. Supplying an action without either flag executes it directly on the command line, which also works without a graphical desktop.

The run action initializes a world and advances it for the requested number of generations. The step action advances the current world once, initializing a new one first if its world settings have changed. The reset action restores the configured initial population without advancing it. State is retained between actions within a form, while each separate command-line invocation starts a new application. Without a configured seed, run and reset choose a fresh seed and step retains the current one. An explicit seed reproduces the Java algorithm’s initial world and subsequent sequence for the same settings, rather than Turbo Pascal’s random sequence.

The default world has 69 columns, 22 rows, 53 fish and 5 sharks, with fish breeding age 6, shark breeding age 12 and starvation limit 4. A run defaults to 500 generations with a 100 ms delay between generations. Width and height must be positive and their product must not exceed 1,000,000 cells. Initial populations must be non-negative and fit together into the world. Breeding ages and the starvation limit must be positive, while steps and delay may be zero but not negative. Loaded configuration values override these defaults, and explicit command arguments take precedence over configuration values.

The terminal view uses · for fish and > for sharks, while the plain command-line display uses . and @. The graphical view shows green fish and larger gray sharks in blue water. A small viewport clips the world without changing its dimensions. In the TUI, focus the board with Tab or a click and navigate with the arrow keys, Page Up/Down, Home/End, the mouse wheel or scrollbars. The GUI supports dragging the board and using scrollbars. The Cancel button stops an active command in either form, and Ctrl+C interrupts a command-line run.

Depending on the downloaded package, the executable is named wator-x.y.z.jar, wator-launcher-x.y.z.sh, wator-launcher-x86_64-x.y.z.elf, wator-launcher-x86_64-x.y.z.exe, wator-bundle-x86_64-x.y.z.elf or wator-bundle-x86_64-x.y.z.exe, where x.y.z is the application version. This manual uses wator for the corresponding invocation. Run a JAR with java -jar wator-x.y.z.jar. Launchers and the JAR require Java 25 or later, while bundles include their Java runtime. The packaged JavaFX native libraries support Linux x86-64, Windows x86-64 and Apple Silicon. Other GUI architectures require matching JavaFX native libraries.

OPTIONS

run:	Initializes a new world and advances it for –steps generations.
step:	Advances the current world by one generation, creating a new world first if its settings have changed.
reset:	Restores the configured initial world without advancing it.
--config <config>:	Selects the configuration file or resource to load, or the destination for –init.
--debug:	Enables additional developer-readable diagnostic output.
--fish <fish>:	Initial fish population, default 53.
--fish-breed <fishBreed>:	Fish breeding age in generations, default 6.
--gui:	Opens the graphical form. Other arguments prefill its controls without starting the action.
--height <height>:	Number of rows, default 22.
--help:	Prints command-line help.
--init:	Creates a configuration file from the packaged template.
-q --quiet:	Suppresses informational output and progress while retaining result data.
--seed <seed>:	Random seed as a signed 64-bit integer. Omit it from both the arguments and configuration for a fresh seed on run or reset.
--shark-breed <sharkBreed>:	Shark breeding age in generations, default 12.
--sharks <sharks>:	Initial shark population, default 5.
--starvation <starvation>:	Shark hunger limit in generations, default 4.
--steps <steps>:	Generations per run, default 500. Zero runs until cancelled. The step and reset actions still advance one and zero generations respectively.
--sysinfo:	Prints system information for debugging.
--tick-millis <tickMillis>:	Delay between generations in milliseconds, default 100. Zero removes the deliberate delay.
--tui:	Opens the terminal form. Other arguments prefill its controls without starting the action.
--tui-color-scheme <scheme>:	Selects a terminal color scheme, for example GREEN_SCREEN. Use this option with –tui.
-v --verbose:	Enables additional human-readable informational output through the logger.
--version:	Prints the application version.
--width <width>:	Number of columns, default 69.

EXAMPLES

Open the graphical form:

wator --gui

Open the terminal form with a reproducible experiment ready to run:

wator --tui run --seed 1234 --steps 100

Run 100 generations directly on the command line with a 50 ms delay:

wator run --seed 1234 --steps 100 --tick-millis 50

Prepare a larger population and a green terminal palette:

wator --tui run --width 50 --height 25 --fish 200 --sharks 20 --tui-color-scheme GREEN_SCREEN

Advance a freshly initialized world by one generation in a command-line invocation:

wator step --seed 1234

Create an editable configuration file and then use it in the graphical form:

wator --init --config ocean.ini
wator --gui run --config ocean.ini

FILES

The default configuration filename is wator.ini. The –init action copies the packaged template to that file or to the path supplied with –config. Configuration keys use the aliases shown below, including the camelCase names fishBreed, sharkBreed and tickMillis. Explicit command arguments override file values.

width=69
height=22
fish=53
sharks=5
fishBreed=6
sharkBreed=12
starvation=4
steps=500
tickMillis=100
seed=12

The supplied template includes seed=12. Remove that entry to select a fresh seed on each run or reset. Repeating step within a form then continues to use the current world’s seed.

ENVIRONMENT

The command help and form descriptions support English and German. Set the Java system property org.refcodes.messages.locale or the environment variable ORG_REFCODES_MESSAGES_LOCALE to en or de to select the message locale explicitly. Without an override, the JVM’s default display locale is used, with English as the fallback for unavailable translations. Command names, option names and configuration keys remain language-independent.

BUGS

Report issues in the funcodes-wator issue tracker.

AUTHOR

Siegfried Steiner steiner@refcodes.org

Wa-Tor manpage

Categories

Tags