%\chapter{Obsah CD}
%\chapter{Manual}
%\chapter{Konfigrační soubor}
%\chapter{RelaxNG Schéma konfiguračního soboru}
%\chapter{Plakat}




\chapter{Struktura souboru Wherigo Cartridge (GWC)} \label{app:gwc}

Popis souboru GWC souboru, převzato, přeloženo a doplněno z wiki aplikace WherUGo \cite{gwc}. Datové typy popisuje tabulka č. \ref{tab:types}

\begin{itemize}
	\item \verb|@0000|: Identifikace souboru (Magic number):
		\begin{verbatim}
BYTE      0x02
BYTE      0x0a
BYTE      "CART", 0x00
\end{verbatim}
		
	\item \verb|@0007|: Počet objektů v souboru:
		\begin{verbatim}
USHORT    number_of_objects
\end{verbatim}
  
	\item \verb|@0009|: Přesně number\_of\_objects referencí na jednotlivé objekty v cartridge:
		\begin{verbatim}
repeat <number_of_objects> times {
    USHORT	object_id   ; Unikátní ID pro každý objekt
    LONG	address     ; adresa v souboru
}
\end{verbatim}
	
	
	\item \verb|@xxxx|: Hlavička cartridge
		\begin{verbatim}
LONG  header_length     ; Délka hlavičky (následujícího bloku):
struct {
    DOUBLE  Latitude    ; N+/S-
    DOUBLE  Longitude   ; E+/W-
    DOUBLE  Altitude    ; Nadmořská výška
    LONG    unknown1
    LONG    unknown2
    ; media-ID of icon and splashscreen:
    SHORT  ID_of_splashscreen     ; -1 = bez úvodní obrazovky
    SHORT  ID_of_small_icon	      ; -1 = bez ikony
    ASCIIZ  type_of_cartridge     ; Typ: např "Wherigo cache"
    ASCIIZ  PlayerName            ; Jméno hráče
    LONG    unknown6
    LONG    unknown7
    ASCIIZ  CartridgeName         ; Jméno cartridge
    ASCIIZ  CartridgeGUID
    ASCIIZ  CartridgeDescription  ; Popis cartridge
    ASCIIZ  StartingLocationDescription ; Popis výchozího bodu
    ASCIIZ  Version               ; Verze cartridge
    ASCIIZ  Author
    ASCIIZ  Company
    ASCIIZ  RecommendedDevice     ; Doporučené zařízení
    LONG    unknown8
    ASCIIZ  CompletionCode
} header
\end{verbatim}

	\item \verb|@xxxx + header_length + 4|: Zde by měl být první objekt, ale jejich offsety jsou definovány seznamu referencí

	\item \verb|@address_of_FIRST_object| objekt ID = 0 -- vždy bytekód LUA
       \begin{verbatim}
LONG          length
BYTE[length]  content_of_object		; LUA bytekód
\end{verbatim}
       
       
    \item \verb|@address_of_ALL_OTHER_objects| objekt ID $>$ 0
		\begin{verbatim}
BYTE  valid_object
if (valid_object == 0) {
    ; Objekt byl smazán a neexistuje v cartridge
} else {
    LONG  object_type  ; Typ objektu: 1=bmp, 2=png, 3=jpg, 4=gif,
                       ; 17=wav, 18=mp3, 19=fdl, ostatní neznámé
    LONG  length
    BYTE[length]  content_of_object ; objekt
}
\end{verbatim}
\end{itemize}

\begin{table}[h!]
	\centering
	\begin{tabular}{l l}
		 Datový typ & popis \\ \hline
		 BYTE 		& unsigned char (1 byte) \\
		 SHORT 		& signed short (2 bytes) \\
		 USHORT 	& unsigned short (2 bytes) \\
		 LONG 		& signed long (4 bytes) \\
		 ULONG 		& unsigned long (4 bytes) \\
		 DOUBLE 	& double-precision floating point number (8 bytes) \\
		 ASCIIZ 	& zero-terminated string ("hello world!", 0x00) \\
	\end{tabular}
	\caption{Datové typy použité pro popis struktury souborů} \label{tab:types}
\end{table}







\chapter{Struktura souboru Wherigo Savegame (GWS)}  \label{app:gws}

Popis struktury souboru s uloženou hrou.

\begin{itemize}
	
	\item \verb|@0000|: Identifikace souboru (Magic number):
		\begin{verbatim}
BYTE    0x02
BYTE    0x0a
BYTE    "SAVE", 0x00
\end{verbatim}
		
	\item \verb|@0007|: Délka hlavičky v bytech
		\begin{verbatim}
LONG    header_length
\end{verbatim}
  
	\item \verb|@000A|: Jméno cartridge
		\begin{verbatim}
struct {
    ASCIIZ    CartridgeName
    BYTE[8]   CartridgeDateOfCreation
    ASCIIZ    PlayerName
    ASCIIZ    DeviceName
    ASCIIZ    DeviceID      ; S/N zařízení
    BYTE[8]   DateOfSaving
    ASCIIZ    NameOfSave    ; "UI Initialized sync"
    DOUBLE    Latitude
    DOUBLE    Longitude
    DOUBLE    Altitude
} header
\end{verbatim}
	
	\item \verb|@000A + header_length|: Počet objektů obsažených v souboru
        \begin{verbatim}
LONG    number of ZObjects
\end{verbatim}
	
    \item \verb|@000A + header_length + 4|: Seznam objektů
        \begin{verbatim}
repeat <number of ZObjects> times {
    LONG            length
    BYTE[length]    ObjectName
}
\end{verbatim}
    
    \item \verb|@xxxx|: Tabulka objektu Player
        \begin{verbatim}
