NAME
Game::Go::Terminal - a playable game on two filehandles
VERSION
Version 0.03
SYNOPSIS
my $t = Game::Go::Terminal->new(size => 9, level => 2);
my $result = $t->start; # returns, never exits
DESCRIPTION
A game of Go against the bot, on in and out.
It is a separate module from Game::Go for a reason a sibling distribution paid for: that one put a thousand lines of escape codes in its top-level namespace module, which is why only its board class ever turned out to be reusable.
Why it ships
The confirmation phase is a two-person negotiation and no unit test will tell you it is unusable. This is where somebody finds out that the proposal is the wrong way round, or that the prompt never says which stones are marked, or that "dispute" reads like a refusal rather than a request to play on. Finding that out here costs an afternoon; finding it out after the JavaScript is written costs the JavaScript too.
What the display has to get right
These are rules rather than decoration:
Coordinates on both axes, A to T with I left out and rows numbered from the bottom. A Go player reads them off the edge constantly, which is not true of any other game on this roster.
The last move marked and the captures named. A capture of a large group is the most important thing that can happen in Go and it is completely invisible in an after-picture.
The confirmation phase spelled out. Two passes stop play; they do not end the game. A player told "the game is over" and then shown a board they can still type at will file a bug, and they will be right.
The final arithmetic, line by line. A board full of stones followed by "W+6.5" with no working reads as something the program made up, and komi and prisoners are both invisible on the board.
The board is drawn as a board
Grid lines, not a lattice of dots: ┌─┬─┐ with ╋ on the star points and stones sitting on the intersections. A go board has a line between every two points and drawing it costs nothing, because the space between two cells was already there.
That space is also what the cursor spends. See "pick_point".
A mark has to be a shape
The last move is drawn as a ringed stone, ◉ or ◎, and a point a capture has just emptied as ×. Both are characters, so they survive --ascii, NO_COLOR and a redirected handle.
That is not a preference, it is a bug this had. The last move was marked by wrapping the cell in \e[31m, but the cell was already \e[1;30m●\e[0m from "glyph", so the inner code won and the reset closed it: the mark was emitted on every board and never once visible. A colour laid over a colour is not a mark.
You point at the move you mean
On a terminal with Term::ReadKey installed the arrow keys walk a cursor over the board, the point under it shows the stone you would play, and return plays it. p passes, r resigns, t goes back to typing, ? lists the keys and q stops. Without Term::ReadKey, or off a terminal, every move is typed as before.
A list would be absurd here, which is what makes this different from the other terminals on this roster. A 19x19 board offers up to 362 legal moves, so there is nothing to enumerate: the board already shows every one of them, laid out in the shape the player is thinking in. The cursor is two-dimensional for the same reason.
What the point under the cursor says
One line, from the engine rather than from arithmetic here: whether the point can be played and why not if it cannot, what the move would capture, and how many liberties the resulting group would have.
E5: a lone stone with 4 liberties
A8: takes 1, a lone stone with 3 liberties
C9: joins a group of 2 with 6 liberties
A9: that move would leave your own stones with no liberty
It is the engine's own answer because "preview" plays the point on a clone and asks the clone. Nothing is played, which matters more here than in the other games on this roster: a preview that moved the game would be worse than no preview, and the suite asserts the board and the turn are untouched after one.
A clone is 0.009 ms on 19x19, so the line can be recomputed on every keystroke without anybody noticing.
ATTRIBUTES
in, out
The two filehandles. Keeping them as attributes is what lets a test play a whole game in process against tied in-memory handles, with no fork and no subprocess to eat the test output.
size, level, colour, komi, handicap, seed, ascii, quiet
Every one is validated in the constructor. A sibling's terminal refused a bad colour with a tidy sentence and exit 2, and died on a bad variant with a raw Perl message and exit 255, because one option was checked in the constructor and the other several calls deeper.
colour accepts b, w, black, white, dark and light.
game, bot
The Game::Go being played and the Game::Go::Bot playing the other side, built in the constructor from the options above. They are readable so that a test can assert against the position rather than against the drawn board, which is the difference between a test that checks the rules and one that checks the spacing.
ansi
Whether to colour the output. Worked out at construction if not given: NO_COLOR wins over an explicit request, which is the whole point of the convention, and otherwise colour is used only when out is a terminal.
METHODS
start
Plays the game and returns the Game::Go::Result. It never calls exit: a module that exits cannot be tested in process.
run
exit Game::Go::Terminal->run(@ARGV);
The whole command line program as a class method: parses the options bin/go documents, builds the terminal, plays, and returns the exit status rather than calling exit: 0 for a win or a game with no winner, 1 for a loss, 2 for a bad option, a leftover word or a value the terminal refuses, with the reason and the usage on STDERR. --help prints the usage on STDOUT and returns 0. Signal handlers are local to the call and the terminal is left in cooked mode on every way out, so a launcher such as Game::Terminal can call it in its own process and carry on afterwards. Colour is off when NO_COLOR is set, as it is off a terminal.
board_text
The board as lines, coordinates and all.
glyph
interactive, clear
Whether out is a terminal, and the screen clear the picker does before each frame. A 19x19 board is twenty-three lines, so a picker that scrolled one of them per keystroke would be unusable.
picking
Whether a point is pointed at rather than typed. Settable, because a failed enter_raw and the t key turn it off for the rest of the game. Unset, it follows "keys_available".
keys_available, enter_raw, leave_raw
Whether there is anything to read keys with, and cbreak on and off. cbreak rather than raw, so an interrupt stays an interrupt.
keysource, pending, raw
A coderef returning ONE character in place of Term::ReadKey, characters read and given back, and the cbreak state. keysource is what lets t/23 drive the whole key loop with no terminal and no Term::ReadKey installed; one character a call, because a source handing back "\e[C" whole never becomes a right arrow.
read_char, read_key, read_sequence
One character, one keystroke as a name, and the tail of an escape sequence. A name is always longer than one character so it never collides with one, and an opener that turns out not to open a sequence goes back on "pending".
pick_point, pick_help
The cursor loop and its key list. pick_point returns true if a turn was taken and false to stop, the same contract as the typed turn.
preview
my $peek = $terminal->preview($colour, $point);
What playing a point would do, as { refused => $why } or { move, caps, libs, size }. Played on a clone; the game is not touched.
point_line
"preview" as the one line printed under the board.
One point's character.
SEE ALSO
Game::Go, Game::Go::Bot, bin/go.
AUTHOR
LNATION <email@lnation.org>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION <email@lnation.org>.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)