LCOM1920-T5G03

\documentclass{article}

% Hyperreferences

\usepackage{hyperref}

% Margins

\usepackage[top=35mm,bottom=35mm,left=25mm,right=25mm]{geometry}

% Graphics and images

\usepackage{graphicx} \graphicspath{{./images/}}

\usepackage{subcaption}

\usepackage{float}

% Encodings (to render letters with diacritics and special characters)

\usepackage[utf8]{inputenc}

% Language

\usepackage[english]{babel}

% Section pagebreaks

\usepackage{titlesec}

\newcommand{\sectionbreak}{\clearpage}

\newcommand{\sectionnobreak}{% for when I want a section that does not break

  \global\toggletrue{afterpart}%

  \section

}

% Source code

\usepackage{listings}

\usepackage{xcolor}

\renewcommand{\lstlistingname}{File}

\lstset{

    frame=tb, % draw frame at top and bottom of the code

    tabsize=4, % tab space width

    numbers=left, % display line numbers on the left

	showstringspaces=false, % don't mark spaces in strings    

    commentstyle=\color{green}, % comment color

    keywordstyle=\color{blue}, % keyword color

    stringstyle=\color{red} % string color

}

\lstdefinelanguage{Maxima}{

	keywords={log,jacobian,determinant,subst},

	sensitive=true,

	comment=[n][\itshape]{/*}{*/}

}

% Tables with bold rows

\usepackage{tabularx}

