diff options
author | InigoGutierrez <inigogf.95@gmail.com> | 2023-06-06 20:09:08 +0200 |
---|---|---|
committer | InigoGutierrez <inigogf.95@gmail.com> | 2023-06-06 20:09:08 +0200 |
commit | 12431ce4c4ed52fcfc2180bcffdfec33e72b73ba (patch) | |
tree | 630235a3db5287604217e87126931de842ad6499 /doc/tex/appendixes.tex | |
parent | 88fbf5f8919211cfa06116a76f42fb26ec9f2e18 (diff) | |
download | imago-12431ce4c4ed52fcfc2180bcffdfec33e72b73ba.tar.gz imago-12431ce4c4ed52fcfc2180bcffdfec33e72b73ba.zip |
Written user manuals.
Diffstat (limited to 'doc/tex/appendixes.tex')
-rw-r--r-- | doc/tex/appendixes.tex | 279 |
1 files changed, 274 insertions, 5 deletions
diff --git a/doc/tex/appendixes.tex b/doc/tex/appendixes.tex index 581f764..ec6c2aa 100644 --- a/doc/tex/appendixes.tex +++ b/doc/tex/appendixes.tex @@ -3,6 +3,275 @@ Additional information is included here, after the main sections regarding the project. +\subsection{User manual} + +This manual explains to the end user how to use the software. + +\subsubsection{The game: the \texttt{go.py} interface} + +\texttt{go.py} is a simple executable to interact with the Game system of this +project. It makes use of no artificial intelligence whatsoever, its aim just +being allowing for human play. It can be executed in a shell as: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \texttt{python go.py} + \end{minipage} + \par +} + +or by any other means of executing a python file with access to its input and +output streams. The executable receives no arguments and has no options. + +When executed the user is presented with the following interface: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \inputminted{text}{listings/goInterface/01-start.txt} + \end{minipage} + \par +} + +The state of the board (empty for now) is shown and the user is prompt for a +move. The color to make the move is marked between brackets: \texttt{B} for +Black, \texttt{W} for White. + +A move can now be provided for the Black player, such as \texttt{e6}. + +{ + \centering + \begin{minipage}{0.4\textwidth} + \inputminted{text}{listings/goInterface/02-firstMove.txt} + \end{minipage} + \par +} + +The interface shows again the state of the board. The game can continue until +the move ``pass'' is provided for both players. + +{ + \centering + \begin{minipage}{\textwidth} + \begin{multicols}{2} + \inputminted[fontsize=\small]{text}{listings/goInterface/03-fullGame.txt} + \end{multicols} + \end{minipage} + \par +} + +The game will also show captured stones and notify illegal moves, such as wrong +input or because of the \gls{ko} rule. + +{ + \centering + \begin{minipage}{\textwidth} + \begin{multicols}{2} + \inputminted[fontsize=\small]{text}{listings/goInterface/04-ko.txt} + \end{multicols} + \end{minipage} + \par +} + +\subsubsection{The engine: the \texttt{imagocli.py} interface} + +\texttt{imagocli.py} is a text interface which follows the \acrshort{gtp} +specification. It can be executed in a shell as: + +{ + \centering + \begin{minipage}{0.4\textwidth} + \texttt{python imagocli.py} + \end{minipage} + \par +} + +When executed interactively and before any input is provided it just waits for +input, with no prompt whatsoever. This is in compliance with the \acrshort{gtp} +specification. + +There are the commands that the program knows and a short description of what +each does: + +\begin{itemize} + + \item \texttt{list\_commands}: Shows a list of the commands the engine + knows. + \item \texttt{known\_command}: Receives an argument and tells wether it is a + known command or not. + \item \texttt{name}: Shows the name of the program. + \item \texttt{version}: Shows the version of the program. + \item \texttt{protocol\_version}: Shows the implemented \acrshort{gtp} + version number. + \item \texttt{boardsize}: Changes the size of the board. Results in an + arbitrary internal state unless \texttt{clear\_board} is called after + it. + \item \texttt{clear\_board}: The board is cleared of stones, the record of + captured stones resets to zero and the move history resets to empty. + \item \texttt{komi}: Sets the value for \gls{komi}. + \item \texttt{fixed\_handicap}: The given number of handicap stones are + placed following the protocol specification, which follows traditional + placement of handicap. + \item \texttt{place\_free\_handicap}: The given number of handicap stones + are placed following the AI criteria. + \item \texttt{set\_free\_handicap}: The given number of handicap stones are + placed on the requested vertices. + \item \texttt{play}: A stone of the requested color is played at the + requested vertex. + \item \texttt{genmove}: A stone of the requested color is played following + the AI criteria. The played move is printed. + \item \texttt{undo}: The state is restored to before the last move, which is + removed from the move history. + \item \texttt{showboard}: Prints a text representation of the board state. + +\end{itemize} + +Here is an example of a session. + +{ + \centering + \begin{minipage}{\textwidth} + \begin{multicols}{2} + \inputminted[fontsize=\small]{text}{listings/imagocliInterface/01-start.txt} + \end{multicols} + \end{minipage} + \par +} + +Note how responses from the program begin with an equals symbol and a space but +with a question mark replacing the space to mark errors, like when providing an +unknown command (exemplified here with \texttt{nonexistentcommand} in line 16). + +This session consists first of some information asked to the engine: its name, +its version and the version of \acrshort{gtp} it implements. Then exemplifies +how to check if a command is implemented and an error answer. Then, the main +commands to interact with the game and the \acrshort{ai} are executed: +\texttt{play}, to provide an initial explicit move, and \texttt{genmove}, to +obtain an \acrshort{ai}-generated move. Finally, a representation of the board +state after these two moves is obtained with \texttt{showboard} and the engine +is closed with \texttt{quit}. + +\subsubsection{Example of \acrshort{gui} use: configuring Sabaki} + +Since the main aim of implementing a \acrshort{gtp} interface is having it be +compatible with existing tools, an explanation of how to use in in conjunction +with one such established tool is provided. + +Sabaki \cite{sabaki} is a Go board software compatible with \acrshort{gtp} +engines. It can be downloaded from \texttt{https://sabaki.yichuanshen.de/}. When +started, it shows a screen such as the one in \fref{fig:sabakiStart}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/01-initialScreen.jpg} + \caption{Sabaki after being started. + }\label{fig:sabakiStart} + \end{center} +\end{figure} + +This initial screen contains a 19x19 board ready to be played on by local human +players. The stones can be placed by clicking on the desired vertices of the +board and, as would be expected, the interface swaps between players after each +move. An example of the screen after some initial moves can be seen on +\fref{fig:sabakiExampleMoves}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/02-examplePlaying.jpg} + \caption{Playing some moves on the default board. + }\label{fig:sabakiExampleMoves} + \end{center} +\end{figure} + +To set Sabaki to work with \texttt{imagocli.py} first open the engines sidebar +by clicking on ``Engines'', then ``Show Engines Sidebar''. The window should now +look like the one shown on \fref{fig:sabakiEnginesSidebar}, with the engines +sidebar open at the left but with nothing shown on it yet. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/03-enginesSidebar.jpg} + \caption{Opened the engines sidebar (on the left). + }\label{fig:sabakiEnginesSidebar} + \end{center} +\end{figure} + +Click on the symbol on the top left of the engines sidebar, the one with a +triangle inside of a circle (the play button), and on ``Manage Engines...'' on +the opened floating dialog. The engine management window will open, as shown on +\fref{fig:sabakiEngineManagement}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/04-engineManagement.jpg} + \caption{The engine management window. + }\label{fig:sabakiEngineManagement} + \end{center} +\end{figure} + +Engines are listed on the big box at the center of the window, but if none has +yet been configured nothing will be shown there. Click ``Add'' to create the +first engine entry. Give it a name by writing on the first line of the newly +created entry, then write the path to the \texttt{imagocli.py} executable +besides the folder symbol, at the text box prompting for the path to the engine. +Arguments and initial commands to provide to the engine can be configured here, +but none of them will be needed for the default configuration of \program{}. An +example of the configured engine is shown on \fref{fig:sabakiConfiguredEngine}. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/05-configuredEngine.jpg} + \caption{\texttt{imagocli.py} configured as engine. + }\label{fig:sabakiConfiguredEngine} + \end{center} +\end{figure} + +The engine management window can now be closed by clicking on ``Close'' at its +bottom right. Click again on the play button, the one on the top left of the +engines sidebar, and select the newly created engine entry. The engine will now +be started. By default, Sabaki will provide it the \texttt{name}, +\texttt{version}, \texttt{protocol\_version} and \texttt{list\_commands} +commands, and the text interface will be shown on the engines sidebar. To play +against the engine, click on ``File'', then ``New'', or just use the keyboard +shortcut Ctrl+N. A window will be shown where a new game can be configured. The +most important settings are making the engine be one (or both) of the players +and setting the board size to 9x9, since this is where the engine plays best. +For example, to set the engine as the white player, click on the arrow next to +the white player's name and select the engine, represented by the name given to +it before), on the floating menu. The size of the board can be set on the +``Board Size'' setting. Other options allow to set a name for the other player, +a name for the match, the \gls{komi} and the handicap stones, if any. When +ready, click ``Ok'' on the bottom right of the window. An example configuration +can be seen on \fref{fig:sabakiConfiguringAMatch}. If the engine doesn't respond +to the moves, which should be clear since its status is shown on the engines +sidebar, try adding it to the match by clicking on ``Attach Engine'' and then on +its name on the new match window, instead of directly on its name. This creates +a new entry for the engine on the engines sidebar. Multiple instances of the +same or different engines can be running at the same time; to remove one, just +right click on its name and click on ``Detach'' on the floating menu. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/06-configuringAMatch.jpg} + \caption{Configuring a match against the engine. + }\label{fig:sabakiConfiguringAMatch} + \end{center} +\end{figure} + +The engine can now be played against: when black (the human) makes a move, it +will respond as white. Some initial moves against it can be seen on +\fref{fig:sabakiAgainstTheEngine}. Note the interaction between Sabaki and the +\acrshort{gtp} interface on the engines sidebar. + +\begin{figure}[h] + \begin{center} + \includegraphics[width=0.8\textwidth]{img/sabakiManual/07-playingAgainstImago.png} + \caption{Playing some moves against \program{}. + }\label{fig:sabakiAgainstTheEngine} + \end{center} +\end{figure} + \subsection{Budget} Here are tables regarding the costs of resources and development for the @@ -12,7 +281,7 @@ project. The costs are calculated based on a programmer salary of 20€/hour. -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r r} \toprule @@ -34,7 +303,7 @@ The costs are calculated based on a programmer salary of 20€/hour. \subsubsection{Material resources} -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r} \toprule @@ -48,7 +317,7 @@ The costs are calculated based on a programmer salary of 20€/hour. \subsubsection{Totals} -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r} \toprule @@ -64,9 +333,9 @@ The costs are calculated based on a programmer salary of 20€/hour. } \end{table} -\subsection{Budget for the client} +\subsubsection{Budget for the client} -\begin{table}[h] +\begin{table}[H] \makebox[\linewidth]{ \begin{tabular}{l r} \toprule |