# Підручник з &kappname;

Gael
Kleag
de Chalendar

    Kleag@free.fr

Юрій
Чорноіван

    yurchor@ukr.net

Переклад українською
2002-2008
Gael de Chalendar
&FDLNotice;
18/09/2008
4.1.2

&kappname; є комп’ютеризованою версією добре відомої стратегічної гри. Існують комерційні та інші вільні версії гри, але автор, Gaël de Chalendar, створив цю гру від початку для того, щоб покращити свої знання мови програмування C++ і отже, розробив цю гру до сучасного її стану (подробиці можна прочитати у файлі README).

У поточній версії, &kappname; є грою за участі декількох гравців, можливістю грати мережею та з комп’ютерним інтелектом. (подробиці можна прочитати у файлі TODO)

У цій документації подано основну інформацію, яка буде потрібна вам для того, щоб розпочати гру. Щоб отримати додаткові відомості, читайте повідомлення у рядку стану і підказки. Окрему главу документації присвячено створенню нових шкірок для &kappname;

Метою гри є звичайне завоювання світу... Ця мета досягається нападом на ваших сусідів за допомогою ваших армій. Миролюбна гра, чи не так? :-)

KDE
kdegames
гра
стратегія
Ризик
вільна
GPL
Мережа
AI

## Вступ

&kappname; є комп’ютеризованою версією добре відомої стратегічної гри. Існують комерційні та інші вільні версії гри, але автор, Gaël de Chalendar, створив цю гру від початку для того, щоб покращити свої знання мови програмування C++ і отже, розробив цю гру до сучасного її стану (подробиці можна прочитати у файлі README).

Ось знімок вікна &kappname; Знімок вікна

У поточній версії, &kappname; є грою за участі декількох гравців, можливістю грати мережею та з комп’ютерним інтелектом. (подробиці можна прочитати у файлі TODO)

У цій документації ви знайдете лише основні відомості, які потрібні для того, щоб розпочати гру. Будь ласка, зверніть увагу на підказки та повідомлення у смужці стану, щоб отримати повнішу інформацію.

Метою гри є звичайне завоювання світу... Ця мета досягається нападом на ваших сусідів за допомогою ваших армій. Миролюбна гра, чи не так? :-)

## Користування &kappname;

### Як грати у &kappname;

Попереднє зауваження: гортати карту можна у три способи:

- Ви можете підвести вказівник миші до краю вікна, — програма почне гортати карту у відповідному напрямку.

- Ви можете скористатися коліщатком миші: без натискання клавіші-модифікатора воно гортає карту у вертикальному напрямку, а за натискання клавіші &Alt; — у горизонтальному.

- Ви можете скористатися клавішами зі стрілочками на клавіатурі

#### Як розпочати гру

Після запуску &kappname; ви побачите перед собою головне меню. Головне меню &kappname; Головне меню

Нова гра

  Починає нову гру

Приєднатися

  Надає змогу приєднатися клієнтом до мережевої гри

Завантажити

  Використовуйте для завантаження раніше збереженої гри

Вийти

  Можливо, зрештою ви зовсім не бажаєте грати?

Якщо ви натиснете кнопку Нова гра, програма відкриє перед вами діалогове вікно Властивості нової гри, у якому ви зможете обрати кількість гравців, шкірку (або тему) гри, тип гри (підкорення мети або особлива мета) і нарешті, чи будуть у гру грати гравці з мережі, чи лише локальні гравці. Діалогове вікно нової гри Діалогове вікно нової гри

Щоб розпочати гру мережею, позначте пункт Гра мережею, розташований праворуч від поля лічильника кількості гравців. Після натискання кнопки Гаразд ви зможете обрати параметри мережевої гри: кількість гравців і порт TCP, на якому програма очікуватиме на з’єднання. Діалогове вікно параметрів гри мережею Діалогове вікно параметрів гри мережею

Після цього мережеві гравці зможуть приєднувати до гри за допомогою кнопки Приєднатися на вступному вікні. Їм слід буде вказати IP або назву вузла та порт, які було раніше встановлено вами. Діалогове вікно приєднання до гри мережею Діалогове вікно приєднання до гри мережею

