Tłumaczenie dokumentacji RobotGame - początek.

docs/index.rst

@@ -21,6 +21,7 @@ Spis treści:
     cppqt/index
     web/index
     python/index
+    rg/index
     galerie/index
 
 Indeks

docs/rg/game_rules.rst

@@ -0,0 +1,59 @@
+Zasady gry
+################
+
+W "Grze robotów" piszesz programy kierujące walczącymi dla Ciebie robotami.
+Planszą gry jest siatka o wymiarach 19x19 pól. Celem gry jest
+umieszczenie na niej jak największej ilości robotów w ciągu 100 rund
+rozgrywki.
+
+.. figure:: img/rules1.png
+
+Czarne kwadraty (pola) oznaczają pola, na które nie ma wstępu. Ich układ
+tworzy więc kolistą arenę, na której mogą walczyć roboty.
+
+Zielone kwadraty oznaczają punkty wejścia do gry robotów.
+Co 10 rund po 5 robotów każdego gracza rozpoczyna walkę w losowych punktach wejścia
+(ang. *spawn points*). Roboty z poprzednich tur pozostające w tych punktach giną.
+
+Każdy robot rozpoczyna grę z 50 punktami życia HP (ang. *health points*).
+
+Roboty mogą działać (przemieszczać się, atakować itd.) na przyległych
+kwdratach w pionie (góra, dół) i w poziomie (lewo, prawo).
+
+.. figure:: img/rules2.png
+
+W każdej rundzie możliwe są następujące działania robota:
+
+* Przemieszczenie się na przyległy kwadrat. Jeżeli znajduje się tam już robot
+  lub inny robot robot próbuje zająć to samo miejsce, obydwa tracą 5 punktów HP
+  z powodu kolizji, a ruch(y) nie dochodzi(ą) do skutku. Jeżeli jednak robot
+  chce przejść na pole zajęte przez innego, ale temu drugiemu udaje się
+  opuścić zajmowane pole, ruch jest udany.
+
+  Minimum cztery roboty w kwadracie, przemieszczające się zgodnie ze wskazówkami
+  zegara, będą mogły się poruszać, podobnie dowolna ilość robotów w kole.
+  (Roboty nie mogą bezpośrednio zamieniać się miejscami!)
+
+* Atak na przyległy kwadrat. Jeżeli w atakowanym kwadracie znajdzie się robot
+  pod koniec rundy, np. robot pozostał w miejscu lub przeszedł na nie,
+  robot ten traci od 8 do 10 punktów HP w następstwie uszkodzeń.
+
+* Samobójstwo – robot ginie pod koniec rundy, oddając 15 punktów HP dowolnemu
+  robotowi obok.
+
+* Obrona – robot pozostaje w miejscu, tracąc połowę punktów HP wskutek ataku
+  lub samobójstwa, ale nie odnosząc uszkodzeń z powodu kolizji.
+
+W grze nie można uszkodzić własnych robotów. Kolizje, ataki i samobójstwa
+oddziałują tylko na przeciwnika.
+
+Wygrawa gracz, który po 100 rundach ma największą liczbę robotów na planszy.
+
+Zadaniem gracza jest zakodować sztuczną inteligencję (ang. AI – *artificial itelligance*),
+której będą używały wszystkie roboty. Aby wygrać, roboty gracza muszą ze sobą współpracować,
+np. żeby otoczyć przeciwnika.
+
+.. note::
+
+    Niniejsza dokumentacja jest nieautoryzowanym tłumaczeniem oficjalnej dokumentacji
+    dostępnej na stonie `RobotGame <https://robotgame.net>`_.

docs/rg/getting_started.rst

@@ -0,0 +1,133 @@
+Rozpoczynamy
+##############
+
+.. contents:: Spis treści
+    :backlinks: none
+
+Tworzenie robota
+*****************
+
+Podstawowa struktura klasy reprezentującej każdego robota jest następująca:
+
+.. code-block:: python
+
+    class Robot:
+    def act(self, game):
+        return [<some action>, <params>]
+
+Na początku gry powstaje jedna instanacja twojej klasy ``Robot``. Oznacza to,
+że właściwości klasy oraz globalne zmienne modułu są współdzielone między
+wywołaniami. W każdej rundzie system wywołuje metodę ``act`` tej instancji
+dla każdego robota, aby określić jego działanie. (Uwaga: na początku przeczytaj
+reguły.)
+
+Metoda ``act`` musi zwrócić jedną z następujących odpowiedzi:
+
+.. code-block:: python
+
+    ['move', (x, y)]
+    ['attack', (x, y)]
+    ['guard']
+    ['suicide']
+
+Jeżeli metoda ``act`` zwróci wyjątek lub błędne polecenie, robot pozostaje
+w obronie, ale jeżeli powtórzy się to zbyt wiele razy, zostaniesz zmuszony
+do kapitulacji. Szczegóły omówiono w dziale `Zabezbieczenia`_.
+
+Odczytywanie właściwości robota
+********************************
+
+Każdy robot, przy użyciu wskaźnika ``self``, udostępnia następujące
+właściwości:
+
+* ``location`` – położenie robota w formie tupli (x, y);
+* ``hp`` – punkty zdrowia wyrażone liczbą całkowitą
+* ``player_id`` – identyfikator gracza, do którego należy robot
+  (czyli oznaczenie "drużyny")
+* ``robot_id`` – unikalny identyfikator robota, ale tylko w obrębie
+  "drużyny"
+
+Dla przykładu: kod ``self.hp`` – zwróci aktualny stan zdrowia robota.
+
+W każdej rundzie system wywołując metodę ``act`` udostępnia jej stan gry
+w następującej strukturze ``game``:
+
+.. code-block:: python
+
+    {
+        # słownik wszystkich robotów na polach wyznaczonych
+        # przez {location: robot}
+        'robots': {
+            (x1, y1): {
+                'location': (x1, y1),
+                'hp': hp,
+                'player_id': player_id,
+
+                # jeżeli robot jest w twojej drużynie
+                'robot_id': robot_id
+            },
+
+            # ...i pozostałe roboty
+        },
+
+        # ilość odbytych rund (wartość początkowa 0)
+        'turn': turn
+    }
+
+Wszystkie roboty w strukturze ``game['robots']`` są instancjami specjalnego
+słownika udostępniającego ich właściwości, co przyśpiesza kodowanie.
+Tak więc następujące konstrukcje są tożsame:
+
+.. code-block:: python
+
+    game['robots'][location]['hp']
+    game['robots'][location].hp
+    game.robots[location].hp
+
+Poniżej zwięzły przykład drukujący położenie wszystkich robotów z danej drużyny:
+
+.. code-block:: python
+
+    class Robot:
+        def act(self, game):
+            for loc, robot in game.robots.items():
+                if robot.player_id == self.player_id:
+                    print loc
+
+Przykładowy robot
+*****************
+
+Poniżej mamy kod prostego robota, który można potraktować jako punkt wyjścia.
+Robot, jeżeli znajdzie wokół siebie przeciwnka, atakuje go, w przeciwnym
+razie przemieszcza się do środka planszy (``rg.CENTER_POINT``).
+
+.. code-block:: python
+
+    import rg
+
+    class Robot:
+        def act(self, game):
+            # if we're in the center, stay put
+            if self.location == rg.CENTER_POINT:
+                return ['guard']
+
+            # if there are enemies around, attack them
+            for loc, bot in game.robots.iteritems():
+                if bot.player_id != self.player_id:
+                    if rg.dist(loc, self.location) <= 1:
+                        return ['attack', loc]
+
+            # move toward the center
+            return ['move', rg.toward(self.location, rg.CENTER_POINT)]
+
+Użyliśmy, jak widać modułu ``rg``, który zostanie omówiony dalej.
+
+.. note::
+
+    Podczas gry tworzona jest tylko jedna instancja robota, w której można
+    zapisywać trwałe dane.
+
+.. note::
+
+    Niniejsza dokumentacja jest nieautoryzowanym tłumaczeniem oficjalnej dokumentacji
+    dostępnej na stonie `RobotGame <https://robotgame.net>`_.

docs/rg/index.rst

@@ -0,0 +1,20 @@
+Robot Game
+##########################
+
+Robot Game to gra, w której programy walczą ze sobą.
+Serwis powstał w oparciu o projekt `RobotGame <https://robotgame.net>`_.
+Zaprogramuj swojego robota w Pythonie i zmierz się z innymi graczami
+w bitwach towarzyskich. Nasz serwer sam przeprowadzi rozgrywki rankingowe.
+Poznaj zasady:
+
+.. toctree::
+    :maxdepth: 2
+
+    game_rules.rst
+    getting_started.rst
+    library_documentation.rst
+
+.. note::
+
+    Niniejsza dokumentacja jest nieautoryzowanym tłumaczeniem oficjalnej dokumentacji
+    dostępnej na stonie `RobotGame <https://robotgame.net>`_.

docs/rg/library_documentation.rst

@@ -0,0 +1,36 @@
+Dokumentacja modułu
+####################
+
+*Gra robotów* udostępnia bibliotekę ułatwiającą programowanie. Zawarta jest
+w module ``rg``, który importujemy na początku pliku instrukcją ``import rg``.
+
+.. note::
+
+    Położenie robota reprezentowane jest przez tuplę (x, y)
+
+.. raw:: html
+
+    <hr />
+
+Metoda **rg.dist(loc1, loc2)**
+*******************************
+
+Zwraca wyliczoną odległość między dwoma położeniami.
+
+.. raw:: html
+
+    <hr />
+
+Metoda **rg.dist(loc1, loc2)**
+*******************************
+
+[...]
+
+.. raw:: html
+
+    <hr />
+
+.. note::
+
+    Niniejsza dokumentacja jest nieautoryzowanym tłumaczeniem oficjalnej dokumentacji
+    dostępnej na stonie `RobotGame <https://robotgame.net>`_.