Net Board/Z pohledu programátora

Z JKwiki

Obsah 1 Architektura 2 Komunikační protokol 2.1 Adresy jednotlivých částí 2.2 Textová reprezentace zpráv 3 Průběh komunikace 3.1 Navazování spojení 3.2 Výběr a načtení hry 3.3 Zahájení hry 3.4 Průběh a zakončení hry 4 Backendy 4.1 Spouštění backendů 4.1.1 Herní backend 4.1.2 Síťový backend 4.2 Úpravy zpráv síťovým backendem 5 Konfigurační dialogy 5.1 Dostupné položky 5.2 Příklad 5.2.1 Zpráva 5.2.2 Výsledek 6 Přehled zpráv

Architektura

Hrací deska sama o sobě je pouze grafické rozhraní, které se stará o předávání zpráv mezi backendy, načítání konfigurace, udržování seznamu hráčů a interakci s uživatelem. Pro komunikaci i pro řízení průběhu hry jsou spouštěny backendy, které s deskou komunikují přes standardní vstup a výstup.

Na obrázku níže je nakresleno vnitřní uspořádání hrací desky. Jednotlivé části mezi sebou komunikují prostřednictvím zpráv, které jsou všechny poslány routeru a ten je předá cílové části. Zprávy mají tvar prostého seznamu hodnot, kde první hodnota je řetězec obsahující příkaz. Vše nalevo od svislé přerušované zelené čáry je jeden proces, který obsluhuje GUI.

Komunikační protokol

Zprávy předávané mezi jednotlivými částmi mají tvar seznamu hodnot. Rozlišují se dva datové typy: celočíselný integer a string. Každá zpráva uvnitř hrací desky má ještě adresu odesílatele a příjemce. Adresa je jeden znak. První hodnota v seznamu je příkaz (řetězec). První písmeno příkazu je shodné s adresou příjemce nebo části v příjemci.

Veškerá kominukace probíhá v kódování UTF-8.

Adresy jednotlivých částí

• 'B' – Board (hrací deska)
• 'C' – Chat
• 'G' – Game backend (herní backend)
• 'N' – Network backend (síťový backend)
• 'O' – Options (konfigurace)
• 'P' – Player List (seznam hráčů)
• 'S' – Session (řízení průběhu hry)
• 'F' – Network Profiles (seznam síťových profilů) – jen pro aktualizaci okna

Textová reprezentace zpráv

Zprávy jsou backendům posílány jako prostý text. Každá zpráva je ohraničena kulatými závorkami, položky jsou odděleny mezerou. Bílé znaky okolo závorek jsou ignorovány. Číselné hodnoty jsou psány jako obvykle, řetězce jsou v uvozovkách. Zpětné lomítko v řetězci říká, že následující znak má být brán jako součást řeťězce. Podobnost se s-expy není náhodná ;)

Příklad:

( "Spt" "text" 12 "text s \" uvozovkou" "text s \\ lomítkem" )

O překlad zpráv do/z textové reprezentace se starají funkce deklarované v souboru gui/src/message.h.

Průběh komunikace

Navazování spojení

O navazování spojení se stará síťový backend. Od hrací desky obdrží pouze adresu, kam se má připojit. hrací deska této adrese nijak nerozumí, je to pro ni jen nějaký řetězec.

Po úspěšném navázání spojení pošle síťový backend hrací desce zprávu ("Son") na znamení, že je připojen.

Při připojení dalšího hráče pošle síťový backend zprávu ("Pj" "adresa hráče") následovanou případnými informacemi o hráči. Toto pošle i těsně po připojení o již připojených hráčích. Po odpojení hráče posílá obdobnou zprávu ("Pp" "adresa hráče").

Výběr a načtení hry

Jakmile jsou připojeni všichni hráči, jeden z nich vybere hru, kterou budou hrát. Vybranou hru pošle hrací deska síťovému backendu ve zprávě ("Spg" "jméno hry"). Síťový backend ji rozešle ostatním hráčům.

Jakmile mají ostatní hráči vybranou hru načtenou, odpoví zprávou ("Spa"). V případě, že některý hráč nemůže načíst zvolenou hru, odmítne zprávou ("Spr"). Toto se týká i hráče, který hru vybral.

Zahájení hry

Před vlastním zahájením hry si každý hráč musí vybrat svou roli (barvu, stranu stolu,...). Vybranou roli okamžitě hrací deska odesílá ostatním hráčům. Roli může vybrat vícekrát, platí vždy poslední zvolená.