\newcommand\setrow[1]{\gdef\rowmac{#1}#1\ignorespaces}

\newcommand\clearrow{\global\let\rowmac\relax}

\clearrow

% Math stuff

\usepackage[mathscr]{euscript}

\usepackage{amsmath,amssymb}

\usepackage{mathtools}

\usepackage{enumitem}

\newcommand{\expnumber}[2]{{#1}\mathrm{e}{#2}} % scientific notation

% Definitions, theorems, remarks,...

\usepackage{amsthm}

\newtheorem{definition}{Definition}[section]

\newtheorem{theorem}{Theorem}[section]

\newtheorem{corollary}{Corollary}[theorem]

\newtheorem{lemma}[theorem]{Lemma}

\renewcommand\qedsymbol{$\blacksquare$}

\theoremstyle{remark}

\newtheorem*{remark}{Remark}

% Contents title

\addto\captionsenglish{\renewcommand*\contentsname{Table of contents}}

% Headers and footers

\usepackage{fancyhdr}

\pagestyle{fancyplain}

\fancyhf{}

\lhead{ \fancyplain{}{LabWars - Final report (LCOM 2019/20)}}

\lfoot{ \fancyplain{}{T5G03}}

\rfoot{ \fancyplain{}{\thepage} }

%

\newcommand{\email}[1]{

{\texttt{\href{mailto:#1}{#1}} }

}

\newcommand{\role}[1]{

\begin{tabular}{l l}

	\begin{minipage}[t]{30mm} \textbf{Roles} \end{minipage} &

	\begin{minipage}[t]{125mm} #1 \end{minipage}

\end{tabular}\\

}

\newcommand{\func}[1]{

\begin{tabular}{l l}

	\begin{minipage}[t]{30mm} \textbf{Functionalities} \end{minipage} &

	\begin{minipage}[t]{125mm} #1 \end{minipage}

\end{tabular}\\

}

% Metadata

\title{\Huge LabWars \\ \Large Final report \\ \vspace*{4pt} \large LCOM 2019/20}

\author{

T5G03\\

\begin{tabular}{r l}

	\email{up201806429@fe.up.pt} & Diogo Miguel Ferreira Rodrigues        \\

	\email{up201806554@fe.up.pt} & Telmo Alexandre Espirito Santo Baptista

\end{tabular}

}

\date{06/01/2020}

% Document

\begin{document}

%\begingroup

	\maketitle

%	\let\clearpage\relax

%	\setcounter{tocdepth}{2}

	\tableofcontents

%\endgroup

\section{User instructions}

\subsection{How to play}

In all game modes, the controls are the same:

\begin{itemize}

	\item \textbf{WASD} to move North, East, South and West respectively.

	\item \textbf{Mouse left-click} to fire a bullet.

	\item \textbf{Ctrl+'+'} and \textbf{Ctrl+'-'} to zoom in and out.

	\item \textbf{ESC} to escape game mode (go back).

\end{itemize}

\subsection{Main menu}

On startup, users are greeted by a \texttt{Loading...} message, briefly followed by the main screen.

\begin{figure}[H] \centering

	\includegraphics[scale=0.45]{main_menu}

	\caption{Main menu}

\end{figure}

Using the mouse movement and clicks, the user can select one of the avaliable options:

\begin{itemize}

	\item \textbf{Single player}: Go to single player selection menu, to select one of the single player game modes.

	\item \textbf{Multiplayer}: Go to multiplayer mode, allowing to select more options.

	\item \textbf{Chat}: Exchange text messages with another connected computer.

	\item \textbf{Exit}: Exit the game

\end{itemize}

The user can also exit the game by presing \textbf{ESC}.

\pagebreak

\subsection{Single player}

Upon entering into single player mode, the user is presented with a menu from which he can choose one of the options. \par

\begin{figure}[H] \centering

	\includegraphics[scale=0.45]{singleplayer01}

	\caption{Single player menu}

\end{figure}

\begin{itemize}

	\item \textbf{Campaign}: campaign mode; kill all autonomous opponents.

	\item \textbf{Zombies}: zombies mode; kill as many zombies and survive as much time as possible.

	\item \textbf{Zombies Ranking}: Scoreboard with the highest scores obtained on zombies mode.

	\item \textbf{Back}: go back to main menu.

\end{itemize}

The user can also go back to main menu by pressing \textbf{ESC}.

\pagebreak

\subsubsection{Campaign}

In campaign mode the goal is to kill all the opponents in the map as fast as possible, while sustaining as little damage as possible.

\begin{figure}[H] \centering

	\includegraphics[scale=0.45]{campaign01}

	\caption{Campaign mode}

\end{figure}

\pagebreak

\subsubsection{Zombies}

In zombie mode the goal is to kill as many zombies and survive as much time as possible. Zombies slowly follow the player and attack the player when in short range.\par

Once the player kills a zombie, a new zombie spawns in a random part of the map, with more life than all previous zombies.

\begin{figure}[H] \centering

	\includegraphics[scale=0.45]{zombies01}

	\caption{Zombies mode}

\end{figure}

\pagebreak

\subsection{Multiplayer}

In multiplayer mode, \textcolor{red}{INCOMPLETE}.

\pagebreak

\subsection{Chat}

This chat tool was initially designed as a simple, text mode, test communication between different machines. We have however decided to include it as a functionality in the project for a number of reasons:

\begin{enumerate}

	\item It was easy to develop the graphical part and integrate in the project.

	\item Having a friendly functionality that uses the communication modules allows for faster debugging; in case the computers are not properly connected, or if during development something stops working we can immediately check if the communication modules also stopped working.

	\item It served as a minimal insurance that our project would integrate the communication modules, in case we could not implement multiplayer mode.

	\item It is a useful feature.

\end{enumerate}

\begin{figure}[H] \centering

	\includegraphics[scale=0.45]{chat01}

	\caption{Chat environment}

\end{figure}

The chat can be used for exchanging messages of up to 75 characters directly writable with the keyboard. The character limit was imposed to prevent strings from rendering as wider than the input box, and the fact they should be directly writable with the keyboard simplifies the process of capturing scancodes, having as downside not allowing to write characters that require more than one key press (like exclamation or question marks in a Portuguese keyboard). \par

\begin{figure}[H] \centering

	\begin{subfigure}[b]{0.48\linewidth}

		\includegraphics[width=\linewidth]{chat02_01}

		\caption{Computer 1 chat}

	\end{subfigure}

	\begin{subfigure}[b]{0.48\linewidth}

		\includegraphics[width=\linewidth]{chat02_02}

		\caption{Computer 2 chat}

	\end{subfigure}

	\caption{Two users interacting via chat}

\end{figure}

The user can exit the chat mode by pressing \textbf{ESC}.

\section{Project status}

All functionalities previously presented were fully implemented, with the exception of:

\begin{itemize}

	\item \textbf{Campaign}: autonomous opponents were supposed to follow a pre-programmed path and shoot on sight at the player. Currently, they don't do either of those.

	\item \textbf{Multiplayer}: still working on it.

\end{itemize}

The I/O devices used in the project are presented in the following table.

\begin{center} \begin{tabular}{c || l | c}

	\textbf{Device} & \textbf{What for}                                        & Method \\ \hline

	Timer           & Frame rate, time since beginning of game                 & Interrupts \\

	Keyboard        & Player movement, writing chat messages                   & Interrupts \\

	Mouse           & Player orientation, shooting, selecting options in menus & Interrupts \\

	Video card      & In-game drawing, menus                                   & None \\

	RTC             & Scoreboards                                              & Polling \\

	Serial port     & Chat communication, multiplayer modes                    & Interrupts

\end{tabular} \end{center}

To manage all interrupt subscriptions, the general function \texttt{unsubscribe\_interrupt} was implemented and used.

\subsection{Timer}

Timer 0 is used to generate periodic interrupts at a rate of 60Hz, essentially controlling a large part of what the program does.\par

Timer interrupts regulate screen refreshing, which happens at a rate of 60Hz. In all game modes, timer interrupts serve not only the purpose of refreshing the screen, but also to process all the game data: collisions, movement, path-finding algorithms, etc. \par

To manage timer interrupt subscriptions, functions \texttt{subscribe\_timer\_interrupt}, \texttt{timer\_int\_handler} and \texttt{timer\_get\_no\_interrupts} were implemented and used.

\subsection{Keyboard}

The keyboard was configured to issue interrupts on key presses and releases. \par

The keyboard is used to control some menus (namely using \textbf{ESC}), to input text in the chat, and to control player movement in the game and zoom in/out options.\par

To manage keyboard interrupt subscription, function \texttt{subscribe\_kbc\_interrupt} was implemented. To manage keyboard interrupts, functions \texttt{kbc\_ih}, \texttt{keyboard\_get\_done}, \texttt{keyboard\_get\_scancode} and \linebreak \texttt{update\_key\_presses} were implemented and used. 

\subsection{Mouse}

The mouse was configured to issue interrupts on movement and button presses. \par

The mouse is used to control all menus (position and buttons), as well as allowing the player to aim at the opponents (position) and shoot bullets (buttons). \par

To manage mouse interrupt subscription, function \texttt{subscribe\_mouse\_interrupt} was implemented. To manage mouse interrupts, functions \texttt{mouse\_ih}, \texttt{mouse\_parse\_packet} and \texttt{update\_mouse}, among others, were implemented.

\subsection{Video card}

The video card was configured to work in graphic mode with direct color encoding, with resolution 1024x768 pixels and 8 bits for each color component Red, Green and Blue, yielding a total of approximately 16.8 million colors. \par

Simple buffering was used to eliminate flickering. All graphics are first drawn to the scree buffer, and only after all graphical operations (that is, at the end of the processing of the timer interrupt) is the buffer information copied to the VRAM. \par

The modules \texttt{rectangle\_t} and \texttt{menu\_t} were developed for displaying simple shapes and menus. The modules \texttt{basic\_sprite\_t} and \texttt{sprite\_t} were developed for displaying moving sprites, allowing for rotation around the "center" of the image, as well as scaling and movement. \par

The modules \texttt{font\_t} and \texttt{text\_t} were developed to allow for dynamic rendering of text, using as default (and, for now, sole) font Consolas. The only type of supported fonts are bitmap fonts. \par

Configuration of the UART was made using the functions \texttt{graph\_init} and \texttt{graph\_cleanup} developed during the project. Drawing to the buffer is made primarily through the functions \texttt{graph\_get\_XRes}, \linebreak \texttt{graph\_get\_YRes}, \texttt{graph\_set\_pixel}, \texttt{graph\_clear\_screen} and \texttt{graph\_draw}.\par

Basic sprites are constructed from small XPM files, or loaded at runtime from XPM2 files. A XPM2 file is a XPM file stripped from all the C syntax, leaving only the strings. This format is easier to load at runtime than XPM. A XPM file can be easily converted to a XPM2 file using the function \texttt{xpm\_save\_as\_xpm2}. All XPM arrays of strings are loaded to bitmaps using the function \texttt{xpm\_load} provided by the LCF.

\subsection{Real-Time Clock (RTC)}

The RTC was configured to issue interrupts and if the interrupt source is an Update Event, in which the bit 4 of Register C will be set, then the values of time will be updated by reading their registers.\par

The date isn't updated unless asked, this is, on the interrupt notification the date isn't updated, and the reading process is different from the time. If it's asked to read the date then the date registers will be read two consecutive times, and will repeat the process if the date values of consecutive readings isn't equal, this ensures the values read are correct in case any update occurs. These updates aren't as frequent as the time values so there's no need to update it every second.\par

To manage RTC interrupt subscription, function \texttt{subscribe\_rtc\_interrupt} was implemented. In order to enable the Update Event Interrupts, the function \texttt{rtc\_set\_updates\_int} that enables or disables the Update Events interrupts by writing to bit 4 of register B. To manage mouse interrupts, function \texttt{rtc\_ih} was implemented, that verifies if the source if from an Update Event by reading register C and verifying bit 4 and if so updates the time values (seconds, minutes and hours). To ease the process of reading and writing values to the RTC, functions \texttt{rtc\_read\_register} and \texttt{rtc\_write\_register} were implemented as general functions, while having specific functions for reading the date and time values, such as \texttt{rtc\_read\_min} among others, that use the general functions cited above.\par

The RTC is used to obtain date and time for the scoreboards on the game-modes.

\subsection{Serial port}

The UART was configured to issue interrupts for Receiver Ready and Transmitter Empty. Communication is processed with the same parameters at both ends, at a bit-rate of 115200bps, 8 bits per char, 2 stop bits. UART FIFOs are not used. The protocols that were developed will be discussed in section \ref{sec:details}. \par

In multiplayer mode, data is transferred from host to remote at a frequency of 60Hz, with each message having at least 24 bytes. Data transference from remote to host is made whenever needed, with each message having on average 9 bytes.

\pagebreak

\section{Code organization/structure}

\subsection{\texttt{libs}}

Collection of useful classes and functions. This module was developed with the goal of being as general and independent from \texttt{proj} as possible, although there are rare occasions where sub-modules of \texttt{libs} include sub-modules of \texttt{proj}.

\subsubsection{\texttt{classes}}

Provides classes \texttt{list\_t} and \texttt{queue\_t}. These classes achieve generality by storing pointers to \texttt{void}, which have as major disadvantage requiring the use of \texttt{free}. \par

\textcolor{red}{CONTINUE LIBS MODULES}

\subsection{\texttt{proj}}

\textcolor{red}{MAKE PROJ MODULES}

\section{Implementation details} \label{sec:details}

\textcolor{red}{WRITE IMPLEMENTATION DETAILS}

\subsection{XPM and XPM2}

\textcolor{red}{WRITE STUFF}

\subsection{Communication protocols}

\textcolor{red}{WRITE IMPLEMENTATION DETAILS}

\section{Conclusions}

\textcolor{red}{WRITE CONCLUSION}

\end{document}