Кожне з’єднання буде позначено повідомленням у смужці стану. Повідомлення про з’єднання Повідомлення про з’єднання

Припустімо, що ви не змінювали типовий параметрів, а просто натиснули кнопку Гаразд. Тоді вам слід буде вказати параметри для двох гравців почергово. Для кожного з них ви оберете ім’я, націю і, якщо забажаєте, вкажете пароль, щоб ніхто інший, окрім вас, не зміг грати за відповідного гравця після завантаження гри за вашої відсутності. Нарешті, ви зможете вказати, хто гратиме за цього гравця: комп’ютер чи людина. Діалогове вікно налаштування гравця Діалогове вікно налаштування гравця

Далі, якщо ви обрали гру з метою, буде показано мету для кожного з гравців, перед якою буде показано повідомлення, щоб інші гравці не змогли підглянути вашу мету у грі. Діалогове вікно показу мети Діалогове вікно показу мети Повідомлення попередження про мету гри Повідомлення попередження про мету гри

#### Розподіл

На початку гри країни розподілено між всіма гравцями. У кожній країні розміщено одну армію (це показано зображенням піхотинця). У кожного з гравців є декілька армій, які він може розмістити у свої країнах під час свого ходу (їх присутність буде позначено за допомогою назви і прапора у смужці стану). Зауважте, що п’ятьом арміям відповідає кіннотник, десятьом — гармата.

Щоб розмістити армію у одній з ваших країн, натисніть позначку армії за допомогою лівої кнопки миші. Щоб вилучити армію, натисніть праву кнопку миші. Зауважте, що як правило, ви ніколи не зможете вилучити більше армій, ніж вам потрібно розташувати. Розподіл армій Розподіл армій

Після того, як гравець розмістить всі свої армії, до тих самих дій запрошується наступний гравець. Коли всі гравці завершать розподіл власних армій, можна обрати одну з двох можливостей, які можна обирати за допомогою кнопок, розташованих на правій панелі.

Перерозподіл Повторний цикл

  Один з гравців бажаєте змінити свій вибір. Перший з гравців, у такому випадку, зможе вилучати розташовані ним армії з одної країни за допомогою правої кнопки миші і розташовувати ці армії у іншій країні за допомогою лівої кнопки миші. Після завершення цих дій, право зміни розташування перейде до наступного гравця після натискання кнопки Підтвердити. Після того, як всі гравці завершать перерозподіл власних армій, дві кнопки, про які ми вже говорили буде показано знову.

Кінець перерозподілу Завершено

  Перерозподіл завершено, і гру можна продовжувати.

#### Битва

Після перерозподілу починається сам хід. Кожен з гравців почергово може виконати такі дії:

Наступний гравець Наступний гравець

  Завершити хід поточного гравця і передати хід наступному гравцеві.

Атака 1 Атака 2 Атака 3 Атакувати одною, двома або трьома арміями Автоатака Автоматична атака

  Щоб почати атаку, натисніть ліву кнопку миші і перетягніть вказівник миші з країну, з якої бажаєте атакувати, до країни, яку бажаєте атакувати. Програма відкриє контекстне меню з декількох пунктів. Меню атаки Меню атаки Щоб з країни X можна було атакувати країну Y x арміями, має виконуватися 2 умови:

  - ці дві країни мають бути сусідніми;

  - у країні X має бути принаймні x+1 армія перед атакою.

  Якщо атака можлива, за потреби, буде показано діалогове вікно для гравця, який захищається. За допомогою цього вікна гравець зможе обрати, чи бажає він захищатися однією, чи двома арміями і чи надасть він змогу вирішити це питання комп’ютерові.

  Після того, як гравець, що захищається зробить свій вибір, відбудеться битва. Її опис подано нижче. Діалогове вікно захисту Діалогове вікно захисту

