Commit 04125f9e authored by Matthew Hausknecht's avatar Matthew Hausknecht

Updated manual

parent ec99d4cb
cmake_minimum_required(VERSION 2.8.3) cmake_minimum_required(VERSION 2.6)
project(hfo) project(hfo)
include(ExternalProject) include(ExternalProject)
......
No preview for this file type
...@@ -14,7 +14,7 @@ ...@@ -14,7 +14,7 @@
\usepackage{fullpage} \usepackage{fullpage}
\usepackage{enumitem} \usepackage{enumitem}
\title{Half Field Offense \\ Technical Manual} \title{RoboCup 2D Half Field Offense \\ Technical Manual}
\author{Matthew Hausknecht} \author{Matthew Hausknecht}
\begin{document} \begin{document}
...@@ -24,15 +24,162 @@ ...@@ -24,15 +24,162 @@
\section{Overview} \section{Overview}
This document describes the state and action spaces of the HFO domain. This document describes the installation, usage, state, and action spaces of the HFO domain.
\section{Installation}
Installation with CMake:
\begin{verbatim}
> mkdir build && cd build
> cmake -DCMAKE_BUILD_TYPE=Release ..
> make -j4 # Replace 4 with the number of cores on your machine
> make install # This just copies binaries to the HFO directory; no sudo required
\end{verbatim}
HFO installation has been tested on Ubuntu Linux and OSX. Successful
installation depends on
\verb+CMake, Boost-system, Boost-filesystem, Flex+. By default, the
soccerwindow2 visualizer is also built and requires
\verb+Qt4+. Experimentally speaking, HFO is fully-functional without
the visualizer. To disable this component, use the following cmake
command:\\
\noindent \verb+ > cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SOCCERWINDOW=False ..+
\subsection{Python Interface}
The Python interface is required for interfacing Python agents to the
HFO domain. To install this interface, from the main HFO directory:
\noindent \verb+ > pip install .+
or
\noindent \verb+ > pip install --user .+
if you have limited permissions on the machine.
\section{Uninstall}
The install is completely contained in the HFO directory. Simply
delete this directory to uninstall. If you have installed the python
interface, uninstall it as follows: \verb+pip uninstall hfo+.
\begin{figure}[htp]
\centering
\includegraphics[width=\textwidth]{figures/HFODiagram}
\caption{HFO is comprised of several components which communicate
over the network. Network connections are depicted with orange
ovals. Calling the HFO executable starts the trainer, visualizer,
and all the offensive and defensive npcs (Agent2d) as well as the
offensive and defensive agent servers. Your code then uses the HFO
interface to connect your agent to an agent server. Once all
servers have connected agents, the game begins. The trainer
oversees the game and is responsible for resetting the players
between episodes.}
\label{fig:hfo}
\end{figure}
\section{Basic Usage}
RoboCup 2D soccer is designed to be played between two teams of
autonomous agents who communicate with a game server. Shown in Figure
\ref{fig:hfo}, the HFO domain reflects these design choices and allows
arbitrary teams to be created consisting of some mix of
non-player-controlled agents (agent2d npcs) and player-controlled
agents. These options are specified through the following flags:\\
\noindent
\verb+ > ./bin/HFO --offense-agents=1 --defense-agents=1 --offense-npcs=2 --defense-npcs=2+\\
This would create a 3v3 game with one player-controlled agent on
each team. In order for the game to start, you must connect your
player-controlled agents to the waiting agent servers. This is done
through the call:\\
\noindent \verb+ > hfo.connectToAgentServer(6000, LOW_LEVEL_FEATURE_SET);+\\
or in Python:\\
\noindent \verb+ > hfo_env.connectToAgentServer(6000, HFO_Features.LOW_LEVEL_FEATURE_SET)+\\
By default, the server for the first agent is allocated to port
6000. Subsequent ports are allocated sequentially backwards (e.g. to
connect the second agent, port 5999 would be used). The default port
may be changed as follows:\\
\noindent \verb+ > ./bin/HFO --port 12345+
\section{Visualizer}
The SoccerWindow2 Visualizer allows a live game to be viewed as it
progresses. By default, the visualizer is enabled. However, the game
will likely proceed at a pace too fast for meaningful watching. To
enforce a standard pace, disable sync-mode:\\
\noindent \verb+ > ./bin/HFO --no-sync+\\
To disable visualization altogether, run in headless mode:\\
\noindent \verb+ > ./bin/HFO --headless+\\
The visualizer may also be used after the end of a game by replaying
logs, as discussed in the next section.
\section{Logging}
By default, the soccer server generates game logs and stores them in
the \verb+log+ directory. The main game log is
\verb+log/incomplete.rcg+. This log may be replayed using the
soccerwindow2 visualizer. \\
\noindent To replay a log: \\
\verb+ > ./bin/soccerwindow2 -l log/incomplete.rcg+
\noindent To disable logging:\\
\verb+ > ./bin/HFO --no-logging +
\noindent To change the logging directory:\\
\verb+ > ./bin/HFO --log-dir /path/to/new/dir +
\section{Recording}
It is possible to record the low-level state perceptions, actions, and
game status of all players:\\
\noindent \verb+ > ./bin/HFO --record + \\
This will produce logs for all the offensive players
(\verb+log/left-[1-11].log+) and defensive players
(\verb+log/right-[1-11].log+). The first offensive player is left-11,
so in the case of single-agent offense, left-11.log will contain the
active player's record. The log, \verb+incomplete.rcg+ may be used to
verify the player numbers on field.
\section{Randomness}
A seed may be specified as follows:\\
\noindent \verb+ > ./bin/HFO --seed 123+\\
This seed will determine the placement of the players and the ball at
the beginning of each episode. Due to non-determinism in the player
policies and server, it is not sufficient to precisely replicate full
games. It \textit{only} replicates the starting conditions for each
episode. The player's behavior, observations, and physics all proceed
stochastically.
\section{State Spaces} \section{State Spaces}
The HFO domains provides a choice between a low-level feature set and The HFO domains provides a choice between a low-level feature set and
a higher-level feature set. Selecting between the different feature a higher-level feature set. Selecting between the different feature
sets is accomplished when connecting to the agent server. See sets is accomplished when connecting to the agent server. Also see
\verb|examples/hfo_example_agent.cpp| and \verb|examples/hfo_example_agent.cpp| and
\verb|examples/hfo_example_agent.py| for examples. \verb|examples/hfo_example_agent.py| for examples:
\begin{verbatim}
> hfo.connectToAgentServer(6000, LOW_LEVEL_FEATURE_SET);
> hfo.connectToAgentServer(6000, HIGH_LEVEL_FEATURE_SET);
\end{verbatim}
\subsection{High Level Feature Set} \subsection{High Level Feature Set}
A set of high-level features is provided following the example given A set of high-level features is provided following the example given
...@@ -239,9 +386,9 @@ and high-level strategic actions. Basic, parameterized actions are ...@@ -239,9 +386,9 @@ and high-level strategic actions. Basic, parameterized actions are
provided for locomotion and kicking. Additionally high-level strategic provided for locomotion and kicking. Additionally high-level strategic
actions are available for moving, shooting, passing and actions are available for moving, shooting, passing and
dribbling. Control of the agent's head and gaze is not provided and dribbling. Control of the agent's head and gaze is not provided and
follows Agent2D's default strategy. Selection between high-level and follows Agent2D's default strategy. Both low and high level actions
low-level actions spaces is performed when connecting to the agent are available through the same interface. It is the responsibility of
server. the user to faithfully report which action spaces were used.
\subsection{Low Level Actions} \subsection{Low Level Actions}
\begin{itemize} \begin{itemize}
...@@ -254,7 +401,7 @@ server. ...@@ -254,7 +401,7 @@ server.
specified direction. Valid values range between [-180, 180] degrees specified direction. Valid values range between [-180, 180] degrees
where 90 degrees turns the agent to directly to its right side.} where 90 degrees turns the agent to directly to its right side.}
\item{\textbf{Tackle}(degrees): Contest the ball. Direction \item{\textbf{Tackle}(degrees): Contest the ball. Direction
varies between [-180, 180]. TODO: Better description.} varies between [-180, 180].}
\item{\textbf{Kick}(power, degrees): Kick the ball with power [0, 100] \item{\textbf{Kick}(power, degrees): Kick the ball with power [0, 100]
in relative direction [-180, 180]. Has no effect if the agent does in relative direction [-180, 180]. Has no effect if the agent does
not possess the ball.} not possess the ball.}
...@@ -279,6 +426,18 @@ server. ...@@ -279,6 +426,18 @@ server.
combination of short kicks and moves.} combination of short kicks and moves.}
\end{itemize} \end{itemize}
\section{Developing a New Agent}
New agents may be developed in C++ or Python. In Python, as long as
the hfo interface has been installed, the agent needs only to
\verb+from hfo import *+. In C++ it is necessary to
\verb+#include <HFO.hpp>+ and also to link against the shared object
library \verb+lib/libhfo.so+ when compiling:\\
\begin{verbatim}
> g++ example/your_new_agent.cpp -I src -L lib -Wl,-rpath=lib -lhfo
\end{verbatim}
\bibliographystyle{abbrv} \bibliographystyle{abbrv}
\bibliography{manual} \bibliography{manual}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment