# Dokumentacja techniczna

&ktuberling; oferuje oględne i odpłacające wprowadzenie do dostrajania i programowania &kde;. Program może być rozszerzany. Na przykład, bez żadnego kodowania, nowe plansze mogą być dodawane za pomocą zmiany plików graficznych. Poprzez dodanie odpowiednich plików dźwiękowych, tłumacze mogą stworzyć dźwięki w ich ojczystym języku!

Jeżeli rozszerzasz, lub dodajesz coś do gry, pomyśl o przesłaniu Twoich dodatków do programisty Eric Bischoff, w celu włączenia w kolejnych wersjach.

## Dla artystów

Rozmiar i kształt pola gry, a także liczba obiektów mogą podlegać zmianom. Można dodawać nowe plansze. Tylko dwa pliki graficzne muszą być stworzone dla każdej planszy: plansza gry i maska. Maksymalnie dozwolonych jest 8 plansz, z których obecnie używa się 3.

W programie &ktuberling; używa się sześciu typów obrazków: `potato-game.png`, `potato-mask.png`, `penguin-game.png`, `penguin-mask.png`, `aquarium-game.png` i `aquarium-mask.png`. Standardowym położeniem tych plików jest katalog `$KDEDIR/share/apps/ktuberling/pics/`.

Pierwszy typ obrazków, `*-game.png`, przechowuje planszę i obiekty, które wybiera użytkownik. Jest to grafika, którą widzi użytkownik podczas gry.

Drugi typ obrazków, `*-mask.png`, zawiera wyłącznie maski obiektów. Maski używane są do określania granic obiektów, a także, w niektórych przypadkach, dodania obiektowi pewnej przezroczystości (na przykład okulary). Obowiązkowe jest umieszczenie obiektów w tym samym położeniu zarówno w pliku planszy, jak i pliku masek.

W tym samym katalogu plik o nazwie `layout.xml`. (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`) mówi, których obrazków użyć i łączy je z pozycjami menu. Zawiera również parametry pozycji planszy, a także obiektów w polu gry i maskach. Ostatecznie deklaruje języki jako zbiory przetłumaczonych dźwięków. Stosuje się do standardowej składni XML (zobacz szczegóły na below).

Ciągle w tym samym katalogu, plik o nazwie `layout.i18n` (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`) podsumowuje teksty w `layout.xml`, które mogą być przetłumaczone:

- Pozycje menu, które pozwalają wybrać planszę i język

- Nazwy kategorii obiektów

Jeden poziom wyżej, plik o nazwie `ktuberlingui.rc` (`$KDEDIR/share/apps/ktuberling/ktuberlingui.rc`) jest kolejnym plikiem XML opisującym menu programu &ktuberling;. Powinien zawierać jeden znacznik `<action>` dla planszy i języka. Nazwa symboliczna akcji w tym pliku powinna być identyczna z nazwą symboliczną w `layout.xml`.

## Tłumaczenie

Oprócz zwyczajowego mechanizmu plików `.po` do tłumaczenia etykiet i tekstów zachęty, dźwięki również mogą zostać zlokalizowane.

Jeśli różni tłumacze mogą nagrać swój głos do pliku `.wav`, mogą go zachować do określonego przez język podkatalogu w katalogu z dźwiękami. Nazwa dźwięku jest później przypisywana do pliku `layout.xml`. Na przykład gdy docelowym językiem jest włoski, tłumacze mogą nagrać swój głos w plikach `.wav` umieszczonych w `$KDEDIR/share/apps/ktuberling/sounds/it`. Następnie mogą przydzielić dźwięk o nazwie hat do nazwy pliku `it/cappello.wav`.

W kolejnych wersjach &ktuberling; będzie używał dla dźwięków formatu OGG Vorbis rc3. Wtedy również będzie można skonwertować pliki WAV do OGG Vorbis rc3 za pomocą poniższej linii:

    $ oggenc_rc3 -o sound.ogg sound.wav

Informacja jak pracować z mechanizmami tłumaczeń w &kde; jest dostępna w The KDE Translation HOWTO.

## Dla programistów

&ktuberling; tak naprawdę nie jest trudny do rozszerzenia przez programistów.

### klasy C++

`TopLevel`

- Okno górnego poziomu i podstawowe zarządzanie programem

`PlayGround`

- Opis jednego z poziomów gry

`ToDraw`

- Opis jednego z obiektów graficznych do narysowania

`SoundFactory`

- Opis jednego z języków i jego dźwięków

`Action`

- Jedna z akcji użytkownika na stosie cofnij/ponów

### Struktura plików `.tuberling`

Plik `.tuberling` przechowuje dane niezbędne do odrysowania bulwy. Może być edytowany zwykłym edytorem tekstu.

Pierwsza linia przechowuje numer planszy.

We wszystkich pozostałych liniach znajduje się po jednym obiekcie graficznym, w kolejności używanej do ich narysowania. Każda linia zawiera pięć liczb: identyfikator obiektu i prostokąt, gdzie powinien być narysowany (lewo, góra, prawo, dół). Liczby oddzielone są spacjami.

## Struktura pliku rozmieszczenia (`layout.xml`)

Znacznik górnego poziomu jest unikalny, a jego nazwa to `<ktuberling>`. Zawiera liczne znaczniki `<playground>`, po jednym dla planszy oraz liczne `<language>`, po jednym dla języka.

Znacznik `<playground>` posiada dwa atrybuty. `gameboard` i `masks`. Atrybuty te dają nazwę plików przechowujących obrazki. `<playground>` zawiera również jeden znacznik `<menuitem>`, jeden znacznik `<editablearea>`, wiele znaczników `<category>` i `<object>`.

Znacznik `<menuitem>` opisuje identyfikator akcji pozycji menu pozwalając na wybór położenia obszaru, na którym można upuszczać obiekty, a także etykietę tej pozycji menu. Ten identyfikator akcji powinien być identyczny z tym w `ktuberlingui.rc`.

Znacznik `<editablearea>` opisuje położenie obszaru, na którym można upuszczać obiekty, a także nazwę dźwięku z nim powiązanego.

Znacznik `<category>` opisuje położenie i etykietę tekstu opisującego grupę obiektów. Na przykład, może opisywać położenie i tekst grupy kosztowności.

Znacznik `<object>` opisuje położenie (na planszy i w maskach) obiektu, jak również nazwę dźwięku z nim powiązanego.

Znacznik `<language>` posiada jeden atrybut: `code`. Zawiera on kod ustawień regionalnych danego języka. Znacznik `<language>` zawiera również jeden znacznik `<menuitem>` i wiele znaczników `<sound>`.

Znaczniki niższego poziomu nie są tu wyjaśnione, ponieważ ich znaczenie jest raczej oczywiste. Po zmianie `layout.xml` nie zapomnij odpowiednio zmodyfikować `layout.i18n` i `ktuberlingui.rc`.