Пересувати армії Пересунути армії з однієї країни до іншої

  Це остання дія під час ходу гравця. За її допомогою можна пересунути декілька армій з однієї країни до іншої, сусідньої з першою. Щоб обрати ці дві країни, будь ласка, скористайтеся перетягуванням і скиданням, як під час атаки. Після вибору двох країн буде показано повзунок, за його допомогою ви зможете обрати кількість армій, які залишаться після пересування у кожній з країн.

#### Наслідки битви

За кожну з армій, які беруть участь у битві, кидається відповідна кістка. Гравець, чия кістка покаже більше очок, нападник або гравець, який захищається, виграє, а той, чия кістка покаже менше очок, втрачає кількість армій, яка визначається кількістю викинутих очок. Показ результатів атаки Показ результатів атаки

Після того, як кількість армій у країні, яка захищається, досягне 0, право володарювання над країною переходить до гравця, який здійснював атаку: на карті країни буде встановлено прапор цього гравця, а у самій країні розквартировано одну з армій, які здійснювали атаку. Програма також покаже повзунок «Пересунути армії», як під час пересування наприкінці ходу. Повзунок вторгнення Повзунок вторгнення

#### Кінець ходу

Щоб завершити ваш поточний хід, якщо ви не бажаєте пересувати армії, скористайтеся кнопкою Наступний гравець, розташованою на панелі інструментів.

Після того, як всі гравці зроблять власні ходи, хід гри вважається завершеним. Після цього кожному з гравців, залежно від кількості країн, якими цей гравець володіє, буде додатково надано певну кількість армій: по одній на кожні три країни, за мінімальної кількості у три країни. Крім того, бонусні армії отримають гравці-володарі континентів, кількість бонусних армій залежить від континенту. Кількості армій для типової шкірки:

##### Бонуси за континентами

Континент | Бонус
--- | ---
Північна Америка | 5
Південна Америка | 2
Європа | 5
Африка | 3
Азія | 7
Тихоокеанський регіон | 2

Після завершення розподілу гравцем армій, йому слід натиснути кнопку Підтвердити, щоб право перерозподілу бонусних армій перейшло до наступного гравця. Так само, як і для початкового розподілу, після розташування армій усіма гравцями вони можуть почати новий цикл перерозподілу або почати новий хід...

#### Надсилання повідомлень іншим гравцям

Якщо ви граєте у гру локально і бажаєте спілкуватися з іншими гравцями, ну, тоді ви можете з ними заговорити (якщо у вас немає з цим проблем)... Але якщо ви граєте у гру мережею, ви можете скористатися панеллю балачки, розташованою у нижній частині вікна (її можна сховати або показати за допомогою стрілочок). Просто введіть ваше повідомлення і натисніть клавішу &Enter;. Надсилання повідомлень Надсилання повідомлень

## Довідка щодо команд

### Головне вікно &kappname;

#### Кнопки

Вийти Вийти

  Завершує роботу програми.

Нова гра Нова гра

  Починає нову гру. Програма відкриває діалогове вікно, у якому запитує вас про кількість гравців. Після цього кожен з гравців зможе ввести своє ім’я у іншому діалоговому вікні.

## Довідник розробника для &kappname;

Для отримання документації щодо програмного інтерфейсу, будь ласка, завітайте на сайт за адресою http://api.kde.org/. Там ви знайдете повну, але трошки застарілу документацію. У файлах реалізації, `.cpp` ви не знайдете коментарів.

Зауважте, що автор спочатку розробляв цю гру у &Windows; за допомогою Borland C++ і WinG. Цю гру було портовано на &Java;, перш ніж її було переписано знову на C++ у &kde;. На початку автор вживав французьку і мішанину французької і англійської мов для створення назв ідентифікаторів (назв класів, методів, членів тощо). Коментарі також писалися французькою. Коли автор вирішив розпочати поширення гри, він вирішив також переписати все англійською... але, очевидно, англійська для нього не є рідною: будь ласка, пропонуйте і надсилайте виправлення до коментарів у коді або до цієї документації.

## Як створювати нові оболонки