Poté každý hráč požádá herní backend o svolení k zahájení hře zprávou ("Sgc"). Herní backend zkontroluje obsazení herních rolí a povolí zahájení zprávou ("Sga") nebo zamítne zprávou ("Sgr"). Pokud herní backend povolí zahájení hry, hrací deska odešle zprávu ("Spb") všem ostatním hráčům.

Jakmile všichni hráči rozešlou zprávu ("Spb"), považuje se hra za zahájenou a první hráč může hrát.

Průběh a zakončení hry

V průběhu hry posílá hrací deska akce uživatele hernímu backendu, ten na ně reaguje jednak příkazy pro vykreslovací část a jednak posíláním tahů ostatním hráčům ve zprávách ("Spt" "čitelná reprezentace tahu" data). Herní backendy si sami řídí střídání hráčů.

Přihlížející hráči nijak nezasahují do hry, jen interpretují jednotlivé tahy a zobrazují je.

Po skončení hry se herní backend prostě ukončí.

Backendy

Spouštění backendů

Backendy komunikují přes standardní vstup a výstup. Standardní chybový výstup je přesměrován do logů. Data jsou posílána jako prostý text.

Herní backend

Je spuštěn bez parametrů.

Síťový backend

Je spuštěn s parametry:

-P ID

ID síťového profilu. Backend musí veškerou svojí konfiguraci ukládat do [ network :: ID :: * ]

-A adresa

Adresa, kam se má síťový backend připojit.

-v -d -q

Verbose, Debug, Quiet. Nastavení úrovně ladicích výpisů. Je uveden jeden z těchto nebo žádný (= normální úroveň).

Úpravy zpráv síťovým backendem

Síťový backend připouje ke všem zprávám přijatým ze sítě, jejiž příkaz začíná na 'Sp', adresu hráče, který ji poslal a příznak, zda odesílatel je stejný jako příjemce – doručení každé zprávy potvrdí jejím vrácením s touto úpravou.

Konfigurační dialogy

Pohodlné úpravy konfigurace lze provádět pomocí konfiguračních dialogů. Tyto dialogy jsou generovány ze zpráv Odo. Jakmile je doručena zpráva Odo, hrací deska zobrazí dialog s položkami definovanými v této zprávě, která má následující tvar:

("Odo" "kategorie" "modul" "titulek_okna" položky... )

Jednotlivé položky se mohou skládat z více částí, v některých případech může být jejich počet libovolný.

Dostupné položky

"[Název"

Nadpis/rámeček (GtkFrame). Všechny následující položky jsou zahrnuty pod tímto nadpisem až do dalšího nadpisu. Je vhodné použít alespoň jeden, aby byly správně mezery okolo widgetů ve výsledném dialogu.

"$Název" "option"

Textová položka (GtkEntry)

"*Název" "option"

Textová položka k zadání hesla (GtkEntry), kde místo textu jsou hvězdičky.

"#Název" "option" min max

Numerická (celočíselná) položka (GtkSpinButton).

"?Název" "option"

Zaškrtávací položka (GtkCheckBox). V konfiguraci ukládá/načítá celočíselnou hodnotu 0 nebo 1.

"%Název" "option" "hodnota" "hodnota" ... ""

Výběr jedné hodnoty z mnoha (GtkComboBox). Předvolené hodnoty následují za option a jsou zakončeny prázdým řetězcem.

"=Text"

Prostý text (GtkLabel). Určen především pro umístění krátké nápovědy a doplňujících informací. Pro formátování textu je k dispozici Pango Text Attribute Markup Language. (od rev. 75)

Příklad

Poznámka: Zalomení řádků v dlouhých řetězcích bylo před odesíláním zprávy odstraněno.

Zpráva

( "Odo" "network" "test-dialog" "Testovací dialog"
	"[Command line"
		"=command arg1 arg2 ..."
	"[Frame 1"
		"\$_Text entry 1"	"textentry"
		"\$_Text entry 2"	"textentry2"
		"*_Password entry"	"passwordentry"
		"?_Check button"	"checkbutton"
	"[Frame 2"
		"%Combo _Box"		"combobox"
					"jedna" "dva" "tři" "čtyři" ""
		"#_Spin button"		"spinbutton" -1000 1000
	"[Text Frame"
		"=Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed
		  diam nonummy nibh euismod <b>tincidunt</b> ut laoreet
		  dolore magna aliquam erat volutpat. Ut <i>wisi enim</i>
		  ad minim veniam, <u>quis nostrud</u> exerci tation
		  ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat."
		"=<span foreground='blue' weight='bold' size='x-large'>Blue text
		  is <i>cool !</i></span>"
)

Výsledek

Přehled zpráv

Přehled zpráv je generovaný z komentářů ve zdrojových kódech do podoby manuálové stránky – PDF verze.