LONG                length
BYTE[length]        ZCharacter (ObjectName)
OBJECT              Player
\end{verbatim}
    
	\item \verb|@xxxx|: Přesně number of ZObjects tabulek s ostatními objekty z tabulky AllZObjects
		\begin{verbatim}
repeat <number of ZObjects> times {
    LONG            length
    BYTE[length]    ObjectName
    TABLE           Object
}
\end{verbatim}
\end{itemize}

Použité datové typy z jsou vysvětleny v tabulkách č. \ref{tab:types} a  \ref{tab:data_types}.

\begin{table}[h!]
	\centering
	\begin{tabular}{l l l}
		 Datový typ & binární formát 					& popis \\ \hline
		 BOOL 		& 0x01 + BYTE 						& 00 = false, 01 = true \\
		 NUMBER 	& 0x02 + DOUBLE 					& \\
		 STRING 	& 0x03 + LONG(l) + BYTE[l]			& Řetězec bez ukončovací nuly\\
		 FUNCTION 	& 0x04 + LONG(l) + BYTE[l]			& lua\_dump() funkce\\
		 TABLE		& 0x05 + (KEY + VALUE)* + 0x06		& Formát dvojic: klíč, hodnota \\
		 REFERENCE	& 0x07 + USHORT						& Ref. na ZObjekt pomocí ObjId \\
		 OBJECT		& 0x08+LONG(l)+BYTE[l]+TABLE		& Jméno objektu \\
	\end{tabular}
	\caption{Datové typy použité pro popis struktury souboru} \label{tab:data_types}
\end{table}




\chapter{Knihovna Wherigo} \label{app:library}

Knihovna je uložena ve jmenném prostoru Wherigo. Zde je umístěn jen stručný seznam funkcí, objektů a konstant. Jejich detailní popis je umístěn na přiloženém CD.

\subsection{Objekty}

\begin{description}
	\item[Bearing(value)] Objekt reprezentující azimut
	\item[Distance(value, units)] Objekt reprezentující vzdálenost v metrech, obsahuje možnost převodu na jiné jednotky
	\item[ZCommand(table)] Akce objektu
	\item[ZReciprocalCommand] Obousměrná akce objektu, použitá pro ukládané hry, málo využívané
	\item[ZonePoint(lat, lon, alt)] Bod se zadanými geografickými souřadnicemi a nadmořskou výš\-kou
	\item[ZObject] Bázový objekt pro následující objekty
	\item[Zone] Zóna složená z alespoň tří bodů ZonePoint
	\item[ZCartridge] Objekt cartridge. Měl by existovat jediný v celém prostředí
	\item[ZMedia] Objekt reprezentující média uložená v cartridge jako další objekty
	\item[ZItem] Objekty, které může hráč držet nebo vidět
	\item[ZTask] Objekt úkolu
	\item[ZTimer] Objekt časovače -- vyžaduje interakci s C++
	\item[ZInput] Objekt pro vstup uživatele
	\item[ZCharacter] Objekt postavy nebo hráče
\end{description}

\subsection{Funkce}

\begin{description}
	\item[MessageBox(table)] Zobrazení zprávy uživateli
	\item[Dialog(table)] Zobrazení série zpráv uživateli
	\item[PlayAudio(media)] Požadavek na spuštění přehrávání audia
	\item[ShowStatusText(text)] Zobrazení stavové zprávy. Nevyužívané
	\item[VectorToZone(point, zone)] Počítá vzdálenost z bodu k nejbližšímu bodu zóny
	\item[VectorToSegment(point, p1, p2)] Počítá vzdálenost z bodu \verb|point| k segmentu zóny. Využito funkcí výše
	\item[IsPointInZone(point, zone)] Určuje, zda se bod vyskytuje v zóně
	\item[TranslatePoint(point, distance, bearing)] Posun bodu o danou vzdálenost v daném azimutu
	\item[VectorToPoint(p1, p2)] Výpočet vzdálenosti a azimutu mezi dvěma body
	\item[NoCaseEquals(s1,s2)] Porovnání řetězců bez ohledu na velikost písmen
	\item[Command(command)] Provedení příkazu -- možnosti jsou SaveClose, DriveTo, StopSound, Alert
	\item[LogMessage(table)] Záznam akce do logu cartridge
	\item[GetInput(input)] Požadavek na vstup uživatele
	\item[ShowScreen(screen, item)] Požadavek na zobrazení obrazovky
\end{description}

\subsection{Konstanty}

\paragraph{Konstanty pro funkci \texttt{ShowScreen}:}
\begin{itemize}
	\item MAINSCREEN
	\item INVENTORYSCREEN
	\item ITEMSCREEN
	\item LOCATIONSCREEN
	\item TASKSCREEN
	\item DETAILSCREEN
\end{itemize}

\paragraph{Konstanty úrovní logování pro funkci \texttt{LogMessage}:}
\begin{itemize}
	\item LOGDEBUG
	\item LOGCARTRIDGE
	\item LOGINFO
	\item LOGWARNING
	\item LOGERROR
\end{itemize}

\paragraph{Ostatní:}
\begin{description}
	\item[INVALID\_ZONEPOINT] Označení nezadaného objektu \verb|ZonePoint|
\end{description}

\subsection{Globální objekty:}

Zdroj je wiki u projektu WherigoBuilder \cite{globals}.

\begin{description}
	\item[cartridge] Objekt ZCartridge, který obsahuje aktuálně spuštěnou hru
	\item[Player] Objekt ZCharacter, který představuje hráče hrajícího hru
	\item[Wherigo] Výše popisovaná knihovna
	\item[Env] Proměnné prostředí
	\item[WIGInternal] Knihovna nativních funkcí, nevyužívaná samotnými cartridgemi
\end{description}