Зовнішній вигляд &kappname; можна повністю змінити. Для користувачів, які мають таланти у малюванні, створення нової шкірки буде дуже простим: скопіюйте існуючу шкірку і змініть графіку у ній, оновіть дані у файлі налаштувань .desktop. Останнім кроком буде зміна файла опису даних, які слід встановлювати для шкірки.

Всі приклади (текст і зображення) взято з типової шкірки &kappname;

### Структура тек і файлів

- Data/ : дані, що використовуються програмою для обробки зображень шкірки.

  - CMakeLists.txt : описує файли, які слід встановити.

  - onu.desktop : головний файл опису шкірки. Його опис наведено нижче.

- Images/ : зображення шкірки (карта, спрайти тощо)

  - CMakeLists.txt : описує файли, які слід встановити.

  - pool.svg : карта і всі спрайти, які використовуються у цій шкірці.

  - map-mask.png : зображення, за яким програма визначає, над якою з країн на карті зараз знаходиться вказівник миші (див. нижче).

  - *.png : всі інші зображення є зображеннями кнопок.

- CMakeLists.txt/ : Описує файли, які слід встановити.

- Sounds/ : звукові файли шкірки.

### Тека Data

#### Файл onu.desktop

У цьому файлі має бути опис вмісту шкірки. Його використовують для опису структури світу та способу його показу. Структура цього файла така:

Група onu містить декілька записів країн, декілька записів націй і, нарешті, декілька записів континентів. Далі, різноманітні групи містять опис різних спрайтів, опис різних країн, континентів, націй і типів мети.

У подальших відомостях цього розділу наведено інформацію про вміст кожної з груп.

##### Група onu

###### Записи групи onu

Назва запису | Призначення
--- | ---
ширина | Ширина карти шкірки
висота | Висота карти шкірки
skinpath | Шлях до шкірки, відносно шляху до даних програми (наприклад, skins/default)
nb-countries | Кількість країн (42 у типовій шкірці). Нижче має бути наведено таку саму кількість записів груп країн
nb-nationalities | Кількість націй (6 у типовій шкірці). Нижче має бути наведено таку саму кількість записів груп націй
nb-continents | Кількість континентів (6 у типовій шкірці). Нижче має бути наведено таку саму кількість записів груп континентів
pool | Шлях і назва файла набору (pool), відносно шляху до шкірки (наприклад, Images/pool.svg)
map-mask | Шлях і назва файла маски карти, відносно шляху до шкірки (наприклад, Images/map-mask.png)
format-version | Версія формату файла шкірки (2.0)
name | Назва шкірки
desc | Розгорнутий опис шкірки
fighters-flag-y-diff | Різниця висот між спрайтами прапорів і гармат
width-between-flag-and-fighter | Кількість пікселів між найлівішим пікселем прапора і найправішим пікселем простої гармати (без пострілу і вибуху)

##### Групи описів спрайтів

Кожен з типів спрайтів (прапор, піхота, кіннота, гармата, гармата, що стріляє, і гармата, що вибухає) визначається групою. Лише деякі з спрайтів мають запис ширини. Цей запис використовується для відносного позиціонування під час анімації: гармати, постріл і вибух не повинні «рухати» об’єкт навколо прапору країни під час битви.

###### Записи групи опису спрайта

Елемент | Призначення
--- | ---
ширина | Еталонна ширина кадрів спрайта прапора
висота | Еталонна висота кадрів спрайта прапора
кадри | Кількість кадрів у спрайті
версії | Кількість версій спрайтів прапора

##### Групи опису країн

Кожна з країн має свою групу onu, запис країни має власну групу з міткою у вигляді назви країни. У наведеній нижче таблиці показано записи цих груп.

###### Записи країн

Назва запису | Призначення
--- | ---
id | Цілий унікальний ідентифікатор країни, який має починатися з нуля (0)
name | Назва країни, яку буде показано гравцеві
<sprite>-point | Кожен з типів спрайтів (прапор, піхота тощо) на зображенні країни буде показано у певній позиції, яка визначається цим записом у вигляді двох цілих чисел, відокремлених комою
neighbours | Список ідентифікаторів країн, сусідніх з поточною країною

