# Техническое описание

&ktuberling; является прекрасным примером программирования под &kde;. Он имеет легко настраиваемую и изменяемую структуру. Например, для добавления или изменения рисунков игрового поля не потребуется написать ни строчки кода. Достаточно просто добавить или изменить существующий графический файл. Можно также перевести звуковые файлы игры, и Клубень заговорит на вашем родном языке!

Если вы внесли какие-либо изменения или дополнения в игру, вышлите их автору - Эрику Бишофу и он включит их в следующие версии.

## Дизайнерам

Существует возможность добавления новых игровых полей, а также изменения их размеров и форм. Для каждого игрового поля необходимо создать два графических файла: файл изображения поля и файл маски. В игре есть поддержка восьми игровых полей, из которых сейчас используется только три.

На данный момент в &ktuberling; используются шесть графических файлов: `potato-game.png`, `potato-mask.png`, `penguin-game.png`, `penguin-mask.png`, `aquarium-game.png` и `aquarium-mask.png`. Стандартное расположение этих файлов - в каталоге `$KDEDIR/share/apps/ktuberling/pics/`.

Первый тип файлов, `*-game.png` содержит изображения игрового поля и объектов, выбираемых пользователем. Это та графика, которую вы видите в процессе игры.

Второй тип изображений, `*-mask.png`, содержит только маски объектов. Маски используются для обозначения границ объектов и, в некоторых случаях, позволяют объекту быть прозрачным (как, например, очки). Желательно, хотя и не обязательно, размещать объекты на тех же местах в файле игрового поля, что и в файле маски.

В том же каталоге находится файл `layout.xml` (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`), который описывает используемые файлы, а также их связь с пунктами меню. Кроме того он описывает позиционные параметры игрового поля и объектов в файлах игрового поля и маски. В том же файле осуществляется присваивание объектам звуков и объединение объектов в группы. Наконец, в нем описаны языки как наборы переведенных звуков. Файл `layout.xml` является стандартным XML-файлом. Более подробно об этом файле см. ниже).

И в этом же каталоге находится файл с именем`layout.i18n` (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`). Файл содержит строки из `layout.xml`, которые могут быть переведены:

- Пункты меню, позволяющие выбирать игровое поле и язык

- Имена категорий объектов

В каталоге выше находится файл `ktuberlingui.rc` (`$KDEDIR/share/apps/ktuberling/ktuberlingui.rc`). В этом XML-файле описываются меню &ktuberling;. Он должен содержать один тег - `<действие>` на каждое игровое поле и язык. Символическое имя действия в этом файле должно быть идентично символическому имени действия в файле `layout.xml`.

## Перевод

Локализация игры может быть осуществлена не только с помощью обычного механизма перевода меню и сообщений программ &kde; (механизма `.po`-файлов), но и переводом звуков игры.

Звуковые файлы в формате wav (`.wav`) с названиями объектов на языке переводчиков могут быть помещены в подкаталоге соответствующего языка в основном каталоге звуков. Имя звука затем следует соотнести с файлом в файле `layout.xml`. Например, если язык перевода - русский, то необходимо поместить звуковые (`.wav`) файлы с названиями объектов в каталог `$KDEDIR/share/apps/ktuberling/sounds/ru`. Затем нужно соотнести звук hat с файлом `ru/шляпа.wav`.

В будущем &ktuberling; будет использовать файлы OGG Vorbis rc3 для хранения звуков. В настоящий момент можно сконвертировать файлы WAV в формат OGG Vorbis rc3 следующей командой:

    $ oggenc_rc3 -o sound.ogg sound.wav

Сведения о локализации и переводе &kde; доступны на The KDE Translation HOWTO.

## Программистам

Программисту не трудно расширить и дополнить функциональность &ktuberling;.

### Классы C++

`TopLevel`

- Окно верхнего уровня и основные функции управления программой

`Игровое поле`

- Описание одного из уровней игры

`ToDraw`

- Описание одного из выводимых графических объектов

`Звуки`

- Описание одного из языков и его звуков

`Действие`

- Действие пользователя, связанное со стеком отмены/повтора.

### Структура `.tuberling`-файлов

`.tuberling`-файл содержит всю необходимую для прорисовки монстрика информацию. Это простой текстовой файл и его можно редактировать любым текстовым редактором

Первая строка содержит номер игрового поля.

В остальных строках размещаются графические объекты в том порядке, в котором они должны быть нарисованы. В одной строке содержится один объект. Каждая строка состоит из 5 чисел: идентификатор объекта и координаты прямоугольника (левая, верхняя, правая и нижняя), в которых объект должен быть нарисован. Числа разделяются пробелами или символами табуляции.

## Структура файла `layout.xml`.

Тег верхнего уровня является уникальным и называется `<ktuberling>`. В нем содержится несколько тэгов `<playground>` игровых полей, по одному на поле, и `<language>` по одному на язык.

Тег `<playground>` имеет два атрибута: `gameboard` и `masks`. Эти атрибуты задают имена файлов, содержащих изображения: `gameboard` - изображения игрового поля, `masks` - масок объектов. Тег `<playground>` содержит один тег `<menuitem>`, один тег `<editablearea>`, несколько тегов `<category>` и несколько тегов `<object>`.

Тег `<menuitem>` описывает идентификатор-действие пункта меню, который позволяет выбрать положение области, в которую вы можете перемещать и бросать объекты, а также метку этого пункта меню. Этот идентификатор должен совпадать с идентификатором в файле `ktuberlingui.rc`.

Тег `<editablearea>` описывает положение области, в которую вы можете перемещать объекты, и звук, ассоциированный с ней.

Тег `<category>` описывает положение и метку текста, описывающего группу объектов. Например, им могут быть описаны положение и текст группы Шляпы.

Тег `<object>` описывает положение объекта в файлах игрового поля и маски, а также файл звука, ассоциированного с ним.

Тег `<playground>` имеет один атрибут: `code`. Этот атрибут задает код локали языка. Тег `<language>` также содержит один тег `<menuitem>` и несколько тегов `<sound>`.

Здесь не описываются теги более низкого уровня, так как их названия говорят сами за себя (людям, знающим английский язык :-) прим. пер.). Если вы изменяете файл `layout.xml`, то не забывайте также соответственно изменять и файлы `layout.i18n` и `ktuberlingui.rc`.