[DEV RU] Конвенции написания кода
Необходимость приведения кода к единому формату обусловлена тем, что одному разработчику и без того трудно сразу понять чужой код, а когда он оформлен непривычно или просто плохо, то и подавно.
В данном документе будут описаны стандарты оформления кода, названий токенов, переменных и так далее.
В разработке скриптов используется Lua-подобный язык.
Давайте взглянем на следующий код национального фокуса.
focus = {
id = KOA_Not_So_Loyal_Ones
text = KOA_Not_So_Loyal_Ones
icon = GFX_icon_unknown
cost = 4
relative_position_id = KOA_The_Root_of_All_Evils
x = -1
y = 1
prerequisite = {
focus = KOA_The_Root_of_All_Evils
}
completion_reward = {
# TODO: Add custom tooltip
country_event = koa.318
}
}
Легко видеть, что токены focus, prerequisite и completion_reward имеют комплексные значения, описываемые в фигурных скобках. Первая фигурная скобка открывается после знака = на той же строке. Код внутри скобок сдвигается на одну табуляцию (либо 4 пробела, но лучше табуляцию) вправо. Закрывающая скобка находится на отдельной строке, её горизонтальная позиция равняется таковой у первой буквы открывающего токена.
Учитывайте, что пары "токен-значение" парсятся игрой построчно, безо всяких символов, завершающих выражение. Только комплексные значения парсятся исходя из положения открывающих и закрывающих скобок.
Комментарии в коде оставляются с помощью символа #. Всё, что находится после этого символа на данной строке, будет проигнорировано игрой при парсинге кода. Если нужно оставить многострочный комментарий, то пишите на каждой строке #. Горизонтальное положение символов # должно быть одинаковым, то есть таким, чтобы они образовывали вертикальный ряд. В примере выше легко видеть, что комментарий оставлен с отступом, соответствующим области комплексного значения токена: так следует делать и в остальных случаях.
Фокусы для конкретных стран называются в следующем формате:
TAG_Lorem_Ipsum. Здесь TAG соответствует тегу страны, для которой создаётся фокус,
а Lorem_Ipsum соответствует названию фокуса.
Фокусы для нескольких стран сразу называются в следующем формате:
COMMON_Lorem_Ipsum.
При позиционировании национальных фокусов следует соблюдать простое правило. Фокус, являющийся корневым для отдельного дерева, имеет абсолютные координаты. Если требуется разместить одно дерево относительно другого, то используются относительные координаты. Фокусы, не являющиеся корневыми в дереве, размещаются относительно своего родителя. Рассмотрим пример.
Верхний фокус имеет координаты (69, 7): нас сейчас не интересует, заданы ли они абсолютно или относительно родителя. Нас интересует фокус KOA_Masters_of_Mobius и производные от него. Фокус KOA_Masters_of_Mobius является корневым для целого дерева, поэтому его координаты можно задать двумя способами: абсолютно (69, 9) или относительно KOA_Project_Crown_Atomic. Второй случай применяется тогда, когда мы хотим, чтобы при перемещении верхнего дерева сдвигалось и нижнее вместе с ним.
Производные фокусы в дереве сами могут иметь поддеревья. Фокус KOA_To_Glorious_Yesterday размещается относительно KOA_Masters_of_Mobius:
relative_position_id = KOA_Masters_of_Mobius
x = 2
y = 1
Фокус KOA_The_Root_of_All_Evils размещается уже относительно KOA_To_Glorious_Yesterday.
relative_position_id = KOA_To_Glorious_Yesterday
x = 0
y = 1
Фокусы KOA_Not_So_Loyal_Ones и KOA_The_Guerilla_Answered являются потомками KOA_The_Root_of_All_Evils, а потому оба размещаются относительно него.
relative_position_id = KOA_The_Root_of_All_Evils
x = -1
y = 1
===
relative_position_id = KOA_The_Root_of_All_Evils
x = 1
y = 1
Национальные духи для конкретных стран называются в следующем формате:
TAG_Lorem_Ipsum_Idea. Здесь TAG соответствует тегу страны, для которой создаётся идея,
Lorem_Ipsum соответствует названию идеи, а завершается название суффиксом Idea.
Национальные духи для нескольких стран сразу называются в следующем формате:
COMMON_Lorem_Ipsum_Idea.
События для конкретных стран должны оформляться в следующем формате:
country_event = {
# Walking the Human
id = koa.358
title = koa.358.t
desc = koa.358.d
fire_only_once = yes
is_triggered_only = yes
option = {
# Provoke UFA to declare a war
name = koa.358.a
UFA = {
country_event = ufa.351
}
}
option = {
# Declare a war
name = koa.358.b
declare_war_on = {
target = UFA
type = annex_everything
}
news_event = shared.17
country_event = super.100
}
}
Первым делом идёт комментарий с названием события. Оно должно соответствовать таковому
в диздоке и в файлах локализаций.
Затем идут значения ID, названия и описания события. Легко видеть, что здесь
указан неймпейс koa и через точку номер события. Название события завершается суффиксом
t, а описание суффиксом d.
После этого идут токены fire_only_once и is_triggered_only. После них идут
дополнительные токены (hidden, immediate и т.д.).
В конце идут опции. В каждой из них в комментарии пишется краткое описание действия
опции. Затем идёт токен названия опции: он должен завершаться буквенным суффиксом,
проставляемым в алфавитном порядке. При этом буква d пропускается (буква t тоже, но
зачем городить такие жирные фокусы?).
Для написания локализации используется YAML.
Файлы локализации расположены в папке localisation. Каждый файл локализации
начинается со строчки l_<language>:, где language — язык (russian, english и так далее).
Допускается только один язык на файл.
Далее идут пары ключ-значение, где токенам ставятся в соответствие строки на данном языке.
Каждая пара располагается на своей строке, переносы запрещены. Если необходимо сделать
перенос в самой строке локализации, пишите \n на том месте, где нужно разместить перенос.
Каждая строка с переводом предваряется пробелом. Затем идёт имя ключа в следующем формате:
<KEY>:0. Здесь KEY — название ключа. Ключ может соответствовать имени фокуса, ID ивента
или другому переводимому токену. Локализации каждого типа токенов хранятся в отдельных
файлах (музыка в music_l_<language>.yml, тултипы в tooltips_l_<language>.yml и т.д.).
Таким образом, в одном файле не должны смешиваться токены разных типов: фокусов, событий,
идей и так далее.
После ключа ставится пробел, затем размещается сама строка локализации. Она должна быть обрамлена в двойные кавычки. Старайтесь не допускать грамматических и пунктуационных ошибок, а также следите за корректностью синтаксиса.