##### Групи опису націй

Кожна з націй має свою групу onu, запис нації має власну групу з міткою у вигляді назви нації. У наведеній нижче таблиці показано записи цих груп.

###### Записи націй

Назва запису | Призначення
--- | ---
name | Назва нації (наприклад, Японія)
leader | Ім’я, яке буде запропоновано гравцеві, який обрав цю націю
flag | Назва елемента спрайта прапора країни у файлі SVG onu

##### Групи опису континентів

Кожен з континентів має свою групу onu, запис континенту має власну групу з міткою у вигляді назви континенту. У наведеній нижче таблиці показано записи цих груп.

###### Записи континентів

Назва запису | Призначення
--- | ---
name | Назва континенту (наприклад, Африка)
id | Унікальне ціле число для ідентифікації континенту.
bonus | Кількість армій, які отримуватиме наприкінці ходу гравець, який володіє всіма країнами на континенті
continent-countries | Список ідентифікаторів країн на поточному континенті

##### Групи опису мети

Кожну мету має бути включено до списку групи onu, запис мети має власну групу, чиєю міткою є назва метри. У наведеній нижче таблиці показано список записів цих груп.

###### Записи мети

Назва запису | Призначення
--- | ---
тип | Тип мети. Може мати значення континенту, країн або гравця
nbArmiesByCountry | встановлює мінімальну кількість армій, які гравець може залишати у кожній з країн
nbCountries | встановлює кількість країн, якими має володіти гравець
nbCountriesFallback | Призначено для типу мети гравця, якщо відповідного гравця буде вбито іншим гравцем, цим параметром встановлюється кількість країн, які має навзамін завоювати гравець
desc | Повний текстовий опис мети з відповідними заповнювачами (потрібна додаткова документація)
continents | Список ідентифікаторів континентів, які гравець має підкорити

### Тека Images

У цій теці містяться кнопки, специфічні для &kappname; і файл SVG з назвою pool (набір), у якому міститься карта і всі спрайти.

#### Файл pool.svg

У цьому файлі SVG містяться всі спрайти гри. Кожен з його елементів має таку назву, щоб програма могла визначити і показати його окремо від інших.

У типовій шкірці спрайтами є прапори, піхота, кіннота і гармата. Піхота відповідає одній армії, кіннота — п’яти, а гармата — десяти. Гармати також використовуються для показу битв. Ось чому у типовій шкірці три види спрайтів гармат: звичайна нерухома гармата або гармата, що рухається, гармата, що стріляє, гармата, що вибухає.

Кожне з зображень спрайта складається з об’єднання різних виглядів об’єкта, а кожен з виглядів, — з кадрів. Вигляди має бути впорядковано вертикально, а кадри — горизонтально. Місце, де зображення буде розрізано визначається за висотою зображення і кількістю виглядів, а ширина за кількістю кадрів. Всі ці дані знаходяться у файлі onu.desktop.

Приклад зображення спрайта: cannon.png

Спрайти армій мають три різних вигляди, згори вниз:

- дивиться праворуч

- дивиться ліворуч і

- в обличчя

Прапори мають лише один вигляд. Всі елементи тла спрайтів слід зробити прозорими.

Приклад спрайта зображення прапора: italy.png

##### Елементи набору

Назва елемента | Зразок зображення | Призначення
--- | --- | ---
map |  | Карта шкірки світу. Країни можуть мати довільну форму, але їх має бути зібрано у придатні для розпізнавання оком континенти, лише за розташуванням або лише за кольором.
italy |  | Прапор нації Італії. Кожна з націй повинна мати такий запис.
infantry |  | Піктограма для однієї армії
cavalry |  | Піктограма для п’яти армій
cannon |  | Піктограма для десяти армій
firing |  | Піктограма для показу армій під час битви
exploding |  | Піктограма для показу армій, які програли битву
Alaska |  | Форма країни Аляска. Її буде використано для підсвічування цієї країни. У кожної з країн лише одна така форма. Її колір не використовується, отже його можна обрати будь-яким.
reddices |  | Для показу результатів битви буде використано червоні кістки
bluedices |  | Для показу результатів битви буде використано сині кістки
mark1 |  | Цю позначку буде додано до спрайтів учасників битви, вона позначатиме кількість армій, які беруть участь у битві, у нашому прикладі 1. Існують також елементи mark2 і mark3.

#### Файл map-mask.png

Цей файл png також відповідає карті шкірки світу, але з закодованими кольорами, за допомогою яких можна точно визначити кожну з країн. Країни повинні мати принаймні такі самі форми, які мають відповідні країни у файлі map.png так, щоб користувач, який навів вказівник на будь-яку частину певної країни і клацнув лівою кнопкою миші, міг обрати потрібну йому країну. Країни, які складаються з невеличких островів, на зразок Індонезії, можна збільшити порівняно з відповідниками з файла map.png, щоб полегшити вибір відповідної країни. Зразок маски карти

Компонент синього кольору (у моделі RGB) у кольорі країни призначено для ідентифікації країни: індексом 0 позначається країна 0 у файлі onu.xml, індексом 1 — країна 1 тощо. Білим кольором (0xFFFFFF у RGB) позначається відсутність країни (моря або, чому б ні, незаселені території).

#### Зображення кнопок

Назви файлів включено до коду програми, отже їх не можна змінювати. У наведеній нижче таблиці показано всі кнопки, які слід намалювати для теми.

##### Кнопки графічного інтерфейсу користувача

Зображення | Назва файла | Призначення
--- | --- | ---
| newNetGame.png | Спроба приєднання до гри мережею
| recycling.png | Після того, які всі гравці розташують свої армії, можна розпочинати зміну дислокацій (а саме, перестановку армій). Ця кнопка запрошує до такої передислокації.
| recyclingFinished.png | Вибір відмови від перерозподілу. У всіх клієнтських вікнах має бути ця кнопка, яку слід буде натиснути для того, щоб повністю завершити розподіл.
| joueurSuivant.png | Завершення ходу поточного гравця і перехід ходу до наступного гравця, або перехід до наступного ходу, якщо гравець ходив останнім.
| attackOne.png | Вибір початку атаки силами однієї армії.
| attackTwo.png | Вибір початку атаки силами двох армій.
| attackThree.png | Вибір початку атаки силами трьох армій.
| defendOne.png | Вибір захисту атакованої країни силами однієї армії.
| defendTwo.png | Вибір захисту атакованої країни силами двох армій.
| moveArmies.png | Вибір початку пересування армій між двома країнами (остання дія протягом ходу)

### Тека Sounds

У цій теці містяться три звукових файла:

- roll.wav відтворюється під час пересування армій

- cannon.wav відтворюється під час ведення вогню і

- crash.wav відтворюється під час вибуху гармати

## Запитання і відповіді

&reporting.bugs; &updating.documentation;

Яким буде перше питання, що стосується &kappname;?

## Подяки і ліцензія

&kappname;

Авторські права на програму належать © 2002-2008 Gael de Chalendar kleag@free.fr

Учасники розробки: Robin Doer, Albert Astals Cid, Michal Golunski (Переклад польською).

Авторські права на документацію до програми © 2002-2008 Gael de Chalendar kleag@free.fr

Переклад українською: Юрій Чорноіванyurchor@ukr.net

&underFDL; &underGPL;

## Встановлення

### Як отримати &kappname;

&install.intro.documentation;

### Збирання і встановлення

&install.compile.documentation;

### Налаштування

Пункт меню «Параметри» відкриває діалогове вікно, за допомогою якого ви можете: Діалогове вікно налаштувань Діалогове вікно налаштувань

- увімкнути або вимкнути відтворення звуків;

- встановити швидкість спрайтів (від повільної до миттєвої);

- увімкнути або вимкнути контекстну довідку, яку буде показано у підказках;

- увімкнути показ або приховати кількість армій у кожній з країн. На наступному знімку вікна ви можете бачити карту з показаною кількістю армій у країні. Показ кількості армій Показ кількості армій

&documentation.index;