Справочное руководство Enigma

Данное руководство описывает внутреннюю структуру игры Enigma версии 1.20, в частности процесс создания уровней с использованием языка программирования Lua и особенности взаимодействия с движком игры.

1. Использование Enigma

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

Эта глава должна помочь ответить на эти вопросы, а также предоставить основные сведения, которые могут понадобиться для того, чтобы управлять пакетами уровней, отдельными уровнями и создавать собственные уровни (подробно обо всём этом в следующих главах).

1.1 Размещение ресурсов

Для создания резервных копий, внесения изменений в систему, особых конфигураций, а также для добавления новых уровней (в том числе, надеемся, и своих собственных) вам нужно знать, где хранятся ресурсы Enigma и как ими можно управлять.

Для управления загрузкой игры и хранением данных служат несколько путей. Их список можно вызвать в подменю справки или запустив Enigma из консоли с опцией ‘--log’ (см. раздел Опции запуска).

Путь к настройкам

Это путь к файлу с пользовательским настройками приложения. Этот файл обычно размещается у пользователя в директории HOME. Данные пользователей систем Windows, в которых HOME отсутствует, хранятся в директории ‘Application Data\Enigma’. Поскольку это третья версия игры, файл по умолчанию называется ‘.enigmarc.xml’.

Мы рекомендуем создать резервную копию этого файла, хотя там и содержится совсем немного данных, которые можно быстро восстановить.

Поскольку эти настройки очень сильно зависят от операционной системы и конфигурации, каждая установленная игра использует отдельную версию данного файла.

Для разработчиков игры существует опция ‘--pref’ (см. раздел Опции запуска), с помощью которой можно переименовать файл настроек. Запустив программу с переименованным файлом настроек, разработчик может проверить новую конфигурацию, не рискуя потерять свои собственные настройки. Также разработчик в целях проверки может использовать переименованный файл, чтобы запустить игру со стандартной конфигурацией.

В любом случае файл настроек будет скрыт при помощи знака ‘.’ в начале имени файла.

Папка пользователя

В этой папке хранится основная часть пользовательских данных игры. Здесь содержатся все обновления, уровни, написанные или установленные пользователем, счёт, история и, как правило, сделанные пользователем снимки экрана и эскизы уровней.

Обязательно создайте резервную копию этой папки!

Её стандартное размещение — директория ‘.enigma’ в вашей директории HOME. В системах Windows, в которых отсутствует HOME, этой цели служит директория ‘%APPDATA%\Enigma’, которая разрешается в подпапку ‘Application Data\Enigma’ в Windows XP/2000 или ‘AppData\Roaming\Enigma’ в Vista/Windows 7, расположенную в папке данных пользователя.

В папке пользователя также хранятся файлы журналов событий и ошибок.

Путь к папке с пользовательскими данными можно задать в меню Настройки (см. раздел Пользовательские опции). Так можно сохранить данные игры на внешнем накопителе или общем разделе жёсткого диска и использовать их на различных установках Enigma.

Папка эскизов

Это ещё одна пользовательская папка Enigma. В ней хранятся изображения, в частности снимки экрана и эскизы уровней. Обычно папка пользователя, указанная в строке ‘Папка пользователя’, является одновременно и папкой изображений.

Если вы делаете много снимков экрана, а место в директории, указанной в строке ‘Папка пользователя’ ограничено, можно задать отдельный путь для папки с изображениями в меню Настройки (см. раздел Пользовательские опции).

Системная папка

В этой папке содержатся все системные ресурсы дистрибутива Enigma. Здесь находятся уровни, библиотеки и т. д. Начинающим создавать свои собственные уровни обязательно нужно сюда заглянуть в поисках примеров.

Папки с ресурсами

Это список папок. Каждый ресурс, независимый от версии игры, ищется во всех папках из этого списка и загружается из первой найденной папки.

Пользовательские данные в этом списке предваряют системные данные. Таким образом, приоритетом обновления обладают папки пользователя. Если вы заметили разницу между изначальным поведением программы и её работой в данный момент, обратите внимание на этот список. Возможно, вы посмотрели на файл, который был перекрыт другим файлом из предыдущего пути в этом списке.

Папка локализации

В этой папке размещаются данные локализаций.

Обратите внимание, что некоторые ресурсы, например уровни, могут храниться в zip-архивах. В таких случаях ресурс, который вы ожидаете найти по адресу ‘имя_директории/имя_файла’, может храниться в zip-файле ‘имя_директории.zip’. Путём к файлу в zip-архиве может выглядеть как ‘имя_директории/имя_файла’ или ‘./имя_файла’. В случае, если ресурс присутствует как в виде zip-файла, так и в другом формате, приоритет отдаётся второму файлу, так как программа воспринимает его как обновление zip-файла.

1.2 Опции запуска

Помимо запуска игры с помощью щелчка по ярлыку на рабочем столе или меню "Пуск", Enigma можно запустить из оболочки или командной строки. Это позволяет добавить при запуске игры набор опций, который будет действовать только для данного запуска.

Для многократного использования одинакового набора опций запуска можно создать ярлык на рабочем столе или запись в меню "Пуск" и добавить опции запуска к целевой строке исполняемого файла Enigma.

Ниже следует список поддерживаемых программой пользовательских опций. Если в списке указано как полное имя опции, следующее за двумя знаками "минус", так и однобуквенное сокращение, следующее за одним знаком "минус", используйте один из вариантов (а не два одновременно), например: ‘--data путь’ или ‘-d путь’.

--assert

Опция, предназначенная для разработчиков игры, которая принудительно выполняет все отладочные проверки, даже ресурсоёмкие. Результаты дополнительной проверки выглядят примерно так: ‘ASSERT(noAssert || long_lasting_check(), XLevelRuntime, "remark");’.

--data -d путь

Опция, предназначенная для разработчиков игры; она позволяет добавить к списку путей ресурсов дополнительный путь, который будет располагаться перед путём к системной папке (см. раздел Опции запуска). Разработчик может проверить сборку Enigma, не устанавливая её, посредством её вызова из оболочки с текущей рабочей директорией в качестве главной директории с помощью опции ‘src/Enigma -d ./data’.

--help -h

Просто выводит на экран все опции запуска и завершает свою работу.

--lang -l язык

Опция, позволяющая выбрать язык игры. Язык задаётся стандартным двухбуквенным обозначением, например ‘fr’ для французского или ‘ru’ для русского.

--log

Эта опция добавляет к стандартному выводу внутреннюю информацию. Пользователи Windows могут найти её в файле ‘Output.log’ в стандартной ‘Папке пользователя’. В ещё одном файле ‘Error.log’ перечислены критические ошибки.

В выводимую информацию будут включены, к примеру, пути, описанные в разделе Размещение ресурсов.

--nograb

Опция для разработчиков Enigma; она отключает в игре управление мышью. В этом режиме вы вряд ли сможете пройти хотя бы один уровень, но это даёт возможность исправлять ошибки в ядре приложения.

--nomusic

Запускает игру с выключенным музыкальным сопровождением.

--nosound

Запускает игру с выключенным звуковым сопровождением.

--pref -p имя_файла

Имя альтернативного файла настроек (без точки для имён скрытых файлов в начале). Как поясняет раздел Размещение ресурсов, эта опция предназначена исключительно для разработчиков игры.

--pref -p путь_к_директории

Путь к альтернативной директории, в которой содержится файл настроек со стандартным именем ‘.enigmarc.xml’. Если файл настроек или папка не существуют, они автоматически создаются. При создании файла настроек здесь по умолчанию располагается пользовательская папка данных. Это позволяет размещать все пользовательские данные игры в отдельной директории, которая может располагаться где угодно, например на USB-накопителе. Чтобы использовать эту новую настройку, всегда нужно запускать Enigma с данной опцией. Помните, что путь, содержащий пробелы, нужно заключать в кавычки.

--redirect

Перенаправляет ‘stdout’ и ‘stderr’ в файлы с названиями ‘Output.log’ и ‘Error.log’ в стандартной папке пользователя (см. раздел Размещение ресурсов). Для Windows данная опция всегда имеет значение true, но она полезна на любых операционных системах, если Enigma запускается через ярлык на рабочем столе или кнопку меню.

--robinson

Закрытие всех подключений к Интернету. При этом не будут выполняться никакие автоматические обновления и на все запросы пользователя, для выполнения которых требуется подключение к Интернету, будет выводиться сообщение об ошибке.

--showfps

Позволяет отображать во время игры количество кадров в секунду (FPS).

--version

Отображает номер версии и завершает свою работу.

--window -w

Позволяет запустить Enigma в оконном режиме (не в полноэкранном).

Enigma интерпретирует все дальнейшие аргументы командной строки как адреса файлов уровней. Можно вводить абсолютные или относительные адреса файлов уровней, размещённых на компьютере. Также можно добавлять URL для уровней, выложенных в Интернете.

Пользователи Unix могут запустить Enigma при помощи следующей команды:

enigma --log ~/mylevel.xml http://somewhere.com/netlevel.xml

Пользователи Windows могут запустить Enigma из командной строки (не забудьте внести изменения в путь установки, чтобы он соответствовал пути установки Enigma на компьютере):

C:\Programs\Enigma\enigma.exe --log demo_simple.xml

Эти уровни можно найти в пакете уровней ‘Startup Levels’. По умолчанию он является видимым, только если в командной строке указаны какие-либо уровни.

1.3 Пользовательские опции

Обновление рейтинга

Пожалуйста, для версий ниже 1.00 оставьте следующее значение для этой опции: ‘Не обновлять’.

Имя игрока

Введите ник, под которым Enigma будет сохранять ваши баллы. Пожалуйста, взгляните на список уже используемых ников на домашней странице Enigma и выберите ещё не используемый. Свой ник можно изменить в любой момент, не рискуя потерять свои данные.

Папка пользователя

Как поясняет раздел Размещение ресурсов, здесь можно указать произвольную директорию для хранения ваших пользовательских данных.

Если очистить данную строку, то данные будут размещены в директории по умолчанию.

Enigma активирует новый путь к папке эскизов после выхода из меню настроек. Хотя она сохраняет все файлы в новой папке и ещё может находить файлы в старой, мы советуем сразу выйти из игры и перенести данные из старой папки в новую. Это необходимо, так как при следующем запуске Enigma будет работать с данными только в новой директории.

Папка эскизов

Как поясняет раздел Размещение ресурсов, здесь можно ввести новую директорию для пользовательских изображений.

Если очистить данную строку, то данные будут размещены в директории по умолчанию.

Enigma активирует новый путь к папке эскизов после выхода из меню настроек. Хотя она сохраняет все файлы в новой папке и ещё может находить файлы в старой, мы советуем сразу выйти из игры и перенести данные из старой папки в новую. Это необходимо, так как при следующем запуске Enigma будет работать с данными только в новой директории.

1.4 Консольная функция инвентаря

Нижняя правая область экрана, где обычно отображаются предметы, содержащиеся в инвентаре, и прокручиваются тексты активированных документов, также позволяет пользователю выводить тексты ранее активированных документов, вводить тесктовые команды и повторно вводить предыдущие команды.

Команду можно ввести с клавиатуры. Просто введите команду и активируйте её, нажав клавишу <Enter>. Поддерживаются следующие команды:

help

Выводит список всех доступных пользователю команд.

abort

Завершение уровня и возврат в меню уровней. Аналогично нажатию <Alt+X>

April 1st

Просто шутка.

cheats

Выводит "читы", предназначенные для быстрого тестирования уровня его разработчиком.

collision

Необходимый разработчикам "чит", отключающий столкновения между камнями и шариками или жемчужинами. При его использовании счёт в случае успешного завершения уровня сохранён не будет.

easy

Перезапуск уровня в простом режиме.

find строка_поиска

Осуществляет во всех пакетах уровней поиск уровней, которые содержат указанную строку в заглавии, имени автора или имени файла.

god

Необходимый разработчикам "чит", который защищает актёров, присвоенных текущему игроку, подобно активированному объекту it_umbrella. При его использовании счёт в случае успешного завершения уровня сохранён не будет.

hunt

Переход в режим охоты за мировыми рекордами. Аналогично выбору иконки мирового рекорда на левой кнопке в меню уровней.

info

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

jumpto пакет,номер

Непосредственный запуск указанного уровня. Для пакета уровней указывается его название. Для уровня указывается его порядковый номер в пакете. Например jumpto Enigma IV,33.

nohunt

Выключает режим охоты за мировыми рекордами. Аналогично выбору иконки шарика на левой кнопке в меню уровней.

regular

Перезапуск уровня в сложном режиме.

restart

Перезапуск уровня в ранее выбранном режиме сложности.

suicide

Убивает актёров, но без завершения уровня, если это возможно. Аналогично нажатию клавиши F3>.

Игра сохраняет историю команд и отображаемых документов. Эту историю можно вывести с помощью стрелок вверх и вниз.

• инвентарь –> переход в начало
• команда 10, самая ранняя команда в истории
• команда 9
• …
• команда 2
• команда 1, последняя выполненная команда
• выполняемая команда, если последняя команда ещё не была выполнена
• инвентарь <– начало
• документ 1, последний просмотренный документ
• документ 2, предыдущий просмотренный документ
• …
• документ n, первый просмотренный документ
• название уровня, подзаголовок, автор, информация, отображаемая при запуске уровня
• инвентарь –> переход в начало

Стрелка вверх, изначально нажатая при отображении предметов в инвентаре, позволяет прокручивать ранее введённые команды. Повторно отправить команду можно нажатием клавиши <Enter>. История будет пересортирована, при этом последняя команда окажется непосредственно над инвентарём. Историю команд можно редактировать в любой момент, в том числе и добавлять туда новые команды. Если после ввода команды не была нажата клавиша <Enter>, строка всё же будет записана и выведена в качестве первой команды над инвентарём. История команд постоянно поддерживается в актуальном состоянии.

Историю документов можно вызвать с помощью стрелки вниз. Все документы, ранее отображённые на уровне, можно вывести повторно. Кроме того, можно снова вывести информацию, отображаемую при запуске уровня.

Если клавишу вверх или вниз нажать после вывода на экран, соответственно, самой ранней команды или сообщения, то будет осуществлён возврат к инвентарю.

1.5 Информация об уровне

Enigma хранит гораздо больше сведений о каждом уровне, чем можно отобразить в меню уровней. Эти сведения можно просмотреть с помощью инспектора уровней. Его можно вызвать, щёлкнув правой кнопкой мыши (или любой кнопкой мыши + Ctrl) по эскизу уровня в меню уровней.

Помимо названия и автора уровня Enigma приводит публичный рейтинг уровня, различные типы баллов, информацию о версии уровня, размещении файла уровня и др. Также в инспекторе уровней можно ввести своё примечание к уровню. Из инспектора уровней можно просмотреть и сделанные снимки экрана уровня.

1.5.1 Публичные рейтинги

Большинство уровней игры оцениваются по пяти различным категориям:

• инт = Интеллект
• ловк = Ловкость
• терп = Терпение
• знан = Знание игры
• скор = Скорость и контроль над скоростью

Мы используем сокращения, чтобы подчеркнуть отличие наименований категорий рейтинга от повседневных значений этих слов. В каждой из этих категорий уровни оцениваются по пятибалльной шкале от 1 (лёгкий) до 5 (сложный), за исключением категории ‘знан’, где уровням может присваиваться 6 баллов (уникальный механизм).

Пожалуйста, имейте в виду, что строго придерживаться приведённых ниже критериев в почти 750 случаях чрезвычайно затруднительно, поэтому в отдельных уровнях могут быть (и будут) отклонения от них.

Интеллект (инт)

Этот рейтинг отражает творческие и аналитические способности, а также способность к планированию, необходимые для решения уровня. Интеллект сам по себе довольно сложное понятие, которое не так-то легко сразу понять или оценить. Следовательно, фиксированные определения каждого пункта оценочной шкалы не только желательны, но и необходимы при выставлении оценок. Допустим, вам известны все отдельные элементы уровня. Задайте себе следующие вопросы:

• Понятно ли мне решение сразу же? Да -> инт 1
• Требуется ли от меня только сориентироваться на местности, например проверить, куда ведут телепорты или для чего служат переключатели? -> инт 2
• Существует ли стандартный алгоритм решения проблемы, например, нужно найти спрятанный предмет или выход из лабиринта? -> инт 3
• Не работают ни метод проб и ошибок, ни стандартные алгоритмы; это простой пример кода или требуется предварительное планирование? -> инт 4
• Это сложный код, цепочка шаблонов или причинно-следственных связей? -> инт 5

Высокие рейтинги обычно присваиваются головоломкам. Инт-рейтинги не накапливаются: рейтинг уровня определяет его самая сложная задача.

Ловкость (ловк)

Для решения многих уровней вам потребуются, главным образом, точные движения мышкой или терпение. В данном случае под ловкостью мы понимаем не "аккуратность в противоположность поспешным, нетерпеливым движениям", а точность, необходимую, чтобы избежать смерти. Таким образом, данный рейтинг учитывает все потенциальные смертельные опасности уровня, не только пропасти и смертоносные камни, но и, например, потенциальную возможность случайно толкнуть нужный камень в угол, достать из которого его невозможно.

• Не важно, к чему я прикасаюсь, здесь мне абсолютно ничего не грозит. -> ловк 1
• Здесь есть смертельные опасности, но их несложно избежать. -> ловк 2
• На уровне есть потенциальные опасности, сравнимые с узким мостом над пропастью. -> ловк 3
• На уровне есть потенциальные опасности, сравнимые с необходимостью передвинуть камень направо, когда слева от вас пропасть, или пройти по узкому проходу между смертоносными камнями. -> ловк 4
• Чтобы решить уровень, нужно множество попыток. -> ловк 5

В противоположность инт-рейтингам, данные рейтинги могут накапливаться: так, уровень, на котором имеется множество опасностей, оцениваемых в три балла, в результате может получить 4 или даже 5. Роторы в уровнях также ассоциируются с рейтингами ловкости ‘ловк’ и скорости (‘скор’). Поэтому уровни с комбинацией из ‘ловк-скор’ в основном подвижные и активные, тогда как комбинации с высокими ‘ловк-терп’ характерны для лабиринтов.

Терпение (терп)

Терпение — это субъективный рейтинг; он в большей степени отражает "ощущение времени", много ли времени потребовалось для решения уровня, исходя из субъективных ощущений игрока. Таким образом, два однотипных уровня могут иметь различные терп-рейтинги, если, например, у одного из них более привлекательный дизайн или прогресс игрока на нём более очевиден (например, сразу видно количество открытых оксидов). Необходимость много раз начинать уровень заново оказывает существенное влияние на этот рейтинг; важно не время в нижнем левом углу экрана и не счёт, а субъективное ощущение времени, прошедшего с момента, как вы впервые окинули уровень взглядом, до завершения уровня.

• Я решил уровень сразу же, как только понял, что от меня требуется. -> терп 1
• Мне потребовалось некоторое время, но было не скучно. -> терп 2
• Да, мне пришлось потратить достаточно времени на этот уровень, но дизайн здесь симпатичный... -> терп 3
• Я знаю, что здесь нужно делать, но, похоже, этот уровень никогда не кончится. -> терп 4
• Для этого уровня нужны стальные нервы. -> терп 5

Большое количество оксидов на уровне может повысить его терп-рейтинг или же понизить его: если игроку нужно обойти уровень несколько раз, чтобы открыть все пары оксидов, это определённо повышает рейтинг. Однако, если оксиды расположены так, чтобы отмечать прогресс игрока, и являются своего рода наградой за пройденные этапы, они могут понизить терп-рейтинг. То же самое и с уровнями, на которых имеется большое количество дверей: решающим фактором является их расположение.

Высокие терп-рейтинги обычно присваиваются лабиринтам. В сочетании с "инт 3" высокий терп-рейтинг обычно свидетельствует о наличии на уровне спрятанного предмета или полого камня. Терп-рейтинги относятся ко всему уровню, так что они не могут накапливаться.

Знание игры (знан)

Рейтинг знания игры в основном учитывает функции и способы взаимодействия различных объектов игры, таких как камни, покрытия, предметы и актёры. Однако в некоторых случаях он учитывает и особые способы решения уровней. Основой при выставлении рейтинга является уровень "Advanced Tutorial", которому присвоен рейтинг "знан 3". Рейтинг "знан 4" присваивается уровням, на которых встречаются стандартные объекты, отсутствующие в "Advanced Tutorial". Уровни с рейтингом "знан 5" требуют более глубокого знания внутренних закономерностей игры. И, наконец, рейтинг "знан 6" является показателем уникальных либо редко встречающихся способов решения уровня. Общий знан-рейтинг уровня определяется по наиболее сложным объектам или способам решения, встречающимся на нём, и, таким образом, не накапливается:

1. Управление одним шариком на обычных покрытиях, обычные стены, оксиды, оксидоподобные камни, смертоносные камни, вода, пропасть, документы, использование инвентаря, неизменная гравитация, видимые склоны.
2. Перемещение камней, несложные задания а-ля "Сокобан", постройка мостов через воду и пропасть, соединённые камни-мозаики, управление более чем одним шариком, медитация, решётки, роторы и волчки, невидимые склоны, триггеры и переключатели, двери, отверстия (кроме сделанных динамитом), болото, дискеты и камни для дискет (st-floppy), ключи и замки, монеты и отверстия для монет, трещины в полу, камни-таймеры.
3. Различные типы покрытий с различным трением и силой мыши, космос, лёд, инверсное покрытие, сочетание тонущих и плавучих камней, чёрные решетки, не пропускающие роторы и волчки, динамитные шашки, камни, которые можно взорвать с помощью динамита, лопаты, болдеры, волшебные палочки, изменяющие направление движения болдеров, необходимость загнать болдеров в пропасть, стекло, ложки, актёры и предметы, прячущиеся под подвижными камнями, маленькие белые шарики (не опасные), улицы определённого цвета с односторонним движением, импульсные камни ("бамперы"), роторы, перелетающие через пропасть, выхлопные камни, мечи и рыцари, лазеры, неподвижные и подвижные зеркала, трансформация предметов и монет под воздействием веса и лазера, зонтики, позволяющие перелетать через пропасть, молотки и бьющиеся камни (хотя и отсутствуют в "Advanced Tutorial").
4. Постройка мостов на болотах, резиновые ленты, ленточные камни, камни-ножницы, разъединённые камни-мозаики, взрывающиеся камни-мозаики, изменение расположения камней-мозаик (волшебной палочкой и без неё), пружины (оба типа — напольные и встроенные, как на уровне "Upstream Journey"), воры, сёгун-камни из трёх частей, камни-невидимки, полые камни, камни-хамелеоны, предметы, спрятанные под камнями-хамелеонами, камни, замаскированные под другие камни (например фальшивые смертоносные камни), телепорты, магниты, необходимость использовать клавишу <F3> для решения уровня, символы Инь-Ян, одноцветные камни, камни Инь-Ян, обратные камни Инь-Ян, камни, которые можно разбить только шариком определённого цвета, шарики-убийцы, обменные камни, камни для кисточки и рисования, изменение направления на улице с односторонним движением при помощи волшебной палочки, превращение камней в стекло при помощи волшебной палочки, импульсные камни (подвижные, статичные и полые), чёрные и белые бомбы, камни-бомбохранилища, огонь, огнетушители, вращающиеся камни, жёлтые антиобменные камни, мины, флажки, семена, гири, необходимость положить объект под однонаправленные и другие полые камни, электрические камни, турникеты, почтовые камни и каналы связи, кольца (для одного и нескольких игроков), вулканы, сумки, генерирование случайного набора объектов (как возможный результат действия переключателя), лошади (актёры) и камни, через которые лошади могут проходить, шипы, бананы, вишни (необходимы, чтобы сделать шарик невидимым), сюрпризы.
5. Трещины, напольные пружины, телепорты и т. д. — все предметы, семена растут внутри камней, лазер блокируется всеми предметами, шарики-убийцы не тонут в воде, столкновения, подобные тем, которые присутствуют на уровне "Space Meditation", необходимость удерживать кнопку мыши, невидимость как способ пройти сквозь стекло, прыжки через лазеры...
6. Плюющиеся камни, камни-сюрпризы, уровни типа "Enigris" или "Flood Gates" ...

"Знан 6" не обязательно означает, что уровень сложен для понимания; уникальный объект или механизм может быть и интуитивно понятным, как, например, во "Flood Gates".

Скорость и контроль над скоростью (скор)

Скор-рейтинг отражает не только максимальную скорость, которая требуется от игрока (например, когда вам нужно убежать от ротора), но и степень контроля над мышью, которой обладает игрок. Отличными примерами применения второго критерия являются уровень "Mourning Palace" и средняя часть "Sacrifice". Этот критерий учитывает необходимость двигать мышью с постоянной скоростью на протяжении длительного времени, а также необходимость правильной оценки скорости, требуемой для выполнения определённого задания (например, разбить стекло).

1. Никаких ограничений по времени.
2. Не останавливайтесь надолго. Вас, к примеру, может кто-нибудь преследовать на невысокой скорости.
3. Присутствует умеренное ограничение по времени либо необходимость контроля над скоростью. Это может быть один не очень быстрый ротор на открытой территории.
4. Не останавливайтесь! На уровне могут быть, к примеру, задания с ограничением по времени или роторы (один быстрый либо несколько медленных).
5. Скорее! Если "скор 4" означает, что уровень сложный, но решаемый, то рейтинг "скор 5" применяется для уровней, для которых данное определение было бы очень сильным преуменьшением.

Скор-рейтинг накапливается, так как множество медленных роторов могут в сумме составить задание, по сложности подпадающее под "скор 3" или "скор 4", а несколько медленных таймеров-переключателей, которые нужно нажать в определенном порядке, могут представлять собой задание, находящееся на пределе человеческих возможностей. В отличие от остальных категорий, для которых средний рейтинг приближается к 3 (или находится между 3 и 4 для знан), большинство уровней определённо подпадают под определение "скор 1". Таким образом, скор-рейтинг можно, скорее, рассматривать как приложение к трём основным рейтингам: инт, ловк и терп.

Совокупность рейтингов

Иногда бывает интересно определить общую шкалу, по которой можно измерить сложность уровня. Простейший способ вычислить такой общий рейтинг — это выбрать линейную комбинацию пяти отдельных рейтингов, взятых с определёнными коэффициентами. Эти коэффициенты должны соответствовать тому вкладу, который данная категория вносит в общую сложность уровня. Но коэффициенты следует выбирать с осторожностью, чтобы избежать теоретических казусов при вычислении (к примеру, если коэффициенты для всех рейтингов, кроме скор, являются чётными, мы получим заметное различие в распределении чётных и нечётных общих рейтингов, что может заметно исказить картину). Ниже мы приводим работающую и чрезвычайно интересную линейную комбинацию, которую мы применяли для изменения порядка следования уровней:

общая сложность  =  7*инт + 6*ловк + 4*терп + 3*знан + 4*скор - 23

Особенностью данного способа вычисления общего рейтинга является то, что он распределяет уровни по относительно широкой и непрерывной шкале от 1 (все рейтинги равны 1) до 100 (все рейтинги 5, знание 6) и основной упор в нём сделан на самые сложные категории — интеллект и ловкость. Однако некоторые очень низкие и очень высокие значения (например 2 и 99) не могут встречаться в этой комбинации. Другие комбинации позволяют получить полную, но узкую, либо широкую, но не являющуюся непрерывной шкалу.

1.5.2 Баллы

В колонке баллов находятся ваши баллы, а также некоторые сравнительные величины для нормального и лёгкого режимов (если уровень поддерживает лёгкий режим).

Мировой рекорд — это лучшее время прохождения уровня, которое было прислано команде разработчиков Enigma. Мировые рекордсмены перечислены под колонкой с баллами.

PAR — это профессиональный усреднённый рейтинг (professional average rating) уровня. Это гармоническое среднее всех баллов, которые были присланы нам игроками. Однако мы учитываем только баллы, набранные игроками, которые решили определённое количество уровней. В отличие от мирового рекорда, побить который очень сложно, PAR представляет собой куда более достижимую цель для амбициозного игрока. Уровни, пройденные за время, равное PAR либо лучшее, чем PAR, отмечаются изображением ускоряющегося шарика в меню уровней.

Ещё один тип сведений в данной колонке — это авторское время. Большинство авторов не ставят себе цели удерживать мировые рекорды для своих собственных уровней. Однако им обычно известен кратчайший путь решения уровня. Если ваше время значительно превышает авторское, то для этого уровня, вполне возможно, существует более простое решение.

Количество решивших — это количество игроков, которые решили данную версию уровня.

Процент решивших — это отношение количества игроков, решивших данный уровень, к общему количеству игроков, приславших нам свои баллы. Мы учитываем только тех игроков, у которых была возможность решить данный уровень. К примеру, игроки, которые прислали нам свои баллы до написания уровня и после их не обновляли, нами не учитываются. Низкий процент решивших указывает на то, что решить уровень не так-то просто.

1.5.3 Версии

В колонке "Версия" содержится подробная информация об уровне. Обратитесь к разделам <version> и <modes> главы Основы работы с уровнями, где объяснены приведённые в колонке значения.

Для игрока наибольший интерес представляет строка ‘Номер версии’. На эскизе уровня, который решён за определённое время, после обновления Enigma может появиться красный треугольник. Хотя медали, которые указывают на то, что уровень решён, и присутствуют в меню уровней, баллы больше не указываются. Это происходит из-за того, что обновлённый уровень требует нового решения и баллы, набранные при решении предыдущего уровня, к нему неприменимы. В таких случаях автор увеличит номер версии уровня.

1.5.4 Личные примечания и оценки

В этом поле можно ввести свою аннотацию уровня, которую можно изменить при повторных попытках пройти уровень. Обратите внимание, что нынешние возможности текстового поля ограничены (нельзя ввести некоторые символы, и курсор при введении текста должен оставаться в границах поля). Тем не менее, это поле подходит для ввода кратких примечаний, которые могут пригодиться позже.

Примечания хранятся в вашем персональном файле ‘state.xml’. Для каждого уровня, вне зависимости от его версии, можно ввести только одно примечание.

Кроме того, уровням можно выставлять оценки. Просто нажмите на кнопку "Рейтинг". Можно выставлять оценки от 1 до 10, знак ‘-’ означает "воздержался". 0 означает очень плохой уровень, в который, по вашему мнению, не стоит и играть, 5 обозначает средний уровень, 10 — самый лучший. Старайтесь использовать все значения при выставлении оценок.

Ваши оценки хранятся вместе с баллами и обрабатываются анонимно. Средняя оценка, полученная после обработки всех оценок, выставленных уровню игроками, выводится для вашего сведения. Обратите внимание, что для различных версий уровня возможны разные оценки, так как уровни могут улучшиться под влиянием комментариев пользователей. Если вы не выставили оценку новой версии уровня, Enigma оставляет оценку, которая была выставлена предыдущей версии.

1.5.5 Снимки экрана

Играя на уровне, можно делать снимки экрана при помощи клавиши <F10>. Можно сделать целую серию снимков экрана, чтобы получить документальные свидетельства об игре. Каждый снимок экрана программа сохраняет под уникальным именем файла. При помощи инспектора уровней можно просматривать снимки экрана прямо из игры. Просто нажмите на кнопку <Снимок экрана> для просмотра первого изображения.

Так как кнопки могут помешать просмотру, управление игрой в данном режиме осуществляется исключительно с помощью клавиатуры. Нажмите <F1> для вызова экрана помощи, <ESC>, чтобы вернуться к инспектору уровней, <Page Up> и <Page Down> для просмотра, соответственно, предыдущего и следующего снимка экрана. Если продолжить просмотр после показа последнего снимка экрана, "недостающий" файл снимка экрана получит имя. Это может быть полезной подсказкой, где искать другие файлы снимков экрана в вашей ‘папке эскизов’ (см. раздел Размещение ресурсов).

1.6 Гандикап и пар (PAR)

В то время как PAR описывает степень сложности уровня (см. раздел Баллы), гандикап (‘гкп’) описывает способность решать уровни в рамках PAR. Гандикап всегда привязан к пакету уровней либо группе пакетов. Свой гандикап для каждого пакета в меню уровней можно узнать, выбрав режим соответствия (нажимайте на кнопку в нижнем левом углу экрана, пока не появится изображение ускоряющегося чёрного шарика). Гандикап выводится в правом верхнем углу экрана вместе с количеством уровней, которые решены ниже PAR.

Гандикап в Enigma напоминает гандикап, используемый в гольфе. Чем он ниже, тем лучше. Если решить все уровни за время, равное PAR, гандикап будет равен 0. Если их решить за время, лучшее, чем PAR, гандикап будет выражаться отрицательным числом. Игроки могут использовать гандикап для сравнения своего мастерства.

Для тех, кто хочет узнать больше о PAR и гандикапе, ниже мы приводим дополнительную информацию. Остальные могут её пропустить и перейти к следующей главе Основы работы с пакетами уровней.

Мы просим всех игроков присылать нам свои баллы. Все присланные баллы учитываются при определении мировых рекордов и подсчёте процента и количества игроков, решивших уровень.

Однако при подсчете PAR мы учитываем баллы только тех пользователей, которые решили более определённого количества уровней (на данный момент примерно 10% всех уровней). Для каждого уровня мы подсчитываем гармоническое среднее баллов, набранных ‘профессиональными игроками’. Профессионалы, не решившие уровень, учитываются при подсчете с баллами в 10 раз большими, чем мировой рекорд. Гармоническое среднее вычисляется по формуле:

гарм.средн. = N / (sum_[j=1..N] 1/баллы_j) )

При таком способе подсчёта меньшее время прохождения уровня соответствует более высоким величинам, чем большее время.

Гандикап — это сумма величин, которая описывает соответствие баллов рейтингу PAR. Поскольку необходимо учитывать, что для каких-то уровней баллов у вас может и не быть либо PAR может отсутствовать, мы ввели несколько исключений:

Обратите внимание, что всем баллам, лучшим, чем PAR, соответствует отрицательная величина, таким образом они уменьшают общую величину гандикапа. Для пакета, состоящего из 100 уровней, гандикап может быть в пределах от +100 до -300. Для пакетов, состоящих из большего либо меньшего количества уровней, Enigma применяет коэффициент "100/размер пакета" для получения сравнимых величин гандикапа. Гандикапы указываются с точностью до одной десятой.

1.7 Пользовательские наборы звуков

(Следующая информация действительна только для версии Enigma 1.01 и выше.) Звуковые эффекты вызываются так называемыми ‘звуковыми событиями’ (‘sound events’). У этих звуковых событий обычно есть имя (например ‘dooropen’ — открытие двери) и ассоциированное размещение (координаты двери), которые влияют на проигрывание звукового эффекта. Собрание всех аудио файлов, их соотнесение со звуковыми событиями, а также некоторая дополнительная информация по их использованию называется ‘набором звуков’ (‘sound set’).

Можно использовать свои собственные аудиофайлы для создания персональных наборов звуков Enigma и выбирать между наборами звуков в меню настроек (опция ‘Набор звуков’). Эти наборы звуков можно распространять на условиях любой лицензии, а также устанавливать наборы звуков, созданные другими пользователями. В игре не предусмотрено никаких ограничений на количество установленных наборов звуков.

Звуковое событие конвертируется в звуковой эффект с помощью таблиц. Эти таблицы можно найти в файле ‘data/sound-defaults.lua’, а также в пустом файле сэмплов ‘reference/soundset.lua’. Каждый пункт в этих таблицах представляет собой либо строку типа ‘enigma/st-coinslot’, которая понимается программой как файл ‘soundsets/enigma/st-coinslot.wav’ с некими свойствами по умолчанию, либо список звуковых атрибутов в фигурных скобках. Звуковые события, вызываемые с помощью сообщения sound, конвертируются таким же способом. Ниже мы приводим пример подобного пункта таблицы:

dooropen = { file="my_soundset/open-door", volume=0.9, priority=4 },

Данные атрибуты имеют следующие значения:

• ‘file’ Путь и имя файла для данного события (без расширения ‘.wav’).
• ‘volume’ Громкость звука: 1.0 — по умолчанию, 0.0 — звук выключен.
• ‘priority’ Если одновременно активны несколько эффектов, то эффекты с высоким приоритетом могут замещать эффекты с более низким приоритетом. Задайте приоритет при помощи целых чисел от 1 до 10 (по умолчанию - 1). Эта опция ещё не работает в Enigma 1.01.
• ‘global’ Может являться истинным ‘true’ или ложным ‘false’. Если ‘true’, стерео эффекты и затухание отсутствуют. Используется для звукового сопровождения меню, финалов уровней и т. д. По умолчанию задано ‘false’.
• ‘loop’ ‘true’ или ‘false’. Если ‘true’, звуковой эффект повторяется бесконечное количество раз, пока его не отменят. По умолчанию задано ‘false’.
• ‘damp_max’, ‘damp_inc’, ‘damp_mult’, ‘damp_min’, ‘damp_tick’ Параметры приглушения звуков. Звуки, издаваемые шумными объектами, такими как камни-наездники, в игре приглушаются. Для этого подсчитывается частота звука. ‘damp_max’ задаёт максимальный коэффициент приглушения (чем выше коэффициент, тем тише звук), ‘damp_inc’ задаёт скорость нарастания приглушения, ‘damp_mult’ — общий коэффициент, ‘damp_min’ задаёт нижнюю границу для записей о приглушении (если значения расположены ниже этой границы, то они стираются из памяти), а ‘damp_tick’ продолжительность (десятых секунды). Более подробную информацию смотрите в файле ‘sound.hh’. По умолчанию: 10.0, 1.0, 1.0, 0.5, 0.9.

Чтобы создать новый набор звуков, следуйте следующей инструкции:

1. Создайте новую папку, содержащую копию файла сэмплов ‘soundset.lua’ и wav-файлы, которые вы хотите использовать.
2. Переместите её в папку "soundsets", находящуюся в вашей пользовательской папке (возможно, придётся её создать). Структура директории должна выглядеть примерно так:

   (папка пользователя)/soundsets/my_sounds/ /soundset.lua /high_pitch.wav /soundfile_13.wav ...

3. Запустите игру и выберите ‘My Soundset’ в меню настроек. Так как в данном наборе звуков звуковые эффекты не ассоциированы с wav-файлами, звук должен отсутствовать.
4. Отредактируйте файл ‘soundset.lua’ по своему усмотрению. Можно использовать звуковые файлы по умолчанию, например:

   ... coinsloton = { file="enigma/st-coinslot" }, ...

   Если используете свои собственные файлы, не забудьте создать соответствующие подпапки, например:

   ... coinsloton = { file="my_sounds/soundfile_13" }, ...

   Ни в коем случае не указывайте расширение ".wav"! Оно добавляется автоматически. Проверьте, чтобы расширение было написано строчными буквами.

5. Замените ‘MY_SOUNDSET’ подходящим именем переменной, а ‘My Soundset’ — именем, которое вы хотите видеть в меню звуковых настроек. Не делайте его слишком длинным, чтобы оно уместилось на кнопке. Три переменных-идентификатора, имя кнопки и имя директории не обязательно должны быть одинаковыми, но похожие имена, уникальные для каждого набора звука, облегчают жизнь другим разработчикам.

Не забудьте выбрать нужный набор звуков в меню настроек всякий раз, когда вы переименовываете его. И всегда выходите из игры, когда вносите изменения в набор звуков: Enigma не определяет новые наборы звуков без перезапуска.

У вас есть право свободно распространять zip-архивы, содержащие ваш набор звуков и файл ‘soundset.lua’. Новый набор звуков можно установить из архива, просто распаковав его в поддиректорию ‘soundsets’ вашей папки пользователя. Убедитесь, что файл ‘soundset.lua’ находится на одну поддиректорию ниже, чем ‘soundsets’. Деинсталлировать набор звуков можно, просто удалив соответствующую папку. Если вы хотите сделать набор звуков невидимым для Enigma, одного только переименования директории недостаточно, следует переименовать и файл ‘soundset.lua’. Это может пригодиться, если вы используете взаимозависимые наборы звуков (звуковые наборы, использующие общие файлы) и хотите сделать недоступным только один из них.

2. Основы работы с пакетами уровней

Теперь, после ознакомления с основами работы с Enigma, вам, наверное, будет интересно узнать, как уровни организуются в пакеты и как можно добавить уровни либо пакеты уровней в игру.

Пакеты уровней — это отсортированные коллекции уровней, состоящие из указателя и (необязательно) приложенных к нему источников уровней. Не все источники уровней должны обязательно находиться в самом пакете. В пакете уровней могут использоваться перекрёстные ссылки на уровни из других пакетов. Если пакет не содержит собственных источников и состоит исключительно из перёкрестных ссылок, уместно называть его перекрёстным указателем, поскольку он представляет собой только файл-указатель.

Приведённое выше описание соответствует всем версиям Enigma. Однако вплоть до версии 0.92 пакеты уровней нужно было редактировать вручную, а регистрация пакетов была сложным процессом. Поэтому для версии Enigma 1.00 мы решили переписать всю систему пакетов, постаравшись сделать её гибкой и лёгкой в использовании. Мы преследовали следующие цели:

• пакет уровней ‘Auto’, который позволял бы добавлять уровни путём перетаскивания исходного уровня
• добавление пакетов уровней путём копирования файлов в папку пользователя
• автоматическое определение всех пакетов без необходимости прибегать к редактированию регистрационного файла
• уровни, задаваемые из командной строки, как стандартный пакет
• пакет уровней ‘History’ (История) с перекрёстными ссылками на последние сыгранные уровни
• вывод результатов поиска в виде пакета с перекрёстными ссылками
• пакеты уровней в формате zip, являющиеся архивами директорий с пакетами и файлами уровней
• группировка пакетов уровней в меню
• встроенный инструмент для создания и редактирования пакетов
• обновление пакетов без необходимости обновления самой игры
• автоматическое преобразование пакетов уровней из Enigma 0.92

Некоторые из этих функций работают автоматически. Их можно задействовать прямо из меню уровней. Для использования других необходимо знать, где размещать файлы. Более подробная информация приводится в следующих разделах:

2.1 Начало работы с пакетами уровней

Одна из наиболее выдающихся черт Enigma — это возможность добавлять в неё новые уровни. А сообщество пользователей обычно присылает нам несколько новых превосходных уровней каждую неделю.

Добавить новый уровень, полученный в виде XML-файла, очень просто. Найдите поддиректорию ‘levels/auto’ в вашей ‘папке пользователя’ (см. раздел Размещение ресурсов), скопируйте файл уровня в эту папку и перезапустите игру. Новый уровень появится в пакете ‘Auto’ и в него можно будет сыграть точно так же, как и в любой другой.

Обратите внимание, что для уровней, содержащих ошибки либо несовместимых с данной версией, в меню уровней отображается значок ошибки. Естественно, при попытке сыграть в уровень будет получено сообщение об ошибке Просмотрите метаданные уровня в инспекторе уровня (см. раздел Информация об уровне), чтобы определить совместимую версию, и свяжитесь с автором уровня по электронной почте в случае наличия ошибок в коде.

Второй способ сыграть в новые уровни — это добавить адреса файлов этих уровней в командную строку (см. раздел Опции запуска). Так можно играть в уровни, которые хранятся где угодно, можно даже вводить URL уровней, размещённых в Интернете. Уровни, добавленные в командную строку, находятся в пакете ‘Startup Levels’.

При желании сыграть в уровень Lua, написанный с использованием устаревшего формата для Enigma 0.92 или более ранней версии, можно попытаться запустить его из командной строки. В таких уровнях отсутствуют необходимые метаданные для автоматического определения. Однако уровни, заданные из командной строки, воспринимаются игрой как временные, доступные только для одного запуска; недостающие данные заменяются уместными данными по умолчанию. Такой уровень, возможно, запустится, но сохранение баллов, копирование и ссылки на уровень будут невозможны.

Помимо отдельных новых уровней в сообществе пользователей могут распространяться целые пакеты. Эти пакеты могут представлять собой папки с уровнями, zip-архивы или отдельные XML-файлы. Все пакеты могут быть установлены простым копированием файлов, но между этими тремя форматами существуют различия.

Пакеты уровней, распространяемые в виде папок с файлами уровней и файлом-указателем, следует копировать в папку ‘levels’ в вашей папке пользователя (см. раздел Размещение ресурсов).

Пакеты уровней, распространяемые в виде zip-архивов, следует копировать в папку ‘levels’ в вашей папке пользователя. Распаковывать их не обязательно, хотя это и возможно (см. раздел Пакеты в формате zip).

Пакеты уровней, распространяемые в виде отдельных файлов-указателей XML, следует копировать в папку ‘levels/cross’ в вашей папке пользователя.

Все новые пакеты должны быть доступны из меню пакетов уровней после перезапуска Enigma.

Это всё, что нужно знать для того, чтобы добавлять новые уровни и пакеты уровней для тестирования и игры. Если вы заинтересованы прежде всего в том, чтобы создавать новые уровни, то стоит сразу же обратиться к главе Основы работы с уровнями. В остальных же разделах этой главы объясняется, как размещать и сортировать уровни в пользовательских пакетах.

2.2 Конвертирование пакетов из версии 0.92

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

Если раньше вы хранили пакеты в папке системных файлов Enigma, то из старой версии игры их нужно скопировать в поддиректорию ‘levels’ в папке пользователя (см. раздел Размещение ресурсов). Пользовательская папка существует на всех системах, и, начиная с версии 1.00, Enigma никогда не вносит изменения в системную директорию файлов уровней; обновления и преобразование она выполняет только в папке пользователя. Если пакеты были внесены в файл ‘index.lua’ в системной директории, то нужно скопировать регистрационные строки в файл ‘index_user.lua’, который следует хранить в папке пользователя.

Если у вас было несколько пакетов уровней, в Enigma 0.92 их можно было хранить в различных поддиректориях папки ‘levels’. Однако, поскольку можно было хранить все файлы уровней и различные указатели в самой папке ‘levels’, с автопреобразованием возникнут трудности, так как Enigma 1.00 допускает только один пакет уровней с приложенными файлами уровней в каждой папке. В подобных случаях мы рекомендуем поэтапное преобразование: на каждом этапе конвертируйте только один старый указатель. Enigma сконвертирует этот указатель в новый файл ‘index.xml’. Переместите полученный указатель в соответствующую папку вместе с уровнями и приступайте к преобразованию нового пакета.

Следует отдельно рассмотреть случаи, когда указатель в папке ‘levels’ содержал ссылки на уровни, хранящиеся в различных поддиректориях папки ‘levels’. Поскольку в Enigma 0.92 не применялись перекрёстные указатели, а Enigma 1.00 требует, чтобы все файлы уровней пакета хранились в отдельной папке, алгоритму преобразования приходится самому определять нужную папку. Он просто берёт поддиректорию первого уровня. Если это не подходит, то перед преобразованием нужно очистить пакет из версии 0.92.

Все прочие стандартные пакеты уровней Enigma конвертирует без особых проблем. Преобразование она выполняет только один раз. После создания нового файла ‘index.xml’ используется только этот указатель. Следовательно, после тщательной проверки старый ‘index.txt’ может быть удалён. Мы рекомендуем сохранять резервную копию старого индекса до окончательного перехода на Enigma 1.00.

Если вы использовали персональный пакет уровней в формате zip, то вы найдёте поддиректорию с именем zip-архива в папке ‘levels’. В этой папке Enigma сохраняет конвертированный файл ‘index.xml’. Вам, скорее всего, придётся заменить старый ‘index.txt’ в zip-архиве на новый указатель. После этого поддиректория может быть полностью удалена, так как Enigma будет загружать указатель прямо из zip-архива.

После окончания конверсии пакетов мы настоятельно рекомендуем обновить уровни до нового формата XML (см. раздел Основы работы с уровнями).

2.3 Пакеты в формате zip

Помимо классических пакетов уровней, представляющих собой поддиректорию папки ‘levels’ с файлом ‘index.xml’ и несколькими файлами уровней, в Enigma 1.00 предусмотрен совместимый формат zip-архивов. Zip-формат позволяет уменьшить размер ресурсов игры и облегчает распространение пакетов.

Этот формат стопроцентно совместим. Если у вас есть обычный пакет уровней, размещённый в поддиректории, то можно просто заархивировать всю папку и назвать архив её именем с расширением .zip. Теперь эту папку можно полностью удалить: Enigma автоматически определит пакет уровней и позволит играть в него без ограничений. Сохранятся даже перекрёстные ссылки на этот пакет.

С другой стороны, Enigma предоставляет возможность превратить заархивированный пакет в папку с указателем и файлами уровней. Опять же, на уровнях из пакета можно играть без ограничений и все перекрёстные ссылки сохраняются.

Если сохранить и архив, и папку, то файлы папки обладают приоритетом перед архивом. Таким образом, Enigma сохраняет обновления в поддиректориях параллельно с существующими zip-архивами.

2.4 Группировка и сортировка пакетов

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

• Enigma — уровни, написанные специально для Enigma
• Déjà-vu — уровни, которые можно было увидеть и раньше
• Sokoban
• Facets — уровни из перечисленных выше пакетов, сгруппированные по каким-либо иным признакам
• User — личные уровни и пакеты уровней (например пакеты History и Auto, автоматически генерируемые системой для пользователя).
• Development — шаблоны и незаконченные уровни от команды Enigma
• All Packs — Все пакеты

Тем не менее, своё мнение мы не навязываем. Вы вольны переименовывать группы, добавлять новые и изменять расположение пакетов. Как и в случае с другими аспектами Enigma, управлять пакетами и группами пакетов можно, щёлкнув любой кнопкой мыши + Ctrl либо одной правой кнопкой по кнопке соответствующего пакета или группы.

В меню конфигурации групп можно переименовать группу либо изменить её расположение. Группе можно выбрать любое имя, которое ещё не использовалось, не заключено в квадратные скобки и отличается от ‘Every Group’. Обратите внимание, что, возможно, вам не удастся ввести все желаемые символы. Приносим извинения за это неудобство.

В меню конфигурации пакетов можно поместить пакет в какую-либо группу. Список групп содержит два специальных пункта: ‘[Every Group]’ и ещё одно имя в квадратных скобках. При выборе первой псевдогруппы пакет уровней отображается в каждой группе. Это является размещением по умолчанию группы ‘Startup Levels’. Второе имя в квадратных скобках — это группа, в которой по умолчанию размещается сам пакет уровней. Это подсказка, которая позволит переадресовать пакет уровней в группу по умолчанию, даже если удалить саму группу.

2.5 Создание новых пакетов уровней

Чтобы создать новый пакет уровней, выберите группу, в которую следует этот пакет добавить. Скорее всего, это будет группа ‘User’. Щёлкните любой кнопкой мыши + Ctrl или одной правой кнопкой по группе, затем нажмите на кнопку ‘Новый пакет’. На экране отобразится меню конфигурации пакетов, где можно ввести все данные, необходимые для создания пакета уровней.

Вначале нужно ввести имя пакета. Здесь также есть ограничение в выборе символов, которые можно использовать для имён файлов. Разрешается использовать алфавитно-цифровые символы A-Z, a-z, 0-9, пробелы, "_" и дефис. Обратите внимание, что позже вы сможете переименовать пакет, если захотите дать ему более удачное или более подходящее имя (см. раздел Изменение и удаление пакетов).

После этого следует определить, хотите ли вы создать пакет, в котором могут находиться источники уровней или только перекрёстные ссылки. Первый вариант удобен для хранения самостоятельно написанных либо загруженных из Интернета уровней. Пакет с перекрёстными ссылками можно использовать для хранения коллекций своих любимых уровней, для которых просто отбираются существующие уровни из других пакетов, исходя из своих собственных критериев. Нужный тип пакета можно выбрать с помощью кнопки ‘Типы уровней’, которая использует символы для ссылок и копий.

‘Размещение’ — это величина, которая определяет размещение среди групп пакетов, если пакет не был пересортирован вручную (см. раздел Группировка и сортировка пакетов). Эта задаваемая по умолчанию величина имеет значение, только если вы распространяете свой пакет и хотите быть уверенным, что пользователи поместят этот пакет там, где нужно. В большинстве случаев величина, автоматически задаваемая после создания нового пакета, является оптимальной.

Можете указать себя в качестве владельца или создателя пакета. Это просто строка для идентификации.

Наконец, после окончания настройки вы можете создать пакет, нажав кнопку ‘OK’. Enigma создаст новый пакет в папке пользователя (см. раздел Размещение ресурсов).

Если вы решите не создавать новый пакет, нажмите кнопку ‘Отмена’. В этом случае всё останется без изменений.

Если вы хотите сразу же добавить уровни в пакет, нажмите кнопку ‘Составить пакет’. Enigma создаст пакет, и вы сможете использовать составитель пакетов, чтобы наполнить этот пакет уровнями.

2.6 Изменение и удаление пакетов

Чтобы изменить пакет, щёлкните по нему любой кнопкой мыши + Ctrl либо одной правой кнопкой в меню пакетов уровней. На экран будут выведены метаданные всех пакетов. Однако кнопка ‘Ред. метаданные’ появится только для ваших собственных пакетов, которые хранятся в папке пользователя. Нажав на неё, можно отредактировать метаданные.

Пакет можно переименовать, но нельзя изменить имена файлов. Enigma будет использовать новое имя в качестве логического имени пакета, которое отображается в меню.

Другие свойства, которые можно изменить, включают в себя ‘Размещение’ и ‘Владелец’.

Имейте в виду, что изменить тип уже существующего пакета нельзя. Следует создать новый пакет нужного типа и скопировать туда уровни (см. раздел Составление пакетов уровней).

Во избежание случайной потери файлов уровней в игре не предусмотрена функция удаления пакетов. Тем не менее, пакет можно удалить, просто удалив папку с этим пакетом из вашей папки пользователя. Для пакетов, состоящих из перекрёстных ссылок, просто нужно удалить файл-указатель XML в поддиректории ‘levels/cross’ вашей папки пользователя.

2.7 Составление пакетов уровней

Изменения в состав пакета могут быть внесены при помощи составителя пакетов. Его можно вызвать, нажав любой кнопкой мыши + Ctrl либо одной правой кнопкой мыши на кнопку пакета в меню пакетов уровней, а затем на кнопку ‘Составить пакет’ в меню конфигурации пакета.

Составитель выглядит почти так же, как меню уровней, но отличается от него своими функциями. Список всех команд можно вывести на экран с помощью клавиши <F1>. При составлении собственного пакета уровни пакета отображаются в красной рамке. Это предупреждение о том, что вы можете модифицировать этот пакет. В системных пакетах (поставляемых с дистрибутивом Enigma) уровни отображаются в серой рамке, поскольку составитель можно использовать только для того, чтобы скопировать уровни в буфер обмена.

Буфер обмена позволяет выбрать уровни из одного или нескольких пакетов и вставить их в виде копии либо перекрёстной ссылки в свой пакет. Сначала очистите буфер обмена при помощи клавиш ‘Shift + delete’. Затем выберите нужные уровни из составителя. Добавьте их в буфер обмена с помощью ‘Shift + щелчок’. Они отобразятся в строке вверху экрана. Вернитесь в пакет, в который желаете добавить уровни. Выберите уровень, после которого желаете вставить уровни. Используйте клавишу ‘F8’, чтобы вставить уровни из буфера в виде ссылок. При редактировании пакета, в котором допускаются копии уровней, их можно вставить при помощи клавиши ‘F9’.

При внесении каких-либо изменений в пакет уровней в левом верхнем углу экрана появляется маленький красный треугольник. Подтвердить все изменения можно, выйдя из составителя с помощью кнопки ‘OK’. Если выйти из составителя с помощью кнопки ‘Отмена’, то все изменения будут отменены.

Помимо добавления уровней, их можно удалять с помощью клавиши ‘delete’. Имейте в виду, что если удалить уровень, который является файлом, а не просто ссылкой, то Enigma удалит и сам файл уровня. Будьте осторожны с уровнями, на эскизе которых имеется изображение документа. Отменить удаление можно с помощью кнопки ‘Отмена’.

Сортировка уровней осуществляется с помощью клавиш ‘alt + стрелка влево’ и ‘alt + стрелка вправо’. Новый порядок следования уровней отображается на экране незамедлительно, и его можно сохранить, нажав кнопку ‘OK’.

Чтобы обновить индекс уровней, можно воспользоваться клавишей ‘F5’. Это может пригодиться во время редактирования уровня. В пакете отразятся изменения названия, версии, появление простого режима для уровней и т. д. Все уровни пакета Enigma обновляет одновременно.

Используя пакет уровней Auto и составитель пакетов, можно создавать пакеты, состоящие из ваших собственных уровней: создайте новый пакет, добавьте файлы уровней в папку ‘auto’, перезапустите игру, добавьте уровни из папки ‘auto’ в буфер обмена, с помощью составителя вставьте уровни из буфера обмена в свой пакет в виде копии и удалите неиспользуемые файлы уровней из папки ‘auto’.

3. Основы работы с уровнями

Сыграв в несколько уровней Enigma, вы наверняка заметили, что Enigma — довольно динамичная игра с разнообразными уровнями. Поэтому нет ничего удивительного в том, что такие уровни невозможно описать каким-то определённым способом, как простую карту с объектами в Сокобане. Некоторые уровни, такие как лабиринты, каждый раз генерируют свой вид заново и во время каждого сеанса игры выглядят по-разному. Другие уровни предусматривают динамику в процессе игры, например, переключатели могут открывать двери только при определённых условиях. Чтобы обеспечить эти возможности, мы встроили в Enigma мощное и лёгкое расширение языка C — Lua версии 5.1.4.

Вплоть до Enigma версии 0.92 существовало два различных формата уровней. Один из них был XML-подобным форматом, разработанным в основном для сторонних редакторов уровней. Из-за того, что его описание статической карты объектов было неудобно редактировать вручную, многие авторы никогда этот формат не использовали. Вторым форматом был обычный код Lua, который использовался в качестве интерфейса для Lua-функций Enigma по добавлению объектов и функций обратного вызова. Почти все авторы использовали этот формат, но у него был небольшой недостаток: при его использовании хранить метаданные уровня (такие как имя автора, информацию о лицензии и, конечно же, название самого уровня) можно было только в виде неформатированных комментариев Lua, которые нужно было заново вставлять вручную в структуру пакетов уровней.

С XML-икацией Enigma после выхода версии 0.92 мы добились полной поддержки XML, интегрировав Apache Xerces и задались целью избавиться от недостатков старого формата уровней и добавить некоторые новые недостижимые ранее возможности:

• единый формат с необязательными частями — используйте только те части, которые необходимы
• никаких ограничений или существенных изменений для авторов уровней на Lua
• сохранение метаданных, добавленных автором, в самом уровне
• добавление plug & play для пользователей — скопируйте уровень автора и играйте в него без ручного редактирования структуры
• поддержка различных кодировок, таких как US-ASCII, UTF-8, UTF-16, Windows-1252
• интернационализация уровней — позволяет авторам добавить строки на своём родном языке, а переводчиков снабжает всеми строками для перевода и авторскими комментариями, касающимися перевода
• добавление управления выпусками и зависимостями для уровней и библиотек
• добавление поддержки обновления и дополнения уровней и библиотек
• замена старого формата XML гибким интерфейсом для редактирования
• сохранение открытости формата для дальнейших расширений

Позвольте привести пример готового простого уровня ‘Hello World’ в новом формате:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<el:level xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
  <el:protected >
    <el:info el:type="level">
      <el:identity el:title="Demo Simple" el:id="20060210ral001"/>
      <el:version el:score="1" el:release="1" el:revision="2" el:status="stable"/>
      <el:author  el:name="Ronald Lamprecht"/>
      <el:copyright>Copyright © 2006,2009 Ronald Lamprecht</el:copyright>
      <el:license el:type="GPL v2.0 or above" el:open="true"/>
      <el:compatibility el:enigma="1.10"/>
      <el:modes el:easy="false" el:single="true" el:network="false"/>
      <el:score el:easy="-" el:difficult="-"/>
    </el:info>
    <el:luamain><![CDATA[
ti[" "] = {"fl_lawn_b"}
ti["#"] = {"st_box"}
ti["o"] = {"st_oxyd"}
ti["@"] = {"#ac_marble"}

wo(ti, " ", {
    "####################",
    "#                  #",
    "#  o      @     o  #",
    "#                  #",
    "####################",
})
    ]]></el:luamain>
    <el:i18n/>
  </el:protected>
</el:level>

Несложно заметить, что XML-часть содержит все привычные метаданные, поставляемые автором уровня. Это, по сути, формула, которую можно скопировать из шаблона и заполнить.

Код Lua вставлен в XML. Единственное ограничение для Lua-части состоит в том, что для обозначения конца она резервирует ‘]]>’ и может понадобиться заменить его на ‘]] >’. Больше никаких ограничений нет.

Поскольку приведённый выше пример включает в себя все обязательные части XML, скорее всего, нам больше не потребуется вносить существенные изменения для авторов уровней на Lua (как мы того и хотели).

Приведённый пример можно найти в пакете уровней ‘Experimental’ из группы ‘Development’. Исходный код находится в поддиректории ‘levels/enigma_experimental’ системного пути (см. раздел Размещение ресурсов).

Если вы пробуете себя в программировании, используя копию этого уровня в качестве шаблона, то добавьте её в папку Auto (см. раздел Начало работы с пакетами уровней) либо используйте как аргумент в командной строке (см. раздел Опции запуска).

В следующих разделах мы остановимся на подробностях форматирования и поясним необязательные части.

3.1 Общее знакомство с уровнями

Скорее всего, вам хочется понять основные принципы расположения объектов на уровне. Здесь приведено описание очень простого уровня, которое также может служить отправной точкой для новых уровней. (Вообще-то, это первый уровень Enigma, так что можете попробовать сыграть в него прямо сейчас.)

 1    ti[" "] = {"fl_gravel"}
 2    ti["#"] = {"st_box"}
 3    ti["O"] = {"st_oxyd"}
 4    if wo["IsDifficult"] then
 5        ti["Q"] = {"st_quake", name="quake"}
 6        ti["T"] = {"st_timer", interval=10.0, target="quake"}
 7    else
 8        ti["Q"] = ti[" "]
 9        ti["T"] = ti[" "]
10    end
11    ti["@"] = {"ac_marble_black", 0.0, 0.5}
11
12    wo(ti, " ", {
13	"####################",
14	"#                  #",
15	"#                  #",
16	"#  O            O  #",
17	"#         @        #",
18	"#                  #",
19	"#        QT        #",
20	"#                  #",
21	"#                  #",
22	"#  O            O  #",
23	"#                  #",
24	"#                  #",
25	"####################"})

Результат выглядит в игре следующим образом:

Давайте теперь проанализируем эту программу строка за строкой:

 1    ti[" "] = {"fl_gravel"}
 2    ti["#"] = {"st_box"}
 3    ti["O"] = {"st_oxyd"}

Сначала мы объявляем несколько кодов для объектов, которые мы хотим использовать на нашей карте уровня. Просто добавляем каждый код в наше хранилище секций ti и ставим ему в соответствие описание объекта секции, которая в простейшем случае состоит из вида объекта. Двухсимвольная приставка указывает на тип объекта, такой как покрытие, предмет, камень, актёр и т.п.

 4    if wo["IsDifficult"] then
 5        ti["Q"] = {"st_quake", name="quake"}
 6        ti["T"] = {"st_timer", interval=10.0, target="quake"}
 7    else
 8        ti["Q"] = ti[" "]
 9        ti["T"] = ti[" "]
10    end

У вводного уровня есть два режима: обычная сложность и простая. Поскольку обычная сложность отличается от простой всего двумя дополнительными камнями, для этого режима мы добавляем два описания секций.

В сложном режиме мы задаем значения двум описаниям камней. Каждое представляет собой описание камня с дополнительными атрибутами. ‘st_quake’ — это камень, который после прикосновения к нему или срабатывания переключателя закрывает все камни-оксиды. Для того, чтобы к нему можно было обратиться впоследствии, просто назначаем ему имя. Второй камень — таймер, который должен запускаться каждые 10 секунд и посылать своей цели, закрывающему оксиды ‘st_quake’, сообщение о том, чтобы он сменил своё состояние. Поскольку мы присвоили этому камню имя, здесь мы можем использовать в качестве цели его имя.

11    ti["@"] = {"ac_marble_black", 0.0, 0.5}

Теперь мы просто объявляем нашего актёра. Это чёрный шарик, который следует расположить не в левом верхнем углу решётки, а посредине левой границы решётки секций. В принципе, мы хотим просто поместить его в центре уровня. Поскольку размеры одноэкранного уровня составляют 20 x 13, нам следует использовать смещения, указанные выше.

12    wo(ti, " ", {
13        "####################",
14        "#                  #",
15        "#                  #",
16        "#  O            O  #",
17        "#         @        #",
18        "#                  #",
19        "#        QT        #",
20        "#                  #",
21        "#                  #",
22        "#  O            O  #",
23        "#                  #",
24        "#                  #",
25        "####################"})

Теперь можно создать мир, просто указав его карту. Необходимо только вызвать ‘wo’, представление нашего мира, указав для него преобразование секций, код покрытия по умолчанию и карту кодов секций.

Необходимую теоретическую информацию можно найти в разделе Ключевые понятия Enigma, а дополнительные примеры и информацию о синтаксисе в разделе Lua API. Но сперва следует разобраться с метаданными уровня на основе XML.

3.2 XML-структура уровня

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

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<el:level xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd http://enigma-game.org/schema/editor editor.xsd" xmlns:el="http://enigma-game.org/schema/level/1" xmlns:ee="http://enigma-game.org/schema/editor">
  <el:protected>
    <el:info el:type="level">
      <!-- требуемые элементы пропущены -->
    </el:info>
    <el:elements/>
    <el:luamain><![CDATA[
    ]]></el:luamain>
    <ee:editor/>
    <el:i18n/>
  </el:protected>
  <el:public>
    <el:i18n/>
    <el:upgrade/>
  </el:public>
</el:level>

Первая строка — это объявление XML. Не считая задания кодировки, оно фиксировано. На всех платформах Enigma поддерживает по крайней мере ‘US-ASCII’, ‘UTF-8’, ‘UTF-16’, ‘ISO-8859-1’, ‘windows-1252’. Введите вашу кодировку и убедитесь, что ваш редактор сохраняет уровень в этой кодировке. В некоторых редакторах можно начать работу в режиме ASCII, скопировать скелет уровня с другим объявлением кодировки, например UTF-8, сохранить уровень в том же режиме ASCII и заново открыть файл. После этого редактор может автоматически обнаружить объявление XML и автоматически переключиться на указанную кодировку. Имейте в виду, что если не вводить в уровне строки на языке, отличном от английского, о кодировке можно вообще не беспокоиться. В этом случае можно выбрать UTF-8.

Несколько дополнительных замечаний для новичков в XML: теги разметки XML очень похожи на теги HTML. Но для каждого начального тега ‘<element>’ XML нуждается в соответствующем теге завершения ‘</element>’. Для элементов, у которых есть только атрибуты, но нет содержимого, следует использовать альтернативную запись пустого элемента ‘<element/>’. Заметим, что когда мы определяем элемент как пустой или с состоянием, которое лишает его содержимого, между начальным и завершающим тегом не разрешается использовать ни одиночный пробел, ни даже конец строки. Во избежание ошибок используйте запись пустого элемента.

Мы используем приятный глазу формат записи с отступом в 2 символа. Каждый элемент начинается с отдельной строки. У элементов с текстовым содержимым на той же строке есть завершающий тег. Только у элементов с дочерними элементами завершающий тег находится на отдельной строке с таким же отступом.

Такой формат не обязателен. Можно даже вставлять разрывы строки в текстовое содержимое, метки и даже значения атрибутов. Но имейте в виду, что каждый разрыв строки во время парсинга (обработки интерпретатором) XML будет заменяться пробелом. Учитывайте это во избежание ошибок или просто используйте длинные строки.

Идентификатор пространства имён предваряет все названия тегов и атрибутов. В уровнях Enigma в качестве сокращения мы используем ‘el’. Этот префикс используют все названия тегов, которые можно отредактировать вручную.

Наконец, короткий комментарий о зарезервированных символах XML, ‘&’ и ‘<’. Эти два символа зарезервированы как начальные символы тега и объекта. Если они понадобятся в текстовом содержимом или значениях атрибутов, их следует заменить соответственно объектами ‘&amp;’ и ‘&lt;’. К тому же, значения атрибутов следует заключать между ‘"’ или ‘'’. Безусловно, необходимо заменять и кавычки, используемые в значениях атрибутов. Используйте ‘&quot’ и ‘&apos’.

Элементы:

/level, необходим, уникальный

Это основной элемент. В каждом файле он присутствует только в одном экземпляре. Как и первая строка объявления XML, эта вторая строка довольно фиксирована. Существует две её версии. Простая версия с 3 атрибутами, которая использовалась в первом примере, и версия предназначенная только для редакторов уровней, использующая 4 атрибута, как в последнем примере. Для ручного редактирования уровня просто скопируйте простую версию во вторую строку своего файла уровня.

Атрибуты:

xmlns:xsi, необходим, фиксированное содержимое

Определение пространства имён схемы. Содержимое установлено в “http://www.w3.org/2001/XMLSchema-instance”. Тег атрибута ‘xsi’ должен соответствовать префиксу следующего тега атрибута и является стандартным.

xsi:schemaLocation, необходим, фиксированное содержимое

Размещение используемых схем. Содержимым служит фиксированное пространство имён уровней Enigma, после которого следует URL размещения схемы. Редакторы уровней добавят свои пространства имён и URL размещения схемы, как во втором примере.

xmlns:el, необходим, фиксированное содержимое

Определение пространства имён для “уровня Enigma”. В качестве префикса пространства имён всех тегов элементов и атрибутов уровня мы, как правило, используем ‘el’. Используемый префикс может быть произвольным, но должен соответствовать своему тегу атрибутов. Содержимое атрибута зависит от пространства имён уровня Enigma.

xmlns:ee, необязательный

Последнее определение пространства имён используют только редакторы уровней. Например, мы объявили ‘ee’ как префикс пространства имён для всех тегов элементов и атрибутов редактора. Используемый префикс может быть произвольным, но должен соответствовать своему тегу атрибутов. Содержимым атрибута является пространство имён редактора.

/level/protected, необходим, уникальный

Защищённый раздел содержит все данные уровня, полученные от автора, которые не может изменять никто другой.

/level/protected/info, необходим, уникальный

Информационный раздел содержит все метаданные уровня. Он обязателен и детально описан в разделе Информация о метаданных.

/level/protected/elements, необязательный, уникальный

Раздел элементов необязателен. Он содержит части описания уровня, полученные с помощью управления данными. Хотя данный элемент введён для поддержки редакторов уровней, автор уровня может использовать любые части этого раздела как ему или ей захочется.

/level/protected/luamain, необязательный, уникальный

Раздел luamain является частью для ручной вставки определений уровня Lua. Он подробно описан в разделе Код LUA.

/level/protected/editor, необязательный, уникальный

Раздел редактора — это зона расширений, открытая для редакторов уровней. Они могут добавлять в этот раздел необходимую дополнительную информацию. Enigma же игнорирует этот раздел.

/level/protected/i18n, необходим, уникальный

Раздел интернационализации содержит строки на английском, переводы на другие языки и комментарии, предоставляемые переводчикам самим автором. Это обязательный раздел, и он подробно описан в разделе Интернационализация (i18n).

/level/public, необязательный, уникальный

Общедоступный раздел — это необязательное расширение защищённого раздела. Он содержит информацию не подтверждённую автором и даже может быть добавлен после последнего пересмотра самим автором.

/level/public/i18n, необязательный, уникальный

Общедоступный раздел интернационализации содержит дополнительные переводы, поставляемые с уровнем. Их можно получить у автора или из других источников. Переводчики утверждают эти переводы и они могут использоваться, пока переводчики не предоставят исправленные версии (см. раздел Интернационализация (i18n)).

/level/public/upgrade, необязательный, уникальный

Раздел обновления является частью системы Обновление и дополнение.

3.3 Информация о метаданных

Раздел информации содержит все предоставленные автором метаданные для этого уровня. Это источник таких данных. Все остальные части Enigma, такие как индексы уровней, просто содержат копии, которые автоматически обновляются с обновлением оригинальных данных уровня.

Далее мы рассмотрим все поддерживаемые информационные подразделы с их типичными атрибутами:

<el:info el:type="level">
  <el:identity el:title="Demo I18N" el:subtitle="Translate or let it be translated" el:id="20060211ral002"/>
  <el:version el:score="1" el:release="1" el:revision="0" el:status="experimental"/>
  <el:author  el:name="Ronald Lamprecht" el:email="ral@users.berlios.de"/>
  <el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>
  <el:license el:type="GPL v2.0 or above" el:open="true"/>
  <el:compatibility el:enigma="0.92"/>
  <el:modes el:easy="false" el:single="true" el:network="false"/>
  <el:comments/>
  <el:update el:url="http://…"/>
  <el:upgrade el:url="http://…" el:release="2"/>
  <el:score el:easy="-" el:difficult="-"/>
</el:info>

Атрибуты:

type, необходим, значения = “level”, “library”, “multilevel”

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

‘level’ предназначен для всех определений отдельного уровня. Не имеет значения, редактируется ли он вручную или с помощью редактора уровней и какое используется описание элементов.

‘library’ предназначен для описания частей уровня, которые могут быть включены в другой уровень. Библиотека состоит только из кода Lua в разделе luamain. Библиотеки могут использовать почти все разделы кроме ‘/level/protected/info/score’ и ‘/level/*/i18n’, которые должны предоставляться, но не могут использоваться. Библиотеки включаются в уровни с помощью элемента зависимости (см. раздел <compatibility>).

‘multilevel’ предназначен для описания сразу нескольких уровней. Основная цель — поддержка форматов уровней сторонних игр, таких как формат уровней Сокобан, которые обычно описывают в одном файле целый набор карт уровней (см. раздел Многоуровневые файлы).

quantity, необязательный

Количество уровней в файле, содержащем несколько уровней (см. раздел Многоуровневые файлы).

Содержимое — элементы:

identity, необходим

Заголовок, подзаголовок и основная строка описания уровня (см. раздел <identity>).

version, необходим

Все аспекты версии уровня (см. раздел <version>).

author, необходим

Вся предоставленная автором информация о себе (см. раздел <author>).

copyright, необходим

Сообщение об авторском праве на уровень (см. раздел <copyright>).

license, необходим

Информация об условиях лицензии (см. раздел <license>).

compatibility, необходим

Вся информация о совместимости с версиями Enigma, зависимостях от библиотек, внешних данных и редакторе, в котором был создан уровень (см. раздел <compatibility>).

modes, необходим

Режимы, которые поддерживает уровень, такие как сложность, сетевой режим и контроль (см. раздел <modes>).

comments, необязательный

Необязательные комментарии, такие как благодарности, посвящения и комментарии по коду (см. раздел <comments>).

update, необязательный

Обновление и дополнение

upgrade, необязательный

Обновление и дополнение

score, необходим

Результат самого автора уровня (см. раздел <score>).

3.3.1 <identity>

Элемент ‘identity’ необходим, т.к. он предоставляет информацию для идентификации уровня человеком и системой.

<el:identity el:title="Demo I18N" el:subtitle="Translate or let it be translated" el:id="20060211ral002"/>

Атрибуты:

title, необходим

Английское название уровня. Строка может содержать произвольные символы, которые могут быть отображены шрифтом Enigma и поддерживаются XML. В многоуровневых файлах заключительный знак "#" имеет особое значение. Название не должно быть слишком длинным, потому что Enigma использует его в меню выбора уровня. Переводы названия можно предусмотреть в разделе Интернационализация (i18n).

subtitle, необязательный

Необязательный английский подзаголовок. Используется для частей названия, которые не помещаются в основное название, или для небольшого совета в начале. Enigma показывает подзаголовок на странице информации об уровне и в начале уровня. Переводы подзаголовка можно предусмотреть в разделе Интернационализация (i18n).

id, необходим

Это основная строка идентификации уровня, которая всегда актуальна, независимо от последующих обновлений выпуска. Данная строка не должна содержать пробелов, скобок и масок (‘*? ()[]{}’. Главное требование Enigma к id в том, чтобы он был уникальным для всех уровней, созданных всеми авторами по всему миру, и не заканчивался закрывающей квадратной скобкой.

Так как уровни можно редактировать в любом текстовом редакторе или различных специальных редакторах уровней Enigma, то проконтролировать уникальность id не представляется возможным. Поэтому мы предлагаем простой стандарт id во избежание возможных противоречий между id различных уровней:

ГГГГММДДпользовательNNN

Где ‘ГГГГ’,‘ММ’,‘ДД’ — это дата создания первой экспериментальной версии, ‘пользователь’ заменяется уникальным именем автора, а ‘NNN’ случайным числом. Например, у моего уровня под названием ‘Houdini’ такой id: ‘20060816ral719’. Конечно, у всех уровней созданных в один день случайное число должно отличаться. id — это системный идентификаток уровня Enigma, и пользователь никогда в нём не нуждается.

Для обратной совместимости уровни, созданные для предыдущих версий игры, сохраняют своё прежнее имя файла в качестве id нового уровня и не используют приведённую выше схему. Это не создаёт никаких проблем, потому что единственным требованием к id является его уникальность.

Содержимое:

Этот элемент пуст — его нельзя заполнять.

3.3.2 <version>

Этот элемент предоставляет системе информацию о версии.

<el:version el:score="1" el:release="1" el:revision="0" el:status="experimental"/>

Атрибуты:

score, необходим

Номер версии задаётся как положительное целое число. Новые уровни начинают с версии под номером "1". Если изменения в уровне вызывают появление новых способов решения с несопоставимыми результатами, то новые версии уровня должны увеличивать номер версии. Конечно, авторы уровней должны прибегать к подобным изменениям только в крайних случаях.

При создании уровня, следует пользоваться атрибутом ‘status’, чтобы пометить уровень как неготовый. Когда автор сменит ‘status’ на ‘released’, он должен проверить сопоставимость результатов и, при необходимости, увеличить номер версии.

Этот атрибут — логический эквивалент атрибута ‘revision’ файла ‘index.txt’ в Enigma 0.92.

release, необходим

Технический выпуск версии задаётся как положительное целое число. Новые уровни начинают с выпуска под номером "1". Если изменения в уровне вызывают техническую несовместимость с предыдущими выпусками Enigma или несовместимость номеров версии, то следует увеличить номер выпуска версии.

Основной причиной технической несовместимости может стать изменение движка Enigma. Поскольку такая коррекция не будет работать на старой версии Enigma, версии уровней должны отличаться различными номерами выпуска.

И в случае технической несовместимости, и в случае несовместимости номеров версий также должно быть изменено имя файла уровня. Это необходимо, потому что на некоторые системы одновременно могут быть установлены различные версии Enigma. Они нуждаются в одновременном доступе к обеим версиям уровня. Также одновременный доступ к различным версиям уровней Enigma должны предоставлять интернет-сервера.

Чтобы дать игрокам возможность пользоваться различными выпусками файлов уровней, мы настоятельно рекомендуем использовать следующий стандарт именования уровней ИдентификаторАвтораНомерУровня_НомерВыпуска.Суффикс, где номер уровня состоит по крайней мере из 2 цифр; например, ‘ral01_2.xml’

revision, необходим

Номер издания — это простой, постоянно увеличивающийся номер версии. Новый номер издания должен быть у каждой изданной версии уровня. Номер издания независим от номера версии и выпуска.

Если в своих путях поиска данных Enigma найдёт два файла уровней с одинаковыми именами, идентификатором, номером и выпуском версии, она загрузит тот, у которого номер издания больше. Эта возможность гарантирует, что более старое издание уровня, хранящееся в домашней директории уровней пользователя, не будет использоваться вместо нового издания уровня, поставляемого с новым выпуском Enigma. Обновления по сети также проверяют номера изданий уровней.

Хотя издание задается числом, атрибут может получить другую строку в виде ключевого слова ‘$Revision: 1.19 $’. Этот формат Subversion позволяет репозиторию Subversion авторов уровней автоматически вставлять номер издания уровня. Они должны просто установить значение ‘svn propset svn:keywords "Revision" level.xml’ для каждого файла уровня в своем репозитории. Поскольку номер издания Subversion — это постоянно увеличивающаяся величина, она удовлетворяет нашим критериям. Заметьте, что Enigma не требует, чтобы номера издания шли по порядку.

status, необходим, значения = “released”, “stable”, “test”, “experimental”

Этот атрибут описывает качество уровня во время разработки. Enigma использует состояние для защиты базы данных результатов от искажений непредусмотренными результатами решения. Она записывает только результаты уровней, помеченных как ‘released’.

К сведению авторов уровней: при изменении уже выпущенного уровня следует снова сменить его статус на ‘experimental’. Затем внесите изменения и протестируйте уровень. Когда будете абсолютно уверены, что не добавили никаких спойлеров, то можете снова выпустить уровень с новым изданием, а может, и новым выпуском или номером версии.

Содержимое:

Этот элемент пуст — его нельзя заполнять.

3.3.3 <author>

Информация о самом авторе. Enigma необходим только сам элемент автора, а все атрибуты необязательны, чтобы оставить автору возможность остаться анонимом. Пожалуйста, помните, что у администраторов уровней и переводчиков может возникнуть необходимость связаться с вами. Поэтому, пожалуйста, предоставьте им такую возможность.

Элемент автора может выглядеть следующим образом:

<el:author  el:name="Ronald Lamprecht" el:email="ral@users.berlios.de" el:homepage="http://myhomepage.domain"/>

Атрибуты:

name, необязательный, по умолчанию = “anonymous”

Имя автора в том виде, в каком оно будет показываться на странице информации об уровне и в начале уровня. По умолчанию это имя ‘anonymous’.

email, необязательный

Электронная почта автора, новостная лента или форум, которые он просматривает. В основном это указание о том, как связаться с ним/ней. Значение просто показывается в виде строки на странице информации об уровне.

homepage, необязательный

Домашняя страница автора или место, где он размещает дополнительные уровни Enigma. Значение просто показывается в виде строки на странице информации об уровне.

Содержимое:

Этот элемент пуст — его нельзя заполнять.

3.3.4 <copyright>

Стандартизованное расположение сообщения об авторских правах:

<el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>

Атрибуты:

отсутствует

Содержимое:

Уведомление об авторских правах.

3.3.5 <license>

Конечно, каждый автор волен сам выбирать условия лицензии для своих уровней. Однако, автор должен указать эти условия. Для этого и нужен этот элемент и его атрибуты:

<el:license el:type="GPL v2.0 or above" el:open="true"/>

Атрибуты:

type, необходим

Короткое определение типа лицензии, с необязательной ссылкой на текст лицензии или строкой ‘special’, если автор приводит в содержимом этого элемента свою собственную лицензию.

open, необходим

Булево значение, показывающее, удовлетворяет ли выбранная лицензия критериям Open Source Initiative (OSI). Пожалуйста, имейте в виду, что значение ‘false’ может помешать распространению вашего уровня с Enigma.

Содержимое:

В качестве содержимого этого элемента допускается использовать полный текст лицензии. Воспользуйтесь атрибутом ‘type’, чтобы определить уровень.

3.3.6 <compatibility>

<el:compatibility el:enigma="0.92" el:engine="enigma">
  <el:dependency el:path="lib/natmaze" el:id="lib/natmaze" el:release="1" el:preload="true" el:url="http://anywhere.xxx/mypage/natmaze.xml"/>
  <el:externaldata el:path="./extfile" el:url="http://anywhere.xxx/mypage/extdata.xml"/>
  <el:editor el:name="none" el:version=""/>
</el:compatibility>

Атрибуты:

enigma, необходим

Минимальный номер выпуска Enigma, с которым совместим уровень.

engine, необязательный, значения = “enigma”, “oxyd1”, “per.oxyd”, “oxyd.extra”, “oxyd.magnum”; по умолчанию = “enigma”

Необходимый режим совместимости движка, который влияет на поведение различных объектов. Этот атрибут используется только для уровней. Библиотеки данный атрибут игнорируют.

Содержимое — элементы:

Сам элемент совместимости в качестве содержимого включает только подэлементы.

dependency, необязательный, несколько экземпляров

Этот элемент используется для указания библиотеки Enigma-Lua, от которой зависит этот уровень. Используя несколько экземпляров данного элемента, можно указать несколько библиотек. Если библиотека настроена на предварительный запуск, движок загрузит её перед загрузкой или исполнением любого кода Lua, используемого в уровне. Порядок загрузки нескольких библиотек основывается непосредственно на порядке элементов зависимостей.

Атрибуты:

path, необходим

Путь к ресурсам библиотеки без её суффикса и любого расширения. Большинство библиотек Enigma хранит в поддиректории ‘lib’ своей директории ‘levels’, в большинстве случаев путь к ресурсам будет примерно таким: ‘lib/ant’. Это действительный путь к файлу библиотеки, который может иметь вид ‘levels/lib/ant.xml’, ‘levels/lib/ant.lua’ или ‘levels/lib/ant_1.xml’.

Однако, библиотеки могут быть и полностью зависимыми от пакета уровней. В этом случае можно выбрать относительный путь, такой как ‘./mylib’, и хранить библиотеку в самой директории пакета уровней.

id, необходим

Это независимый от версии id библиотеки, указанный в её метаданных. Во избежание проблем Enigma проверит данный атрибут при загрузке библиотеки и, вместе с номером выпуска версии, может использовать для определения перемещённых библиотек.

release, необходим

Хотя у различных выпусков библиотек должны быть различные имена, следует указывать версию библиотеки. Во избежание проблем Enigma проверит данный атрибут при загрузке библиотеки и, вместе с номером выпуска версии, может использовать для определения перемещённых библиотек.

preload, необходим

Булево выражение, которое указывает, должна ли библиотека загружаться предварительно. Если библиотека не является предварительно загружаемой, её всё равно можно загрузить с помощью кодовых выражений Lua. Но даже эти библиотеки должны быть определены, т.к. Enigma проверит их на соответствие. При использовании раздела ‘elements’ всегда нужно предварительно загружать библиотеки.

url, необязательный

Этот необязательный атрибут позволяет указать для библиотеки запасной адрес. Это будет полезно при использовании новых библиотек, ещё не поставляемых с системой.

Во время разработки и тестирования новых библиотек разработчик может распространять пробные уровни с пустым атрибутом пути к ресурсам ‘library’. Пробные уровни загрузят новейшую версию библиотеки, которая указана в полученном URL.

Содержимое:

отсутствует

externaldata, необязательный, несколько экземпляров

Этот элемент можно использовать для указания любого внешнего текстового файла данных, от которого зависит этот уровень. Добавляя несколько экземпляров этого элемента, можно указать несколько файлов. Заданные файлы могут быть прочитаны с помощью интерфейса Lua.

Эта возможность призвана обеспечить поддержку других игр в Enigma, например Сокобана. В виду авторских прав и лицензионных соглашений, включение некоторых данных в уровень может оказаться неприемлемым. Однако распространение данных в оригинальном неизменном формате, возможно, будет законным.

Атрибуты:

path, необходим

Путь к ресурсам внешнего файла данных без расширения ‘.txt’. Путь должен иметь формат "./name" для внешнего файла данных, который хранится локально в той же папке, что и файл уровня, или будет сохранён по данному адресу при загрузке, или "externaldata/name" для общих внешних файлов данных, на которые ссылаются различные файлы уровней, хранящиеся в разных папках. Внешний файл данных может храниться локально или сохраняться в папке "levels/externaldata". В любом случае локальное имя внешнего файла данных будет иметь расширение ‘.txt’, чтобы обозначить его как читаемый, но не исполняемый для локальной операционной системы.

url, необязательный

Этот необязательный атрибут позволяет задать сетевой адрес к внешнему файлу данных. При первом доступе отсутствующий внешний файл данных будет загружен, а его копия будет сохранена локально для последующего доступа.

Содержимое:

отсутствует

editor, необязательный, уникальный

Специальные редакторы уровней используют этот элемент, чтобы хранить информацию о себе.

Атрибуты:

name, необходим

Название редактора уровней.

version, необходим

Номер версии редактора, полученный в виде строки .

Содержимое:

отсутствует

Содержимое:

отсутствует

3.3.7 <modes>

Элемент ‘modes’ позволяет автору указать поддерживаемый режим и режим уровня по умолчанию. Движок Enigma проверяет, используется ли уровень в поддерживаемом режиме.

<el:modes el:easy="false" el:single="true" el:network="false" el:control="force" el:scoreunit="duration" el:scoretarget="time"/>

Атрибуты:

easy, необходим, значения = “true”, “false”

Если уровень поддерживает второй, упрощённый, режим, установите этот атрибут в ‘true’. Если поддерживается только сложный режим, установите атрибут в ‘false’.

single, необходим, значения = “true”, “false”

Если уровень, как и стандартные, предоставляет возможность одиночной игры, установите этот атрибут в ‘true’. Установите этот атрибут в ‘false’, только если уровень представляет собой сетевую игру для 2 игроков.

network, необходим, значения = “true”, “false”

Если уровень предоставляет возможность сетевой игры для 2 игроков, установите этот атрибут в ‘true’. В противном случае установите этот атрибут в ‘false’.

control, необязательный, значения = “force”, “balance”, “key”, “other”; по умолчанию = “force”

Этот атрибут задаёт для уровня стандартный режим управления. На уровне можно играть, пользуясь мышью, движение которой влияет на положение шариков: это стандартный способ, и он был единственным вплоть до Enigma 0.92. Или же можно играть на уровне, используя мышь или другие устройства ввода для балансировки шариками в мире уровня. Кроме того, можно использовать клавиши со стрелками на клавиатуре, чтобы перемещать актёра, как в классических играх Сокобан.

Хотя последнее слово в выборе более подходящего способа управления всегда остаётся за пользователем, автор должен задать стандартный режим управления, который использует система подсчёта результатов. Enigma сохранит и рассчитает для списков рекордов только результаты, полученные в заданном режиме управления.

scoreunit, необязательный, значения = “duration”, “number”; по умолчанию = “duration”

Этот атрибут задаёт режим подсчёта и отображения результатов. В режиме по умолчанию, ‘duration’ результаты интерпретируются как время решения уровня и отображаются в формате ММ:СС. Режим ‘number’ отображает результаты в виде обычных чисел, а меньшие числа означают лучшие результаты. Этот режим подходит для подсчета толчков и шагов.

scoretarget, необязательный, значения = “time”, “pushes”, “moves”, *; по умолчанию = “time”

Целевое значение задаёт способ подсчёта баллов. При выборе ‘time’ учитывается время решения, при выборе ‘pushes’ — количество толчков камней, при выборе ‘moves’ — шаги актёра. Любое другое значение вызовет функцию Lua для подсчёта результатов. Цель в пользовательском интерфейсе представлена в виде короткого наименования для результатов.

Содержимое:

отсутствует

3.3.8 <comments>

Необязательный раздел комментариев позволяет автору добавить несколько комментариев и определить, как их нужно использовать. Пожалуйста, имейте в виду, что поддержка интернационализации не позволяет переводить комментарии.

<el:comments>
    <el:credits el:showinfo="true" el:showstart="false">Thanks to the author of my favorite libs</el:credits>
    <el:dedication el:showinfo="true" el:showstart="false">To a honorable or a beloved person</el:dedication>
    <el:code>some important general notes</el:code>
</el:comments>

Атрибуты: отсутствуют

Содержимое — элементы:

Сам элемент комментариев в качестве содержимого включает только подэлементы.

credits, необязательный, уникальный

Место для того, чтобы поблагодарить людей, помогавших вам при создании уровня.

Атрибуты:

showinfo, необязательный, по умолчанию = “false”

Значение ‘true’ покажет сообщение на странице информации об уровне.

showstart, необязательный, по умолчанию = “false”

Значение ‘true’ покажет сообщение при запуске уровня. Пожалуйста, используйте эту возможность только в исключительных случаях.

Содержимое:

Сами благодарности. Он может быть разделён на несколько строк. Перед отображением лишние пробелы убираются.

dedication, необязательный, уникальный

Место для посвящения уровня уважаемому или любимому человеку. Пожалуйста, используйте для этой цели данное поле, а не документы на самом уровне.

Атрибуты:

showinfo, необязательный, по умолчанию = “false”

Значение ‘true’ покажет сообщение на странице информации об уровне.

showstart, необязательный, по умолчанию = “false”

Значение ‘true’ покажет сообщение при запуске уровня. Пожалуйста, используйте эту возможность только в исключительных случаях.

Содержимое:

Само посвящение. Он может быть разделён на несколько строк. Перед отображением лишние пробелы убираются.

code, необязательный, уникальный

Атрибуты:

отсутствуют

Содержимое:

Главный комментарий к коду, который может представлять собой пояснение состояния <version> или список запланированных изменений. Он может быть разделён на несколько строк. Этот комментарий не обрабатывается.

3.3.9 <score>

В этом разделе автор должен опубликовать свои собственные результаты в качестве ориентира и вызова для остальных игроков. Все значения связаны с режимом управления, заданным в <modes>.

<el:score el:easy="01:07" el:difficult="-"/>

Атрибуты:

easy, необходим

Время решения уровня в упрощённом режиме. Формат: ММ:СС, где ММ означает минуты, а СС секунды, либо - если автор ещё не решил свой уровень. Для уровней с единицей измерения результатов ‘number’ значение должно быть числом шагов шарика или толчков.

difficult, необходим

Время решения уровня в сложном режиме. Формат: ММ:СС, где ММ означает минуты, а СС секунды, либо - если автор ещё не решил свой уровень. Для уровней с единицей измерения результатов ‘number’ значение должно быть числом шагов шарика или толчков.

Содержимое:

3.4 Код LUA

Этот элемент включает в себя любой код Lua в виде единого блока почти без ограничений:

    <el:luamain><![CDATA[
levelw = 20
levelh = 13

create_world( levelw, levelh)
draw_border("st-wood")
fill_floor("fl-leavesb", 0,0,levelw,levelh)

oxyd( 4,4)
oxyd( 14,4)

document(5,10,"hint1")
document(10,10,"hint2")
document(10,5,"Heureka!")
set_actor("ac-blackball", 4, 11)
    ]]></el:luamain>

Атрибуты:

отсутствуют

Содержимое:

В качестве содержимого этого элемента выступает основной код Lua.

Все остальные библиотеки, объявленные как зависимости, и поставляемые элементами XML фрагменты кодаLua загружаются предварительно, как описано в разделе <compatibility>. Обычно для того, чтобы загрузить библиотеки, нет необходимости в использовании таких функций Lua как ‘Require’. В случае, если нужно контролировать точку входа в процедуру, где должна загружаться библиотека, можно объявить библиотеку с атрибутом ‘el:preload="false"’. Чтобы загрузить библиотеку следует использовать новую функцию @ref{enigma.LoadLib}.

Код Lua — это код, заключённый в разделе XML под названием CDATA. Это накладывает на код Lua ограничения в виде невозможности использования завершающего тега ‘]]>’. Любое его вхождение должно быть заменено на ‘]] >’.

С другой стороны, формат XML расширяет возможности использования кодировок в Lua. В строках и комментариях Lua можно использовать умляуты, но идентификаторы Lua всё же ограничиваются чистым US-ASCII. Преимущество в том, что допускается использовать умляуты и другие символы, отсутствующие в ASCII, в подсказках it-document.

3.5 Интернационализация (i18n)

Интернационализация уровней стала движущей силой изменений в формате уровней. Можно заметить, что существует два элемента ‘i18n’: один в защищённом авторском разделе и один в общедоступном. Рассмотрим, как использовать их для интернационализации трёх документов нашего уровня ‘demo_i18n.xml’:

  <el:protected >
    <!-- elements omitted -->
    <el:i18n>
      <el:string el:key="title">
        <el:english el:translate="false"/>
      </el:string>
      <el:string el:key="subtitle">
        <el:english el:translate="true"/>
        <el:translation el:lang="de">Ьbersetzten oder ьbersetzten lassen</el:translation>
      </el:string>
      <el:string el:key="hint1">
        <el:english el:comment="Let 'right' be ambiguous: correct and opposite of left - if not possible choose correct">Read the right document</el:english>
        <el:translation el:lang="de">Lies das rechte Dokument</el:translation>
      </el:string>
      <el:string el:key="hint2">
        <el:english el:comment="the correct one and not the right positioned one">The right one, not the right one!</el:english>
        <el:translation el:lang="de">Das rechte, nicht das rechte</el:translation>
      </el:string>
      <el:string el:key="Heureka!">
        <el:english el:translate="false">Heureka!</el:english>
      </el:string>
    </el:i18n>
  </el:protected>
  <el:public>
    <el:i18n>
      <el:string el:key="hint1">
        <el:translation el:lang="fr">Lisez la document de droite</el:translation>
      </el:string>
    </el:i18n>
  </el:public>

Два документа для обращения к строке используют ключевые слова. Последний использует в качестве ключа непосредственно английскую строку. Существует ещё два дополнительных зарезервированных ключа: ‘title’ и ‘subtitle’.

Для каждой переведённой строки или той, которая нуждается в переводе, мы определяем подэлемент защищённого раздела — ‘string’ и добавляем к самому элементу подэлемент ‘english’. Элемент ‘string’ получает один обязательный атрибут — код строки. У элемента ‘english’ один обязательный атрибут ‘translate’ (который по умолчанию инициализируется значением ‘true’), отражающий решение автора о необходимости перевода строки. Если автор не желает, чтобы строка была переведена, он может и должен вообще не добавлять в эту строку элемент ‘string’. Таким образом, элементы для строк с ключами ‘title’ и ‘Heureka!’ необязательны и встречаются довольно редко.

‘title’ и ‘subtitle’ отображают текст на английском в элементе <identity>. Все остальные строки, к которым обращаются, используя их код, в качестве содержимого элемента ‘english’ должны включать в себя английский текст. Примерами служат ‘hint1’ и ‘hint2’.

Ввиду того, что мы выбрали довольно неясные английские тексты, переводчики, которые сами не играли в игру, могут перевести их неправильно. Во избежание ошибок автор уровня может добавить к элементу ‘english’ атрибут ‘comment’. Как мы увидим ниже, переводчик получит в своё распоряжение комментарий вместе со строкой на английском.

Если для автора английский язык не родной, он должен добавить к элементу ‘string’ свой подэлемент ‘translation’. У элемента ‘translation’ есть один обязательный атрибут ‘lang’, который принимает 2-буквенное сокращение языка. Содержимое этого элемента — сам перевод.

Все переводы, добавленные в защищённый раздел, получают преимущество над любыми переводами, выполненными переводчиками, и используются сразу после добавления, не дожидаясь перевода уровня переводчиками.

Необходимо упомянуть, что в общедоступном разделе у нас есть элемент ‘i18n’. В этом элементе содержатся предложения по переводу. Автор может самостоятельно добавить его для других известных ему языков. Они могут быть добавлены на пути уровня к пользователю или даже самим пользователем.

Переводы в этом разделе используются сразу после добавления, не дожидаясь переводов уровня переводчиками. Однако, у переводов, выполненных переводчиками, есть преимущество над ними.

Формат аналогичен используемому в защищённом разделе, исключая неиспользуемые элементы ‘english’. Атрибут ‘key’ элемента ‘string’ должен точно совпадать с атрибутом ‘key’ соответствующего элемента ‘string’ из защищённого раздела. Тут есть одно трудноуловимое различие, вызванное причинами технического и практического характера. Атрибуты ‘key’ в общедоступном разделе должны быть идентификаторами XML; поэтому, нельзя предоставить общедоступный перевод строк, использующих фразу на английском в качестве кода. Чтобы избежать подобных проблем, выберите ключевое слово и вынесите английскую строку в общедоступный раздел ‘i18n’.

Элемент ‘string’ из защищённого и общедоступного разделов должен быть уникальным относительно атрибута ‘key’ в соответствующем разделе. Это значит, что переводы для всех известных языков следует добавить для строки в элементе ‘string’ из защищённого и общедоступного разделов. Порядок не имеет значения.

Давайте посмотрим, что получит переводчик для каждой из строк. Давайте начнём с ‘hint2’ для немецкого переводчика:

#  level: "Demo Internationalization"
#  author: "Ronald Lamprecht" email "ral@users.berlios.de"
#  comment: "the correct one and not the right positioned one"
#  use: "Das rechte, nicht das rechte"
#: po/level_i18n.cc:17
msgid "The right one, not the right one!"
msgstr ""

‘msgid’ — это строка на английском. ‘msgstr’ принимает немецкий перевод. Но переводчику не надо ничего переводить, потому что автор предоставил перевод на немецкий в строке ‘# use:’.

Другим примером может послужить ‘hint1’ для французского переводчика:

#  level: "Demo Internationalization"
#  author: "Ronald Lamprecht" email "ral@users.berlios.de"
#  comment: "Let 'right' be ambiguous: correct and opposite of left - if not possible choose correct"
#  check: "Lisez la document de droite"
#: po/level_i18n.cc:14
msgid "Read the right document"
msgstr "Lisez le document de droite"

Здесь автор предоставляет общедоступный перевод в строке ‘# check:’. Так как в нём есть по крайней мере одна ошибка, переводчик должен его исправить, как показано в строке ‘msgstr’.

3.6 Использование

После сухой теории давайте посмотрим, как обращаться с форматом уровней XML на практике. Конечно, не обязательно заново собирать воедино метаданные XML для каждого нового уровня, который будет писаться. Целесообразнее использовать шаблоны. Можно начать с любого существующего уровня, например ‘demo_i18n.xml’, поставляемого с этой документацией. Добавьте в него свои личные данные и храните его в качестве шаблона для всех новых уровней, которые вы напишете.

Некоторые авторы уровней хорошо знакомы с форматом файлов Lua, так как их любимый редактор поддерживает подсветку синтаксиса в этих файлах. Имя файла XML и элементы XML указывают их редактору использовать подсветку синтаксиса XML. Тем не менее, эти авторы привыкли вносить метаданные в заголовки своих уровней Lua в виде нестандартных комментариев Lua; мы решили добавить поддержку подобного формата XML, совместимого с Lua. Мы называем его "XML с комментариями Lua", потому что он просто комментирует все строки XML комментариями Lua — ‘--xml-- ’. Например:

--xml-- <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
--xml-- <el:level xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
--xml--   <el:protected >
--xml--     <el:info el:type="level">
--xml--       <el:identity el:title="Demo Simple" el:id="20060210ral001"/>
--xml--       <el:version el:score="1" el:release="1" el:revision="0" el:status="stable"/>
--xml--       <el:author el:name="Ronald Lamprecht"/>
--xml--       <el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>
--xml--       <el:license el:type="GPL2" el:open="true">GPL v2.0 or above</el:license>
--xml--       <el:compatibility el:enigma="0.92"/>
--xml--       <el:modes el:easy="false" el:single="true" el:network="false"/>
--xml--       <el:score el:easy="-" el:difficult="-"/>
--xml--     </el:info>
--xml--     <el:luamain><![CDATA[
levelw = 20
levelh = 13

create_world( levelw, levelh)
draw_border("st-wood")
fill_floor("fl-leavesb", 0,0,levelw,levelh)

oxyd( 4,4)
oxyd( 14,4)

set_actor("ac-blackball", 4, 11)
--xml--     ]]></el:luamain>
--xml--     <el:i18n/>
--xml--   </el:protected>
--xml-- </el:level>

Пожалуйста, имейте в виду, что каждая строка с метаданными XML начинается именно с ‘--xml-- ’, 8 символов, включая пробел в конце. Дополнительное ограничение формата XML с комментариями Lua возникает из-за способности Lua хранить кодировки символов. Для успешного использования формата XML с комментариями Lua следует ограничиться ‘UTF-8’ или, конечно, ‘US-ASCII’. Пожалуйста, помните, что хотя часть XML комментируется Lua, она всё так же должна обрабатываться, а значит и быть верной.

Каждый уровень, хранящийся в формате XML с комментариями Lua, как файл с расширением ‘.lua’, может использоваться непосредственно в командной строке, равно как и в любом пакете уровней, который хранится в пользовательской домашней директории Enigma. Однако уровни в формате XML с комментариями Lua не могут храниться на серверах в интернете или обновляться в режиме реального времени. Поэтому этот формат хорош для создания уровней, но перед распространением их необходимо преобразовать в чистый формат XML. Пожалуйста, имейте в виду, что сначала Enigma ищет уровни XML, а уровни Lua использует, только если не найдёт уровень XML.

Ещё одним вариантом применения уровней в формате XML с комментариями Lua служит обратная совместимость с Enigma 0.92. Если уровни в этом формате не используют новые возможности Enigma, то их можно включить в пакеты уровней Enigma 0.92.

Так как вам может понадобиться несколько раз преобразовать уровни из формата XML в Lua и обратно, мы предлагаем инструменты преобразования: ‘xml2lua’ и ‘lua2xml’. Оба они — очень простые скрипты Lua 5, которые, если 5-я версия Lua установлена правильно, можно использовать следующим образом: ‘lua xml2lua demo_simple.xml > demo_simple.lua’. В системах Unix можно пометить скрипты как исполняемые и просто вводить ‘xml2lua demo_simple.xml > demo_simple.lua’.

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

В процессе работы с метаданными XML, безусловно, могут быть допущены синтаксические ошибки. Свой уровень можно проверить, попробовав запустить его в Enigma. Ошибки XML выводятся на экран, так же как и ошибки Lua. Если сообщения об ошибках не помещаются в экран, можно запустить Enigma из командной строки с опцией ‘--log’ и прочесть сообщения, выведенные в командной строке или (для систем Windows) записанные в файле ‘stdout.txt’ в текущей директории.

Конечно, можно использовать и сторонний инструмент проверки корректности XML. Нужно только скопировать файл схемы ‘level.xsd’ в директорию, в которой находится сам уровень. Примером возможных инструментов контроля может быть программа Xerces-C ‘DOMPrint.exe -n -s -f -v=always level.xml’ или редакторы с проверкой корректности, такие как Exchanger XML Lite. Такие редакторы выделят во всех местах все возможные элементы и атрибуты.

3.7 Обновление и дополнение

Поскольку мы указываем все необходимые атрибуты в элементе <version>, Enigma может загружать новые версии уровней.

Если Enigma загружает новые версии, у которых отличается только номер издания ‘revision’, мы подразумеваем ‘обновление’. Обновление может быть выполнено автоматически с заменой старых версий обновлёнными, поскольку автор гарантирует их совместимость в результатах и зависимостях. Автор должен предоставить адрес для загрузки автоматических обновлений в защищённом информационном элементе:

<el:update el:url="http://myLevelServer.org/path/level_1.xml"/>

Атрибуты:

url, необходим

Доступный в течение длительного времени, полный адрес для загрузки обновлений этого уровня с теми же номером и выпуском версии.

Если автор уровня вносит в уровень элементы, приводящие к несовместимости, он увеличивает выпуск версии уровня и сохраняет файл уровня под новым именем. Мы называем загрузку такой версии нового уровня ‘дополнением’.

Чтобы сообщить о доступности выпуска дополнения, автор должен обновить предыдущий выпуск с последним номером издания, просто добавив элемент дополнения, сообщающий о новом выпуске:

<el:upgrade el:url="http://myLevelServer.org/path/level_2.xml" el:release="2"/>

Атрибуты:

url, необходим

Действительный в течение длительного времени, полный адрес для загрузки дополнений этого уровня. Путь к новому файлу.

release, необходим

Выпуск версии дополнения.

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

3.8 Использование библиотек

Библиотеки — это набор функций Lua для многократного использования во многих уровнях. Для использования библиотеки её необходимо объявить как зависимость, как описано в разделе <compatibility>. Предварительная загрузка библиотеки — это всё, что необходимо для её использования. Кроме того, для загрузки библиотеки в определенной точке выполнения можно использовать функцию @ref{enigma.LoadLib}.

Enigma предоставляет несколько очень полезных библиотек. Их можно найти по системному пути в поддиректории ‘levels/lib’. Большинство из них хорошо прокомментированы непосредственно в исходном коде. Для ‘ant’ существует отдельный файл с документацией: ‘doc/ant_lua.txt’.

В этом разделе, мы сконцентрируемся на аспектах написания и поддержки библиотек:

3.8.1 Написание библиотеки

Файлы библиотеки практически аналогичны файлам уровней. Основное отличие в атрибуте ‘el:type’ элемента ‘info’, который следует установить в ‘library’. Все остальные элементы и атрибуты должны быть такими же, как и для уровней. Конечно, никакие атрибуты, основанные на результатах, не будут учитываться и им следует присвоить значения по умолчанию.

Библиотеки могут зависеть от других библиотек, поэтому необходимо предоставить идентификационный номер и номер выпуска версии. Несколько выпусков библиотеки могут сосуществовать, и их можно обновить и дополнить, если предоставить необходимую информацию. Конечно, библиотеки могут содержать строки документов, которые могут быть локализованы, если вы предоставите элементы ‘i18n’.

Элемент ‘el:luamain’ принимает полный код Lua, как и для уровней. Давайте взглянем на важнейшие XML-части библиотеки:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<el:level xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
  <el:protected >
    <el:info el:type="library">
      <el:identity el:title="" el:id="lib/ant"/>
      <el:version el:score="1" el:release="1" el:revision="0" el:status="released"/>
      <el:author  el:name="Petr Machata"/>
      <el:copyright>Copyright © 2002-2003 Petr Machata</el:copyright>
      <el:license el:type="GPL v2.0 or above" el:open="true"/>
      <el:compatibility el:enigma="0.92">
        <el:dependency el:path="lib/natmaze" el:id="lib/natmaze" el:release="1" el:preload="false">
      </el:compatibility>
      <el:modes el:easy="false" el:single="false" el:network="false"/>
      <el:score el:easy="-" el:difficult="-"/>
    </el:info>
    <el:luamain><![CDATA[
    …
    ]]></el:luamain>
    <el:i18n/>
  </el:protected>
</el:level>

3.8.2 Поддержка библиотеки

Библиотеки могут существовать в виде различных выпусков и изданий. Версии библиотек, которые отличаются только номером издания, считаются совместимыми версиями. Версии библиотеки, которые привносят несовместимость, должны отличаться номером выпуска версии. Однако ввиду того, что существующие уровни могут зависеть от поведения более ранних выпусков, необходимо поддерживать оба выпуска версии библиотеки и распространять их вместе с Enigma.

Для сосуществования эти различные выпуски библиотек должны следовать жёсткой схеме именования. У каждой библиотеки должно быть своё основное имя. В предыдущем примере это ‘lib/ant’. Имя файла данного конкретного выпуска — это основное имя с добавлением символа подчёркивания и номера версии плюс суффикс ‘xml’. Поэтому выпуск ‘lib/ant’ следует хранить в виде ‘lib/ant_2.xml’.

Если посмотреть в директорию lib, то можно обнаружить, что Enigma хранит большинство библиотек без добавления к основному имени номера выпуска. Это из-за поддержки совместимости форматов уровней Lua для версии 0.92. Допускается хранить один, и только один, выпуск каждой библиотеки без добавления к основному имени номера выпуска. Enigma загрузит эту версию из обычных уровней Lua, которые не предоставляют никакой информации о необходимом выпуске библиотеки.

Если файла библиотеки с полным основным именем файла нет, для запросов загрузки XML также будет загружен файл библиотеки по умолчанию, в названии которого отсутствует номер выпуска. Однако в будущем новая схема именования станет единственной, и каждая новая библиотека должна с самого начала следовать ей.

3.9 Многоуровневые файлы

Ещё одним способом повторного использования кода, помимо файлов библиотек, являются многоуровневые файлы. Код, содержащийся в одном файле, может генерировать несколько уровней, называемых подуровнями, которые присутствуют в пакете в качестве автономных уровней. Конечно, данный способ является менее гибким, чем использование библиотек, поскольку другие файли не могут повторно использовать код. Но вы можете использовать данный способ, если вы написали большой объём специфического кода для сложного уровня, предусматривающего более двух вариантов (в противном случае эти варианты указывались бы как ‘difficult’ и ‘easy’ в элементе <modes>).

Но основная роль, выполняемая многоуровневыми файлами, заключается в поддержке форматов других игр, например Сокобана; целые серии таких уровней могут быть описаны в одном многоуровневом файле. Enigma позволяет импортировать эти оригинальные файлы с помощью нескольких строчек кода. Написать же пустую подпрограмму для каждого уровня, импортируемого в Enigma из единого файла в другом формате, возможно, но нерационально.

Но у многоуровневых файлов есть свои ограничения. Они используют единый набор метаданных XML. Поэтому эти метаданные должны подходить для всех уровней. Элемент <version> будет идентичным, поскольку он отражает версию кода оригинального уровня или версию файла, импортируемого из другой игры. Но другие данные, например <author>, <compatibility> и <modes>, также должны совпадать.. В противном случае использовать многоуровневый файл нельзя.

Для всех уровней, описанных в многоуровневом файле, могут (и должны) отличаться только значения ‘title’ и ‘id’. В игре предусмотрены специальные средства работы с этими атрибутами для многоуровневых файлов.

Рассмотрим все атрибуты и свойства многоуровневых файлов, отличающиеся от стандартных.

Во-первых, в информации о метаданных необходимо объявить тип уровня как "multilevel" и указать количество генерируемых уровней. Нумерация подуровней осуществляется с 1 и до указанного количества.

В элементе <identity> необходимо указать один уникальный идентификатор уровня. Enigma автоматически добавить строку "[1]" для первого подуровня, "[2]" — для второго и т. д. Таким образом, каждый подуровень будет иметь уникальный идентификатор.

Кроме того, в элементе <identity> необходимо предусмотреть общий заголовок для уровней. Если заголовок заканчивается знаком ‘#’, Enigma будет автоматически генерировать заголовки для подуровней, добавляя к общей строке заголовка номер подуровня.

Для отдельных подуровней заголовки необходимо предусмотреть в коде LUA. Заголовок, указываемый в элементе <identity>, не может оканчиваться знаком ‘#’ и будет использоваться только в качестве заголовка по умолчанию, если в коде LUA заголовок подуровня будет отсутствовать. Перед выполнением кода Lua осуществляется инициализация глобального атрибута SublevelNumber. Загрузка подходящего подуровня в коде Lua может осуществляться на основе данного номера любым из способов. Кроме того, код Lua в таком случае также должен задать значение ещё одного глобального атрибута многоуровневых файлов — SublevelTitle.

<compatibility> externaldata

4. Ключевые понятия Enigma

Теперь, когда вам уже известна структура формальной описательной XML-части уровня, вам, наверное, будет интересно узнать основные принципы структуры мира уровня Enigma. В этой главе мы объясним все основные понятия и термины, присутствующие в дальнейших главах, которые описывают видение уровня его автором.

Обратите внимание, что мы описываем характеристики нового API версии Enigma 1.10. В API предыдущих версий отсутствуют некоторые его характеристики, и в ряде аспектов он может отличаться от нового API.

4.1 Структура мира

В данном разделе мы рассмотрим уровень как отдельное произведение и как единое целое и опишем первоначальное размещение компонентов игрового мира и его динамическое поведение во время игры. Давайте подробно рассмотрим задействованные в нём объекты:

4.1.1 Очертания и координаты мира

Сыграв в несколько уровней, вы наверняка заметили, что каждый экран в игре разделён на квадратные секции — 20 по горизонтали и 13 по вертикали. Хотя игроку и бывает трудно определить очертания некоторых больших уровней, мир каждого уровня имеет форму прямоугольника. Тем не менее, некоторые части уровня игрок может никогда и не увидеть, потому что путь к ним ему преграждают каменные стены или водные барьеры.

При создании мира автор должен задать его размер в секциях. Заданные ширина и высота мира являются фиксированными и не могут быть изменены впоследствии. Типичный размер — 20x13 для одноэкранного уровня. Но здесь нет никаких ограничений. Можно создавать уровни даже меньшие, чем размер экрана. Обратите внимание, что при создании больших уровней необходимо учитывать тот факт, что один ряд или колонка клеток при прокрутке обычно делится между двумя экранами. Таким образом, уровень размером 2x2 экрана имеет размер 39x25 секций, 3x4 экрана — 58x49 секций и т. д.

Края секций образуют решётку, охватывающую мир уровня. Координаты левого верхнего угла мира уровня мы определяем как {0, 0}. Первая координата показывает смещение по горизонтальной оси вправо от начала координат, вторая — смещение по вертикальной оси вниз. В одноэкранном уровне координаты секции в нижнем правом углу — {19, 12}, в то время как координаты самого угла — {20, 13} (обратите внимание, что данная точка уже не относится к уровню).

Позицию актёра, например чёрного шарика, следует задавать двумя числами с плавающей запятой, например {1.5, 2.5} для актёра, расположенного в центре секции, находящейся на пересечении третьего ряда и второй колонки, считая от левого верхнего угла.

Но большинство объектов, таких как камни, можно разместить только в соответствии с фиксированными координатами, выраженными целыми числами. Даже если попытаться поместить камень в точку {1.5, 2.5}, он окажется в точке {1, 2}. Таким образом, если при задании координат учитываются только целые числа, мы говорим об участке решётки. Легко заметить, что позиция секции определяется по её верхнему левому углу. Верхняя и левая стороны и являются принадлежащими непосредственно данной секции, правая же и нижняя сторона принадлежат соседним секциям.

Наконец, рассмотрим более детально саму секцию. На одном участке решётки можно разместить покрытие, предмет, камень и даже несколько актёров. Комбинация всех объектов на одном участке решётки называется секцией. Эти комбинации объектов нередко объявляются один раз в так называемых определениях секции. Поскольку на многих участках решётки размещаются одинаковые комбинации объектов, эти секции можно использовать многократно.

4.1.2 Слои объектов

На каждом участке решётки можно поместить покрытие, предмет и камень. Но только по одному. Если поместить второй камень, он заменит первый. Покрытие, предмет и камень расположены определённым образом по отношению друг к другу: покрытие всегда располагается под предметом, а камень над ними. Таким образом, можно говорить о трёх слоях объектов: слой покрытий, слой предметов и слой камней.

К слою покрытий предъявляется уникальное требование. Каждый участок решётки должен иметь покрытие. Существует возможность задать секцию по умолчанию с покрытием по умолчанию, которое автоматически размещается на каждом участке решётки, на котором нет другого покрытия. Даже если разрушить покрытие, то есть убрать его, не указав ему замену, оно будет заменено покрытием по умолчанию.

У покрытий есть две элементарные характеристики: трение и сцепление. Трение замедляет движения актёров, а сцепление даёт возможность ускорять актеров с помощью мыши. Покрытие может также вызывать направленную силу, которая даёт игроку ощущение наклона. Следует также упомянуть, что покрытия могут гореть. Имеется целый набор атрибутов, с помощью которых можно управлять поведением огня.

На слое предметов находятся предметы, которые актёр может подобрать, и статичные предметы. К первой группе относятся такие предметы, как ключи, бананы и т. д. К статичным предметам относятся бомбы, фугасы, триггеры, отверстия, а также предметы, которые могут быть размещены только самой системой, такие как лазеры, огонь, пепел и т. д. Поскольку на каждом участке решетки может находиться только один предмет, шарик не может поместить другой предмет на статичном предмете. По этой причине нельзя преградить путь включенному лазеру, поместив на его пути предмет. Но при написании уровня можно добавить любой предмет по своему усмотрению на первоначальную секцию решётки.

Слой камней не требует долгих объяснений. На каждом участке решётки автор может разместить по одному камню из имеющегося набора камней. Естественно, большинство участков следует оставить незанятыми, чтобы по ним могли передвигаться актёры. И хотя границы большинства уровней окружены каменной стеной, делать это не обязательно. При отсутствии стены шарики будут отскакивать от физической границы мира.

Актёры располагаются в другом слое, который не привязан к решётке. Они могут быть размещены в любом месте. Актёры, проходящие сквозь камень, будут отображаться под камнем.

4.1.3 Мир как объект

Трение, ломкость, режимы и прочее, режимы прокрутки.

4.1.4 Неразмещаемые объекты

Похоже, упущен по крайней мере один объект, который нельзя связать ни с конкретным местом на уровне, ни с одним из лежащих сверху слоев — резиновые ленты! На самом деле, кроме покрытий, предметов, камней и актеров в большом количестве существуют Остальные объекты, которые не требуется размещать на карте уровня. Кроме видимых резиновых лент и проволоки в мир можно добавить полезные гаджеты (gadgets), которые помогают составлять уровни простым добавлением новых элементов.

Все эти другие объекты полноценны, что следует из следующих глав. Но вам необходимо использовать метод мира add, чтобы добавить их, а также возможности, описанные в главах Ссылка на объект или Именование объектов, чтобы впоследствии обратиться к ним, потому что не существует способа обратиться к ним по их размещению.

4.1.5 Игрок и инвентарь

По своей концепции, Enigma — это игра для двух игроков. Тем не менее, в неё можно играть одному на единственном компьютере, переключая управление между двумя виртуальными игроками. Мы называем этих игроков Инь и Ян, поскольку первый игрок, как правило, управляет чёрным шариком, в то время как второй обычно управляет белым.

У каждого виртуального игрока есть собственный инвентарь, в котором можно хранить до 13 предметов. Самый левый предмет в инвентаре называется ‘активным’, поскольку щелчок мышью активирует этот предмет, а касание актёром чего-либо этим предметом может вызвать специальные действия.

Инвентари игроков существуют вне прямоугольного мира. Поэтому у любого предмета из инвентаря игрока позиция относительно мира недействительна, что выражается в возвращаемом на запрос ‘exists()’ значения ‘false’. С помощью дополнительного метода мира add можно добавлять предметы непосредственно в инвентари.

Хотя актёры закреплены за игроками, они достаточно самостоятельны и живут в одном из слоёв объектов (см. раздел Слои объектов). С игроками они связаны следующим образом:

каждый виртуальный игрок может управлять одним или несколькими принадлежащими ему актёрами любого типа. Это значит, что игрок Инь не обязан всегда управлять чёрным шариком ac_marble, а с тем же успехом может управлять и белым шариком ac_pearl, лошадью ac_horse или любым другим произвольным набором объектов.

Владение и управление актёрами — это две большие разницы. Владение актёром означает, что каждый предмет, подобранный актёром, оказывается в инвентаре игрока, а предметы игрока могут использоваться всеми актёрами, находящимися в подчинении игрока. Управление актёром просто приводит к передвижению актёра под воздействием сил, которые регулирует игрок. Игрок может управлять актёром при этом не владея им. Другой актёр может находиться во владении игрока, но не управляться им, являясь, таким образом, пассивным актёром, которого могут передвигать толчки других актёров. Актёр может даже управляться обоими игроками, но владеть им может максимум один игрок.

Назначение игрокам актёров однозначно регулируется атрибутами актёров (см. раздел Атрибуты актёров).

Если в Enigma играет один пользователь, то он начинает игру, управляя игроком Инь. Используя объекты Инь-Ян, он может переключиться на управление игроком Ян и обратно. При игре одним игроком на сетевых уровнях автоматически добавляются предметы it_yinyang. Они позволяют произвольно переключаться между игроками. Камни st_yinyang ограничивают способность пользователей переключаться между управлением различными игроками.

4.1.6 Подконтрольные объекты

Помимо объектов, принадлежащих игроку и входящих в его инвентарь, объекты могут временно входить в состав другого объекта. Наиболее очевидный пример — предмет, хранящийся в сумке it_bag. В качестве других примеров можно привести два камня сёгун st_shogun, расположенные на одном участке решётки, или, в течении короткого промежутка времени, камень, меняющийся местами с st_swap или st_pull.

В любом случае подконтрольный объект возвращает ту же позицию, что и его владелец. Даже если несколько объектов хранятся в сумке, которая в свою очередь хранится в другой сумке, все предметы вернут ту же позицию, что и самая внешняя сумка. Если эта сумка находится в инвентаре игрока, то все предметы вернут недействительную позицию.

Нельзя напрямую заставить объект входить в состав другого, разместив объекты в одном и том же месте, поскольку эта стандартная операция уничтожит старый объект и заменит его новым. По возможности, как в случае с сумкой, добавлять объекты в контейнер можно используя дополнительный метод мира add.

4.2 Описание объектов

Теперь, после ознакомления с размещением объектов, пришло время разобраться, как выбрать тип объекта, указать его атрибуты и впоследствии ссылаться на него.

4.2.1 Тип объекта

До настоящего времени мы говорили о таких типах объектов как покрытие ‘fl’, предмет ‘it’, камень ‘st’ и актёр ‘ac’. Все эти типы являются абстрактными. Можно проверить, принадлежит ли данный объект к какому-либо типу, но нельзя создать экземпляр абстрактного типа.

Чтобы создать объект, для него необходимо задать определённое имя типа, например ‘st_switch’. Описания всех типов объектов приведены в соответствующих главах, начиная с главы Покрытия. Для всех имён типов с по крайней мере одним подчеркиванием можно создать экземпляры.

Большинство типов подразделяются на подтипы, такие как ‘st_switch_black’ и ‘st_switch_white’. В случае с переключателями, если не добавить суффикс, то будет получен переключатель, независимый от цвета шарика. В других случаях, например в случае со ‘st_chess’, при указании одного только общего типа будет получен заданный по умолчанию ‘st_chess_black’, так как не существует бесцветных шахматных камней.

Если запросить объект по его типу, то возвращаемое значение всегда будет самого подходящего типа. Таким образом, ‘st_chess’ вернет тип ‘st_chess_black’, в то время как ‘st_switch’ не изменяет своё имя.

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

Существует несколько специальных объектов, предназначенных исключительно для создания новых объектов. Обычно в их названиях присутствует суффикс ‘_new’. Такие объекты никогда не возвращают имя своего первоначального типа, а немедленно преобразуются к стандартному типу.

Если конкретный подтип не важен, то можно проверить объект на соответствие любому общему типу. Например, если проверить переключатель любого цвета на соответствие ‘st_switch’, он вернёт значение "true".

4.2.2 Ссылка на объект

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

С помощью ссылки на объект особого типа Lua ‘object’ можно узнать текущее состояние и атрибуты объекта, модифицировать объект, посылать сообщения либо пользоваться любыми поддерживаемыми методами объекта.

Объекты можно группировать для эффективного осуществления типичных операций со всеми задействованными объектами. Например, если попробовать послать сообщение группе объектов, все объекты получат сообщение по очереди. Последовательность ряда объектов в группе является постоянной и гарантированно соблюдается при выполнении типичных операций.

Поскольку объекты могут прекратить своё существование, то следует иметь в виду, что ссылки также не являются постоянными. Есть возможность проверить существование ссылки на любой объект. Но во многих случаях действительность ссылки не имеет значения, поскольку Enigma 1.10 очень терпима по отношению к доступу к недействительным объектным ссылкам. Операции просто будут проигнорированы, а в ответ на запросы будут выданы величины по умолчанию.

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

Чтобы получить доступ к объекту при последующем вызове, к нему можно обратиться двумя способами. Во-первых, к объекту можно обратиться по его размещению. Но, поскольку многие объекты подвижны, их размещение не является постоянным. Следовательно, можно обратиться к объекту по имени (см. раздел Именование объектов).

4.2.3 Именование объектов

Чтобы длительное время иметь возможность для обращений к объекту, каждому отдельному объекту можно назначить имя. Для этого необходимо только установить для объекта атрибут ‘name’ с уникальной строкой. Естественно, имя объекта можно запросить посредством чтения атрибута ‘name’.

Имя — это строка, которая должна состоять из символов ‘a..z’, ‘A..Z’, цифр ‘0..9’ и символа подчёркивания ‘_’. Прочие символы разрешены только в случаях, рассмотренных ниже.

Необходимо следить за тем, чтобы каждому объекту было дано уникальное имя. Если повторно использовать имя, уже ассоциированное с каким-либо объектом, то этот объект лишится имени, а само имя будет ассоциировано с новым объектом. Чтобы упростить именование больших групп однотипных объектов, можно добавить знак ‘#’ в качестве последнего символа имени, например ‘mydoor#’. Это даёт программе команду добавить к строке уникальный случайный номер. Поэтому автоматически именованные объекты никогда не будут разыменованы другим объектом, именованным позднее. Но если удалить автоматически именованный объект, такой как, например ‘mydoor#103284’, то такое же имя может быть присвоено другому объекту, созданному впоследствии.

Все именованные объекты регистрируются в хранилище именованных объектов. API предлагает переменную ‘no’ , которая позволяет получить ссылку на любой именованный объект, например ‘no["mylaser_a"]’. В таких случаях выдаётся Ссылка на объект или ‘nil’, если объект с данным именем отсутствует.

Поскольку существует возможность автоматически именовать группы объектов, допускается использование символов ‘?’ и ‘*’, заменяющих прочие символы. Вопросительный знак заменяет один произвольный символ, звёздочка — любое количество символов. Например, ‘no["mydoor#*"]’ выдаёт все автоматически именованные объекты ‘mydoor’ в отдельной группе объектов.

Многие атрибуты объектов, такие как ‘target’, ‘destination’, предполагают, требуют ссылок на другие объекты. Помимо временных ссылок на объекты (см. раздел Ссылка на объект), всегда можно создать строку имени как долгосрочную ссылку на объект. Если значением атрибута могут быть несколько объектов, можно ввести группу ссылок на объекты, список имён объектов или шаблон имени объекта с символами ‘?’ и ‘*’. Таким образом, строка ‘"mydoor#*"’ является допустимой целью.

Переключатели часто располагаются рядом с подконтрольными им объектами. Чтобы значительно упростить себе жизнь, на ближайший объект группы можно сослаться, добавив в начало его имени символ ‘@’.

ti["F"] = {"st_floppy", target="@door#*"}
ti["D"] = {"st_blocker", name="door#"}

Таким объявлением секции можно с помощью двух символов секции описать на карте мира произвольное число камней-дисководов и блокирующих камней. Каждый из камней-дисководов связан с ближайшей запираемой дверью. Если два подконтрольных объекта находятся на одинаковом от него расстоянии предпочтение отдаётся расположенному с южной стороны. Если подконтрольные объекты выровнены ещё и по горизонтали, то предпочтение отдаётся восточному. В тех редких случаях, когда объекты расположены на одном и том же месте, камни предшествуют предметам, покрытиям и актерам. Выбор подконтрольного объекта зависит только от размещения этих объектов и их типа и больше ни от чего. Поэтому вполне можно положиться на стабильный механизм выбора. В случае, если выбор равноудалённых подконтрольных объектов непредсказуем, вам может помочь Группировка ближайших объектов.

Возможности автоматического именования и группировки ближайших объектов помогают уменьшить количество необходимых определений секций. Преобрахования, такие как res.autotile и res.composer — это ещё одна возможность снизить потребность в объявлении секций.

Другая уникальная особенность имён объектов — это их предварительное объявление. Это даёт возможность ссылаться на ещё не существующий объект. Так, если требуется поместить на уровне два телепорта, каждый из которых будет точкой назначения для другого, использование имён объектов будет идеальным решением:

wo[{3,4}]  = {"it_vortex", name="vortex1", destination="vortex2"}
wo[{15,9}] = {"it_vortex", name="vortex2", destination="vortex1"}

В таких случаях придётся использовать ссылки на имена объектов в объявлениях секций, поскольку ни один из упомянутых объектов на момент объявления ещё не существует.

Со временем объекты могут изменяться. Двери открываются, шахматы меняют цвет, блокирующий камень может сжаться до блокирующего предмета. Это означает, что меняется и тип объекта. Но во многих случаях это также означает, что временные ссылки на объект также станут недействительными. Для удобства авторов сущность объекта будет перенесена на новый объект, даже если ссылка станет недействительной. И подобно пользовательским атрибутам, имя — это часть сущности объекта. Таким образом, если присвоить имя камню st_blocker, а затем он сожмётся в it_blocker, то этот предмет можно запросить в хранилище именованных объектов, использовав имя объекта.

Когда объект полностью уничтожается, например, дверь разрушается с помощью it_seed, он больше не может быть подконтролен активным объектам наподобие переключателей. Всё ещё существующая ссылка на уже не существующий объект не вызовет проблем для пересылки Сообщения. А как насчёт ссылок на ближайший объект? Во избежание проблем, вызванных уничтожением объектов, стандартная ссылка на ближайший объект, предваряемая приставкой ‘@’, окончательно формируется на этапе инициализации уровня (см. раздел Инициализация уровня). Это означает, что она заменяется уникальным именем ближайшего объекта, который существовал после создания всех объектов и до того момента, когда пользователь получает возможность действовать и может разрушить объект.

Но иногда предпочтительнее работать с подконтрольными объектами динамически. При этом объекты обрабатываются во время доступа к ним. Если добавить к имени приставку ‘@@’, то ссылка при инициализации будет сформирована не до конца, а останется динамической.

ti["c"] = {"it_coin_s", "magic#"}
ti["v"] = {"it_vortex", destination="@@magic#*"}

Если разместить на карте три волшебные монеты и один телепорт, то шарик будет телепортирован к ячейке, на которой размещается ближайшая (на момент телепортации) к телепорту монета.

Во избежание непредвиденных проблем с недействительными ссылками на объект, некоторые наиболее важные объекты автоматически именуются системой, если автор уровня не предлагает свой вариант имени. Но эти уникальные имена не создают помех пользовательскому именованию объектов.

4.2.4 Атрибуты объектов

Один из ключевых факторов в обеспечении гибкости и разнообразия игры — это возможность тонкой настройки поведения объектов при помощи атрибутов. Автор уровня не ограничен фиксированным набором объектов определённого вида с предварительно заданными характеристиками.

Атрибут — это имя, строка с приписанным ей значением. Например, ‘obj["inverse"]=true’ задаёт булево значение отдельному атрибуту объекта, а ‘{"it_magnet", range=6.5}’ описывает магнит с первоначально заданным атрибутом с плавающей запятой.

Набор этих значений многообразен. Могут быть присвоены большинство типов Lua и ряд типов, характерных только для Enigma :

• bool
• int
• double
• string
• nil, DEFAULT
• position
• object
• group
• tokens

Понятие "булево значение" мы употребляем в том смысле, в котором оно употребляется в Lua 5, то есть оно может иметь значения ‘true’ и ‘false’.

Многие значения перечисляемого типа, такие как направления или цвета, выражаются целыми числами.

Особый интерес представляет значение ‘nil’. Лишь немногие атрибуты непосредственно используют значение ‘nil’, например "color" (цвет) для некоторых объектов. Задание атрибуту значения ‘nil’ изменит его значение на значение по умолчанию. Например, если установить для атрибута "orientation" (направление) объекта st_boulder значение ‘nil’, оно будет изменено на значение по умолчанию, каковым является ‘NORTH’ (север), значение направления перечисляемого типа. Последующее чтение атрибута вернёт это значение. Только атрибуты, которые допускают нулевое значение, выдадут ‘nil’ при доступе. Отсюда напрямую следует, что значения этих атрибутов по умолчанию всегда равны ‘nil’.

Разработчики Lua решили прекратить использование ‘nil’ в качестве значений в списках Lua. Так как в качестве определений объектов мы часто пользуемся анонимными списками, таким атрибутам нельзя будет присвоить значение ‘nil’. Такие атрибуты придётся устанавливать явно. Может пригодиться и добавленное нами значение ‘DEFAULT’, которое можно использовать для установки атрибутов где угодно, даже в списках Lua.

mySwitch["color"] = nil
mySwitch["color"] = DEFAULT
wo[{3,6}] = {"ac_marble_black", player=DEFAULT}

Заметим, что ‘DEFAULT’ — это не ‘nil’. В контексте Lua это разные значения. Просто оба они вызывают сброс атрибутов к значениям по умолчанию. Если запросить атрибут с нулевым значением, то всегда будет получено значение Lua ‘nil’. Движок никогда не вернёт ‘DEFAULT’.

Группа — это упорядоченный набор ссылок на объект (см. раздел Ссылка на объект). Так как к моменту их использования все содержащиеся в ней объекты уже должны существовать, то это значение редко используется для атрибутов при объявлении объектов. Но она очень полезна для постобработки объектов и использования в функциях обратного вызова (см. раздел Функция обратного вызова).

Самый сложный тип значений атрибута — это метки. Их назначение — определение одного или нескольких объектов. Так как в Enigma предусмотрено несколько способов это сделать, в этом типе значений объединены и перемешаны все возможности. Метка может быть строкой с именем объекта, ссылкой на объект, а также группой либо списком, в которых перечислены любые их этих типов в любом количестве и порядке. Так, справа в приведённой ниже колонке находятся допустимые метки атрибута ‘target’:

obj1["target"] = "mydoor"
obj2["target"] = myobject
obj3["target"] = grp(ojb1, obj2, obj3)
obj4["target"] = {"mydoor", myobject}
obj5["target"] = {grp(ojb1, obj2, obj3), "mydoor", myobject, "anotherdoor"}

Подобная гибкость может быть полезной при задании меточных атрибутов, независимых от типов ссылок на заданный объект.

В главе Общие атрибуты и сообщения и последующих главах приведены подробные описания существующих атрибутов объектов.

Помимо этих предварительно заданных атрибутов, автор уровня может хранить свою собственную информацию об объектах для дальнейшего использования. Любое имя, начинающееся со знака подчеркивания ‘_’, может быть использовано для целей, специфичных для данного уровня. Данная приставка была выбрана в силу того, что получающиеся в результате её добавления имена все ещё являются действительными именами Lua. Типичная сфера их использования — это переключатели и триггеры с функциями обратного вызова. Эти функции ожидают в качестве аргумента отправителя (переключатель или триггер). Если планируется ассоциировать одни и те же функции с несколькими отправителями, то можно хранить необходимую контекстную информацию в отправителе.

Внутренний движок также использует атрибуты объектов. Имена таких недоступных атрибутов начинаются со знака ‘$’. Они могут указываться в документации для сведения разработчиков, использующих язык C++. Авторам уровней следует игнорировать эти атрибуты.

В некоторых случаях можно наблюдать различное поведение при установке атрибутов во время определения объекта и установке того же атрибута, когда объект уже находится на решётке. Например, дверь ‘{"st_door_h", state = OPEN}’ открыта с самого начала, в то время как ‘mydoor["state"] = OPEN’ по отношению к закрытой двери открывает эту дверь. Открытие двери в таком случае занимает некоторое время. Подробности смотрите в разделе Жизненный цикл уровня.

После просмотра кода на C++ могут возникнуть вопросы по поводу задействования атрибутов. Не все атрибуты находятся непосредственно на карте. Некоторые из них хранятся в переменных экземпляров объектов, другие вообще не существуют. Атрибуты объектов — это абстрактное понятие, которое объединяет несколько внутренних характеристик в рамках простого общего API кода уровня. В движке C++ малозаметные причины, такие как оптимизация работы программы, требуют значительно более сложного манипулирования.

4.3 Способы взаимодействия

Описав первоначальное размещение объектов в мире уровня, мы теперь должны понять, как управлять динамическим поведением уровня.

4.3.1 Сообщения

Открытую дверь можно сгенерировать, установив её атрибуты. Но как же сделать так, чтобы переключатель открывал дверь, когда до него дотронешься шариком? Он просто посылает двери сообщение ‘open’. Другие переключатели могут посылать сообщение ‘on’ ("включиться") лазеру, или ‘ignite’ ("загореться") объекту it_dynamite. При взрыве динамит в свою очередь пошлёт сообщение ‘ignite’ соседним участкам решётки.

Сообщение — это простая универсальная функция или, с точки зрения объекта-получателя и автора уровня, "метод". Он может принимать два аргумента — имя сообщения, строка и необязательное значение, Например:

mydoor:message("open")
myboulder:message("orientate", NORTH)

mydoor:open()
myboulder:orientate(NORTH)

Последние два примера — это стандартное сокращение первых двух.

Сообщения могут возвращать значения. Но большинство сообщений возвращают просто ‘nil’.

Сообщение можно послать любому объекту. Неподдерживаемые сообщения игнорируются без видимых результатов. В силу этого взрывающийся динамит может посылать сообщение ‘ignite’ соседним секциям, не имея сведений о том, могут ли объекты вообще загораться. Так что динамиту совершенно не важны получатели сообщения. В силу специфики сообщений их отправители и получатели полностью разъединены в том, что касается кода. Таким образом, автору уровня необходим только один метод, позволяющий посылать произвольные сообщения произвольным объектам.

Не посылайте сообщений при инициализации уровня. Переключатель можно запрограммировать на отправление двери сообщения ‘open’ при помощи цели-действия (см. раздел Цель-действие). С помощью функции обратного вызова Lua (см. раздел Функция обратного вызова) можно послать сообщение любому объекту во время его функционирования.

В главе Общие сообщения и последующих главах перечислены и описаны все сообщения.

4.3.2 Цель-действие

"Механизм цели-действия" — это классический объектно-ориентированный метод, позволяющий легко связывать объекты. Один объект активируется вызовом функции или событием (например, актёр, дотрагивающийся до камня, проходящий над предметом либо задействующий его). Вам необходимо просто связать этот объект с другим целевым объектом и приказать ему отправить сообщение о действии. Каждый раз, когда первый объект активируется, он будет посылать сообщение своей цели.

Задать "цель-действие" можно с помощью атрибутов ‘target’ и ‘action’, применённых к первому объекту. Например, чтобы переключатель открыл дверь, которой присвоено имя ‘mydoor’, можно написать:

{st_switch, target="mydoor", action="open"}

Объекты, такие как переключатели, можно включать и выключать. Каждый раз они будут совершать какое-либо действие. Если требуется, чтобы дверь открывалась и закрывалась по команде переключателя, понадобится не ‘open’, а другое действие. Универсальным сообщением, чередующим состояния целевых объектов, является ‘toggle’.

{st_switch, target="mydoor", action="toggle"}
{st_switch, target="mydoor"}

Теперь дверь будет поочередно открываться и закрываться при активации переключателя. Сообщение toggle может быть использовано независимо от целевого объекта. Фактически оно является сообщением о действии, которое используется по умолчанию. Таким образом, его можно и не указывать, что было продемонстрировано во втором примере.

Но помните, что это сообщение только чередует состояния целевого объекта. Если вначале переключатель у вас будет выключен, а дверь открыта, то при его включении дверь закроется. Они не будут синхронизированы. Если создать два переключателя, целью которых является одна и та же дверь, то между положением переключателя и состоянием двери не будет прямой зависимости.

Как вы помните, сообщения могут принимать значения. Сообщения о действиях не исключение. Каждый объект отправляет свое действие с некоторым значением, обычно булевым. Переключатель посылает значение ‘true’, если его включить, и ‘false’, если его выключить. Подходящим сообщением для двери будет универсальное сообщение ‘signal’:

{st_switch, target="mydoor", action="signal"}

Теперь дверь будет открываться при включении переключателя и закрываться при его выключении.

Сообщение signal принимает целочисленное значение ‘0’ или ‘1’. Действительно, значение действия не совпадает. Но, как и во многих других случаях, сообщения и значения сконструированы таким образом, что они автоматически преобразуются к необходимому типу. Эта совместимость является основой для лёгкого объединения объектов.

Во многих случаях перед авторами встаёт необходимость активировать одним объектом несколько других объектов. Как ‘target’, так и ‘action’ могут принимать несколько значений. ‘target’ относится к значению типа "метка" (см. раздел Атрибуты объектов), в то время как ‘action’ может быть строкой или списком строк.

{st_switch, target={grp(ojb1, obj2, obj3), "mydoor", myobject, "anotherdoor"},
            action={"toggle",              "open",   "turn",   "close"}}

Все объекты, описанные при помощи метки, получают сообщение в списке действий. Если перечислено недостаточно сообщений, то будет послано действие по умолчанию ‘toggle’.

Обычно действия совершаются сразу же. Это очень важно, поскольку порядок действий часто играет большую роль. К примеру, ящик st_box сдвигается с одного триггера it_trigger на соседний или просто шарик ac_marble перемещается с первого триггера на соседний. В обоих случаях важно, чтобы первый триггер был отпущен до того, как будет нажат второй. Если эта последовательность изменяется так, что оба триггера одновременно могут быть нажаты одним объектом, то это может стать огромной дырой в балансе уровня. Поэтому все действия производятся в логичной и стабильно повторяющейся последовательности без намёка на случайность.

Действия представляют собой простые, а иногда и очень сложные изменения в мире. Но в любом случае даже не думайте ‘уничтожать’ (‘kill’) объект-отправитель. Уничтожение отправителя может обрушить приложение! Следите за тем, чтобы даже объединённые в цепочку действия не могли уничтожить своего объекта-отправителя. Поэтому триггер (it_trigger), который переключает выключатель st_switch, который в свою очередь уничтожает первый триггер, так же опасен, как и триггер уничтожающий сам себя. Мы не советуем уничтожать какой-либо объект, используя его собственное действие, поскольку его уничтожение не будет анимироваться, а кроме того, будет нарушен принцип WYSIWYG ("Что Ты Видишь, То Ты И Получишь" — прим. перев.). Но если это просто необходимо для соблюдения игровой логики, такое действие можно осуществить в безопасном, отсроченном режиме. Просто добавьте к уничтожаемому объекту атрибут safeaction со значением ‘true’. С этого момента действия будут производиться не мгновенно, а с минимальной задержкой, таким образом, чтобы никогда не обрушить приложение. Но помните, что даже минимальная задержка, не выходящая за пределы соответствующего отрезка времени, может нарушить последовательность действий, приведя к неожиданным результатам.

4.3.3 Функция обратного вызова

Функции обратного вызова — самое мощное расширение парадигмы Цель-действие, которое только можно себе представить. Вместо целевого объекта в качестве получателя сообщения о действии можно использовать встроенную в Lua функцию, которая вызывается всякий раз, когда запрашивается действие.

{"st_switch", target="my_magic", action="callback"}
{"st_switch", target="my_magic"}

‘target’ — это строка, состоящая из имени функции. Для уточнения можно присвоить параметру ‘action’ строку ‘"callback"’, но, как видно из второго примера, это необязательно. Движок определяет, что типом цели является функция Lua, а значит действие должно быть возвращаемым. Однако вы должны следить, чтобы имена всех объектов и функций обратного вызова были уникальны.

Давайте посмотрим на синтаксис типичной функции обратного вызова:

function my_magic(value, sender)
    if value == true then
        wo[sender + {1,0}] = {"it_coin_s"}
    end
end

Функция вызывается с двумя аргументами. Первый — значение. Его тип и содержимое зависит от конечного объекта, но в большинстве случаев это булево значение. Описание значения можно найти в описании объектов. Второй аргумент — ссылка на вызывающий объект.

В приведённом примере мы проверяем, был ли st_switch только что переведён в состояние "включен" (ON). Если так оно и есть, берём за точку отсчёта переключатель, который представляет собой отправителя, и размещаем к востоку от него монету it_coin — небольшой банкомат для снятия денег со счёта.

В разделе Примеры сложных уровней на языке Lua будут приведены примеры по-настоящему мощных функций обратного вызова с комментариями к каждой строке.

Описание дальнейшего использования и других аспектов обратных вызовов приведены в разделе Обратные вызовы и таймеры.

4.3.4 Состояние объекта

Ключевым понятием в объединении объектов, таких как переключатели и двери, являются простейшие механизмы состояния этих объектов. Большинство объектов описываются при помощи простых механизмов состояния, включающих только два состояния, такие как ‘ON’,‘OFF’ или ‘OPEN’, ‘CLOSED’. Эти объекты можно связать несколькими общими сообщениями. Кроме того, эти простейшие механизмы состояния подстраиваются под игроков, которые хотят не читать руководства, а исследовать объекты в самой игре.

Хотя состояниям обычно присваиваются имена, состоящие из прописных букв (см. примеры выше), состояния — это целые числа, начиная с ‘0’, который обычно соответствует состоянию по умолчанию. Но некоторые объекты в силу исторических причин используют другие привязки. Так, для состояний, связанных с направлением, состоянием по умолчанию обычно является ‘3’, соответствующее направлению ‘NORTH’ ("север"), а прочие состояния нумеруются по часовой стрелке вплоть до ‘0’, соответствующего направлению ‘WEST’ ("запад").

В большинстве случаев достаточно выполнить независимое от состояния общее действие, такое как toggle. Даже два уже заданных объекта можно легко синхронизировать стандартным действием signal. Но иногда может понадобиться осуществить действие, находящееся в очень сильной зависимости от состояния. Рассмотрим, как это можно сделать.

Возьмём, к примеру, st_fourswitch, у которого есть четыре состояния, и два объекта st_laser, каждый из которых может быть как включен, так и выключен. Каждый из лазеров светится в трёх из четырёх состояний четырёхпозиционного переключателя. Но один из них выключается, когда переключатель находится в положении ‘EAST’ ("восток"), а другой — в положении ‘WEST’ ("запад"). Это можно сделать при помощи следующих зависимых от состояния целей и действий:

{st_fourswitch, target_3="laser#2", action_3="on",
                target_2="laser#1", action_2="off",
                target_1="laser#1", action_1="on",
                target_0="laser#2", action_0="off"}

Добавив число в качестве суффикса к ‘target_’ и ‘action_’, можно получить специальные атрибуты цели и действия, которые будут обладать приоритетом перед общими атрибутами ‘target’ и ‘action’, если значение состояния равно указанному в суффиксе номеру. Альтернативным объявлением будет следующее:

{st_fourswitch, target={"laser#1", "laser#2"},
              action_3={"nop",     "on"},
              action_2={"off",     "nop"},
              action_1={"on",      "nop"},
              action_0={"nop",     "off"}}

Здесь мы обращаемся к обоим лазерам во всех состояниях. Но один из них получает сообщение nop, которое означает "операция отсутствует". Фактически данное сообщение никогда не посылается. Это просто формальное сообщение, которое в приведённом выше случае нам необходимо использовать из-за требований синтаксиса.

Рассмотрим другой пример: два объекта it_trigger, включающие лазер. При нажатии на первый триггер лазер должен включиться, а при нажатии на второй — выключиться. Но у триггера есть два состояния, и он выполняет одно действие, если на него нажать, и другое, если его отпустить. Таким образом, нам необходимо заблокировать действия, осуществляемые, если отпустить триггер:

{it_trigger, name="on_trigger",  target="laser#1", action_1="on", action_0="nop"}
{it_trigger, name="off_trigger", target="laser#1", action_1="off", action_0="nop"}

Блокировка ‘action_0’ очень важна, и её нельзя пропускать, так как в этом случае будет осуществлено действие по умолчанию. Это будет сообщение ‘toggle’, которое включит лазер.

Так как этот полезный механизм, действующий по умолчанию, может и помешать, сообщение по умолчанию можно отключить, установив для атрибута nopaction значение ‘true’.

{it_trigger, name="on_trigger",  target="laser#1", action_1="on", nopaction=true}
{it_trigger, name="off_trigger", target="laser#1", action_1="off", nopaction=true}

Когда объект удаляется с триггера, будет выполнено действие, соответствующее состоянию ‘0’. Так как ни ‘action_0’, ни ‘action’ не определены, будет выполнено действие по умолчанию, в данном случае ‘nop’.

Заглянув в код C++, можно заметить, что у многих объектов значительно более сложные механизмы состояния, чем могут предполагать авторы уровней и игроки. Это происходит из-за использования анимации, таймеров и т. д. На набор внутренних состояний объектов C++ накладывается куда более простой набор внешних состояний. Это главная причина того, почему некоторые характеристики, предлагаемые авторами уровней, не могут быть осуществлены в Lua API.

4.4 Жизненный цикл уровня

Загрузка уровня по принципу снимка, инициализация, обратные вызовы во время выполнения, условия завершения — загадка оксидов и медитации

4.4.1 Предварительная загрузка библиотек

4.4.2 Принцип снимка

Большинство уровней содержит объекты, влияющие друг на друга. Переключатель может открывать и закрывать дверь при помощи "цели-действия" (см. раздел Цель-действие), шарик может нажать на триггер, а лазер может активировать лазерный переключатель или превратить молоток в меч. Естественно, вам необходимо знать, как можно получить желаемую конфигурацию объектов, чтобы они не претерпевали непредусмотренные изменения при инициализации уровня.

Принцип снимка — это простое практическое правило, на которое можно положиться, описывая уровень как снимок объектов в данный момент времени. Каждый объект необходимо настраивать так, как он должен быть настроен в данный момент времени. Все взаимодействия, имеющие место во время игры, не осуществляются при размещении объектов во время инициализации.

Например, если переключатель должен открывать и закрывать дверь и переключатель в начале уровня должен быть включен, а дверь открыта, объект необходимо описывать именно с такими атрибутами:

{"st_switch", target="mydoor", state=ON}
{"st_door", name="mydoor", state=OPEN}

Если включённый лазер направлен на лазерный переключатель, то переключатель должен быть изначально активирован. Но, конечно, атрибута, позволяющего предварительно активировать лазерный переключатель, не существует. Принцип снимка включает в себя правило, что все внутренние состояния обновляются без внешних действий. Это означает, что переключатель будет находиться в активированном состоянии в начале уровня, не давая команду своей цели осуществить действие.

{"st_laser", state=ON}
{"st_laserswitch", target="mydoor"}

Теперь рассмотрим объекты, трансформирующиеся под воздействием лазера. Принцип снимка не даёт объектам трансформироваться во время инициализации. Молоток, который находится на пути у лазерного луча, не превратится в меч при инициализации уровня. Он останется молотком и сможет превратиться в меч при повторном воздействии лазера во время игры.

Описания невозможных начальных состояний уровня, конечно, не допускаются. Такие объекты, как динамитные шашки, немедленно взрываются под воздействием лазерного луча. Таким образом, динамит на пути у лазерного луча в начале уровня — это ошибка, вызывающая исключение. Принцип снимка заставляет в этом случае поместить на уровне объект, отвечающий за реализацию взрыва (it_explosion), вместо динамита.

Некоторые объекты всё же осуществляют трансформации внутреннего состояния, которые невозможно задать атрибутами. Но некоторые из этих состояний могут представлять интерес при описании снимка уровня. Везде, где возможно, существуют особые подтипы объектов с суффиксом ‘_new’. Эти объекты могут быть использованы при первоначальном описании уровня, чтобы разместить объекты с особыми начальными состояниями. Такой подтип существует, например, для it_blocker. Обратите внимание, что такие объекты никогда не возвратят свой первоначальный подтип при запросе типа, поскольку они начинают своё существование как стандартные объекты.

4.4.3 Инициализация уровня

Определившись с тем, что должно быть предварительно загружено и в каком состоянии должны появиться определённые объекты, наступило время взглянуть на то, как обрабатывается код уровня. Основная проблема состоит в том, чтобы гарантировать, что все связанные части заранее будут правильно настроены.

Перед выполнением первой строки кода мир существует просто как абстрактное вместилище, а не как массив-решётка, способный принимать объекты. Поэтому первые строки кода должны настроить все Глобальные атрибуты, необходимые значения которых отличаются от значений по умолчанию. Не смотря на то, что многие атрибуты впоследствии можно настроить и изменить даже во время выполнения, существуют такие атрибуты как ProvideExtralifes, который имеет смысл устанавливать, только перед созданием мира, или MaxOxydColor, который следует устанавливать перед его первым использованием. Мы рекомендуем выносить настройку всех глобальных атрибутов в самое начало уровня.

Вторым участком в коде уровня должно стать описание секций. Поскольку эти строки кода просто описание, они не размещают объекты в мире, зависят только от глобальных атрибутов и могут ссылаться друга на друга. Их перечисление в одном участке кода упрощает обзор кода и помогает избежать конфликтов зависимостей.

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

Главное выражение в любом уровне — это Создание мира. Оно задаёт размеры мира и располагает предметы в пределах решётки мира, согласно заданным описаниям секций. Хотя позже можно свободно добавить или изменить любой из объектов, размеры мира фиксированы и неизменны.

Поэтому следующие строки кода должны добавлять (add) другие объекты, рисовать дополнительные карты объектов или дополнять некоторые объекты. Общеупотребительным выражением подобного дополнения является метод shuffleOxyd. Для того, чтобы перекрасить и перемешать оксиды (st_oxyd), ему необходимо знать о всех оксидах на уровне. Ещё одним примером дополнения можно считать генерирование требуемого лабиринта, которое придаёт карте уровня форму лабиринта (см. раздел res.maze).

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

Другой набор функций, которые могут быть добавлены — Функции обратного вызова. Мы советуем добавлять эти функции в последней секции кода, потому что они не вызываются непосредственно во время инициализации уровня.

Однако существует одно особое исключение. Функция обратного вызова postinit() вызывается после того, как выполнился код инициализации уровня и завершились все последующие инициализации внутри движка. Если эта функция присутствует в уровне, то она выполняется непосредственно перед обработкой первого события перемещения мыши. А значит, при использовании этой функции можно быть уверенным, что все объекты находятся в своём окончательном состоянии. Перед использованием функции обратного вызова postinit() её следует поместить после всего кода инициализации уровня, но перед остальными функциями обратного вызова, которые будут исполняться при последующих событиях.

4.4.4 Преобразование объекта

Во время игры некоторые объекты Enigma преобразуются в другие объекты-потомки, такие как st_blocker/it_blocker, st_brake/it_brake, it_rubberband/ot_rubberband, it_hammer/it_sword и т. д.

Не смотря на то, что у объекта-потомка могут быть другие атрибуты, некоторые атрибуты, и в частности пользовательские атрибуты, необходимо сохранить. Имена объектов, их атрибуты цели и действия и все атрибуты, начинающиеся со знака подчеркивания (‘_’) — пользовательские атрибуты — наследуются объектом-потомком. Поэтому потомок объекта может точно так же получать сообщения в качестве цели, как и ранее существовавший на его месте объект, и к нему можно обратиться, используя его старое имя.

4.4.5 Именованные позиции

Многие камни можно перемещать и, даже если пользователь не может оттолкнуть их, большинство может поменяться местами с рядом стоящим обменным камнем. Актёры могут поднимать предметы, которые могут быть уничтожены во всепоглощающем пламени. Поэтому в большинстве случаев, предпочтительно помечать на полу якоря или формы. В каждой ячейке решётки существует объект покрытия, который намного стабильнее всех остальных объектов. Тем не менее, пользователь может сбросить в воду (fl_water) или бездну (fl_abyss) ящик (st_box), камень-головоломку (st_puzzle) или другой строительный камень. Более того, пользователь может оставить зажжённую бомбу (it_bomb), которая разрушит покрытие и оставит на его месте бездну (fl_abyss). В любом из этих случаев можно лишиться именованного якоря или важной части именованной области решётки, доступной в виде группы объектов.

Поэтому позиция каждого уничтоженного именованного покрытия остаётся в хранилище под своим именем. Чтобы получить позицию любого возможного покрытия, вместо именованных объектов следует запрашивать именованные позиции.

ti["~"] = {"fl_water", "water#"}
...
function sweet()
    wo[po["water#*"]] = {"it_cherry"}
end

Следует отметить, что наряду со всеми позициями именованных объектов, удовлетворяющих шаблону на запрос именованной позиции будут выданы именованные позиции уничтоженных покрытий.

4.4.6 Обратные вызовы и таймеры

Наиболее гибким свойством, позволяющим автору обеспечить уникальное поведение уровня, являются функции обратного вызова.

Цели-действия убивают предупреждающий ot_timer.

Глобальные функции и функция res.*.

4.4.7 Перезапуск уровня

4.4.8 Условия завершения

Теперь нам необходимо ответить на два важных вопроса: когда и при каких условиях уровень будет являться успешно завершённым? Как можно объявить медитативный уровень в противоположность стандартному уровню, основанному на открытии пар оксидов.

Флаг "медитации" по сути отсутствует как в информации о метаданных , так и среди глобальных атрибутов. Это означает, что формальное разграничение между двумя видами уровней отсутствует. Но есть два вида условий завершения. Оба проверяются постоянно и первое выполненное условие приводит к завершению уровня. Таким образом, Enigma даёт возможность писать действительно гибридные уровни, в которых присутствуют как объекты st_oxyd, так и it_meditation, позволяя пользователю решить уровень двумя абсолютно различными способами.

Главный способ закончить игру — это выполнить условие открытия пар оксидов:

игра считается завершённой после того, как пользователь попарно откроет все стандартные окрашенные пары камней st_oxyd.

Соответственно, подразумевается, что на уровне имеется по крайней мере одна пара стандартных окрашенных оксидов и что для всех оксидов одного цвета имеется чётное количество экземпляров. В то время как в стандартном уровне всегда будет хотя бы одна пара оксидов, за количеством экземпляров бывает трудно уследить. Поэтому движок постоянно проверяет во время выполнения, является ли количество экземпляров оксидов каждого цвета чётным. Нарушение данного условия приведёт к ошибке. Если вы добавляете или удаляете оксиды на уровне, эту проверку необходимо отключить, установив для атрибута AllowSingleOxyds значение true. Теперь ответственность за возможность решения уровня несёте вы и добавлять или удалять оксиды вы должны только попарно.

Вторым способом завершения игры является выполнение условия медитации:

все объекты ac_pearl должны находиться в течение не менее чем одной секунды в неровностях it_meditation, все it_meditation, помеченные как essential, должны быть заняты, и количество ac_pearl должно быть равно количеству занятых it_meditation.

Опять же, это подразумевает, что на уровне существует по крайней мере один объект ac_pearl и что в одном и том же объекте it_meditation не могут одновременно находиться две жемчужины. На уровне должно находиться не меньше объектов it_meditation, чем на нём есть ac_pearl; объектов it_meditation может быть и больше, если они не отмечены как essential. Избыток объектов it_meditation может легко получиться в результате взрывов it_dynamite.

На уровне, который необходимо решить, выполнив условие медитации, могут находиться объекты st_oxyd; установив для атрибута AllowSingleOxyds значение true, можно добавить на уровень нечётное количество оксидов одного цвета. С другой стороны, на уровень, который должен быть решён путём выполнения условия открытых пар оксидов, можно добавить ac_pearl. Но необходимо внимательно следить, чтобы пользователь не мог поместить жемчужины в имеющиеся объекты it_meditation и чтобы он не мог создать новые объекты it_meditation при помощи it_dynamite. Непредусмотренных решений можно избежать, отметив в качестве essential большее количество объектов it_meditation, чем на уровне имеется ac_pearl.

Уровень, который изначально позволяет пользователю выполнить оба условия завершения, называется гибридным. Конечно же, предусмотреть равноценные решения для обоих подходов — нелёгкая задача.

Вне зависимости от типа условий завершения все актёры, отмеченные как essential, должны оставаться в живых в момент выполнения этих условий. Автор также может позволить пользователю пожертвовать актёром, чтобы выполнить условия завершения, установив для атрибута SurviveFinish значение false (подобная опция в основном необходима для поддержания совместимости с уровнями, написанными для предыдущих версий, но её также можно использовать и для новых уровней при условии их тщательного планирования). В этом случае шарик может разбиться, но условие всё равно будет выполнено. Конечно же, актёры, указанные как essential, не могут разбиться заранее, поскольку после того, как такой актёр будет уничтожен, в случае, если его нельзя воскресить, уровень будет перезапущен.

5. Lua API

Теперь, после изучения основных принципов мира уровней Enigma, осталось лишь разобраться языком программирования, чтобы приступить к написанию своего первого уровня. Уровни Enigma написаны на языке Lua 5.1.4. Этот мощный язык позволяет вам писать самые сложные, динамические уровни и в то же время он достаточно понятен для того, чтобы написать простые стандартные уровни. Действительно, зачем в самом начале копаться в тонкостях языка?

Для второй версии Lua API (интерфейс программирования приложений Lua), используемой в Enigma 1.10, мы разработали более оптимальный подход к описанию уровней, который позволяет сделать его кратким и легко читаемым. Поэтому мы познакомим вас с этим API, разобрав несколько примеров, начиная с простого уровня и заканчивая самыми настоящими захватывающими динамическими уровнями Enigma. Свои первые эксперименты можно начать уже после ознакомления с первым примером и пояснениями к нему.

Чтобы вам было удобно, код Lua мы будем выделять цветом. Предопределённые (или встроенные) переменные и функции Lua мы будем выделять зелёным цветом. Встроенные строковые константы Enigma, такие как типы объектов или названия атрибутов и сообщений, выделяются синим. Названия переменных и их значения, относящиеся только к какому-то конкретному уровню, окрашены в пурпурный цвет.

После разбора примеров и краткого обзора мы подробно рассмотрим особенности API языка, ведь это как раз то, что каждый ожидает увидеть в справочном руководстве. Пожалуйста, обратите внимание на то, что Дополнительные возможности описаны в отдельной главе.

5.1 Примеры простых уровней на языке Lua

Давайте рассмотрим два простых одноэкранных уровня, в которых используются все основополагающие принципы. В то время как первый уровень, созданный только для примера, немного искусственный, второй — довольно динамичный уровень, который можно найти в пакетах уровней Enigma.

5.1.1 Простой пример

Давайте взглянем на исходный код. В первые две колонки мы добавили номера строк, чтобы на них можно было ссылаться в этом разделе. Эти номера строк не являются частью самого исходного кода!

 1    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 2    <el:level xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
 3     <el:protected>
 4       <el:info el:type="level">
 5         <el:identity el:title="Basic Level" el:subtitle="" el:id="20080721ral513"/>
 6         <el:version el:score="1" el:release="1" el:revision="$Revision: 1.19 $" el:status="experimental"/>
 7         <el:author el:name="Ronald Lamprecht" el:email="ral@users.berlios.de"/>
 8         <el:copyright>Copyright © 2008 Ronald Lamprecht</el:copyright>
 9         <el:license el:type="GPL v2.0 or above" el:open="true"/>
10         <el:compatibility el:enigma="1.10"/>
11         <el:modes el:easy="true" el:single="true" el:network="false"/>
12         <el:score el:easy="-" el:difficult="-"/>
13       </el:info>
14       <el:luamain><![CDATA[
15
16    wo["ConserveLevel"] = true
17
18    ti[" "] = {"fl_samba"}
19    ti["."] = {"fl_abyss"}
20    ti["~"] = {"fl_water"}
21    ti["#"] = {"st_granite"}
22    ti["X"] = {"st_oxyd"}
23
24    ti["L"] = {"st_laser", orientation=EAST, state=ON}
25    ti["M"] = {"st_lightpassenger", interval=0.04}
26
27    ti["P"] = {"st_polarswitch", name="polar"}
28    ti["T"] = {"it_trigger", target="polar"}
29
30    ti["^"] = {"st_boulder", "boulder", orientation=NORTH}
31    ti["F"] = {"st_fourswitch", target="boulder", action="orientate"}
32
33    ti["D"] = {"st_door_d", "door", faces="ew"}
34    ti["B"] = {"it_blocker", "wall#"}
35    ti["S"] = {"st_switch", target={"door", "wall#*"}}
36
37    ti["v"] = {"it_vortex", "left", destination="right"}
38    ti["V"] = {"it_vortex", "right", destination="left"}
39
40    ti["O"] = {"st_turnstile", flavor="red"}
41    ti["E"] = {"st_turnstilearm", orientation=EAST}
42    ti["N"] = ti["."] .. {"st_turnstilearm_n"}
43
44    ti["+"] = {"fl_samba", checkerboard=0} .. ti({"fl_wood", checkerboard=1})
45
46    ti["1"] = {"#ac_marble"}
47
48    if wo["IsDifficult"] then
49        ti["="] = ti["~"]
50    else
51        ti["="] = ti["~"] .. {"it_strip_ew"}
52    end
53
54    w, h = wo(ti, " ", {
55        "####################",
56        "#      ....++++++~ #",
57        "L   PM ..N.++~~~~OE#",
58        "#######  T~++++++. #",
59        "#     ^   ~++++++# #",
60        "#         =++++++X X",
61        "#         ~++++++# #",
62        "#~~~~~~~~~~~~~+++X X",
63        "#    ~   B   ~+++###",
64        "F    ~   B   ~+++++#",
65        "# 1  ~   B   #+++++#",
66        "S   v~V  B   D+++++#",
67        "####################"
68    })
69
70    wo:shuffleOxyd()
71
72     ]]></el:luamain>
73        <el:i18n>
74          <el:string el:key="title">
75            <el:english el:translate="false"/>
76          </el:string>
77        </el:i18n>
78      </el:protected>
79    </el:level>

Получившийся уровень выглядит в игре следующим образом:

Теперь давайте рассмотрим код строка за строкой.

В строках с 1 по 14 содержатся метаданные уровня в формате XML, описанные в главе Основы работы с уровнями. Единственная строка, на которую стоит обратить внимание, это:

10         <el:compatibility el:enigma="1.10"/>

Чтобы использовать API 2, так как это описано в данном руководстве, следует объявить, что уровень совместим с Enigma версии 1.10 или выше. Значение меньшее 1.10 означает совместимость с предыдущим выпуском Enigma, который использует старый API 1 и который не следует смешивать с новым API 2.

Код Lua начинается со строки 15:

16    wo["ConserveLevel"] = true

Как и большинство уровней, этот уровень начинается установкой глобальных атрибутов (см. раздел Глобальные атрибуты). Представление нашего мира — это ‘wo’. Это предварительно заданная объектная ссылка (см. раздел Мир как объект). С точки зрения Lua, это ‘пользовательские данные’, но большая часть синтаксиса их использования, идентична синтаксису списков Lua. Так, например, мы можем получить доступ к атрибуту, заключив имя нужного атрибута в квадратные скобки. Чтобы задать символьное имя атрибута, мы должны заключить его в двойные кавычки ‘"’. Смысл строки в указании миру воскрешать убитого актёра, пока хватает дополнительных жизней, чтобы текущий уровень всё ещё можно было пройти (см. раздел ConserveLevel). В сущности ‘true’ — это значение по умолчанию, поэтому мы могли бы опустить эту строку. Мы оставляем ее в целях полноты изложения.

Вторая часть уровня — это определение секций способом, описанным в разделе Очертания и координаты мира. Давайте начнём с самого простого:

18    ti[" "] = {"fl_samba"}
19    ti["."] = {"fl_abyss"}
20    ti["~"] = {"fl_water"}
21    ti["#"] = {"st_granite"}
22    ti["X"] = {"st_oxyd"}

Мы снова используем указатель, ‘ti’, который представляет собой объектную ссылку на хранилище определений секций. Подобно миру, это ‘пользовательские данные’ Lua, и мы можем обратиться к нему, задавая нужный индекс в квадратных скобках. Эти индексы можно выбрать на свой вкус. Если они используются далее в карте мира, то их длина должна быть одинаковой. Для маленьких уровней подойдут односимвольные коды. Разрешается использовать любые понятные Lua символы ASCII. То есть, символы ‘A-Z,a-z’ в верхнем и нижнем регистрах, цифры и специальные символы, исключая обратный слэш ‘\’ и двойные кавычки ‘"’.

Определение, присваиваемое объекту, представляет собой анонимные таблицы Lua — фигурные скобки, в простейшем случае содержащие лишь желаемый Тип объекта. Так как это опять строка символов, то её следует заключать в двойные кавычки. Если не указано иное, объекты берутся в их конфигурации по умолчанию, которая описана в разделе Покрытия и следующих разделах.

24    ti["L"] = {"st_laser", orientation=EAST, state=ON}
25    ti["M"] = {"st_lightpassenger", interval=0.04}

Эти две строки описывают объекты с конфигурацией, отличающейся от конфигурации по умолчанию. st_laser должен послать свой луч в восточном направлении и изначально должен быть включен. st_lightpassenger должен перемещаться немного быстрее, чем обычно. В обоих случаях мы должны просто добавить дополнительные атрибуты, разделённые запятой. Названия атрибутов не заключаются в кавычки, потому что за ними следует знак равенства ‘=’.

27    ti["P"] = {"st_polarswitch", name="polar"}
28    ti["T"] = {"it_trigger", target="polar"}

st_polarswitch переименован, чтобы на него было удобнее ссылаться (см. раздел Именование объектов). Для it_trigger настраивается Цель-действие, целью становится наша переключаемая преграда для лазера. Атрибут действия опущен. По умолчанию им становится сообщение ‘toggle’. Таким образом, любой актёр или камень, ставший на триггере, делает прозрачной переключаемую преграду для лазера, но, покидая триггер, снова делает её непрозрачной.

30    ti["^"] = {"st_boulder", "boulder", orientation=NORTH}
31    ti["F"] = {"st_fourswitch", target="boulder", action="orientate"}

Другая пара объектов объединена понятием Цель-действие. st_boulder изначально пытается двигаться на север. На этот раз мы даём объекту имя, просто передавая его в качестве второго из строковых параметров, разделяемых запятыми. Мы опустили идентификатор атрибута ‘name =’. Это упрощение для наиболее часто используемого атрибута, которое требует, чтобы сразу после типа объекта вторым параметром было указано имя.

st_fourswitch в качестве цели использует болдер. Так как мы хотим воспользоваться специальным действием, которое непосредственно управляет болдером в зависимости от направления четырёхстороннего переключателя, то нам также нужно указать действие.

33    ti["D"] = {"st_door_d", "door", faces="ew"}
34    ti["B"] = {"it_blocker", "wall#"}
35    ti["S"] = {"st_switch", target={"door", "wall#*"}}

И ещё одна Цель-действие, немного посложнее. Мы хотим с помощью единственного переключателя (st_switch) открывать/закрывать дверь (st_door) и, в то же время, изменять состояние it_blocker. Игровой момент здесь состоит в том, что ни при включенном, ни при выключенном переключателе шарик не может преодолеть оба препятствия. Чтобы преодолеть их, игроку нужно провести болдер сквозь блокирующую стену.

Настройка двери проста. Для того, чтобы в будущем к ней обращаться, нам нужно просто дать ей имя. Мы хотим использовать несколько блокирующих объектов и дать имя каждому, чтобы ссылаться на них. Мы делаем это, добавляя к его имени знак решётки ‘#’ так, как это описано в разделе Именование объектов. Каждому блокирующему объекту присваивается уникальное имя. Каждый из этих объектов должен быть перечислен в списке целей переключателя. Это сделано с использованием встроенного анонимного списка, формируемого фигурными скобками, в которых через запятую указываются значения. Первое — имя двери, второе — шаблон строки, описывающей все наши блокирующие объекты. Звёздочка представляет собой любой суффикс, который в процессе автоматического именования наших блокирующих объектов может быть добавлен после решётки.

37    ti["v"] = {"it_vortex", "left", destination="right"}
38    ti["V"] = {"it_vortex", "right", destination="left"}

Мы хотим использовать две воронки (it_vortex), которые связаны друг с другом, давая таким образом шарику возможность переноситься в обоих направлениях. Каждой воронке мы присваиваем уникальное имя и добавляем атрибут ‘destination’, который принимает значение имени другой воронки.

Заметим, что мы можем без проблем обратиться к правой воронке в строке 37, в то время как описана она будет только в строке 38. Мы пока только описываем секции, но ещё не создаём вообще никаких объектов.

40    ti["O"] = {"st_turnstile", flavor="red"}
41    ti["E"] = {"st_turnstilearm", orientation=EAST}
42    ti["N"] = ti["."] .. {"st_turnstilearm_n"}

Другая группа объектов — это блок из st_turnstile с одной отсоединённой рукояткой. Первые два определения предельно понятны. Но в строке 42 мы предваряем определение рукоятки ссылкой на другой объект. Это секция бездны, определённая в строке 19. Объединяя двумя точками (..) описание секции и объекта, мы можем определить новый объект, состоящий из обоих объектов. В данном случае мы определяем рукоятку турникета на покрытии бездны.

Возможно вам интересно, почему мы не определили покрытия для остальных секций камней и предметов. Мы используем определение покрытий в строке 18, которое мы позже объявим покрытием по умолчанию для нашего уровня. Таким образом, для любого определения секции, у которой нет своего покрытия, по умолчанию будет установлено это покрытие.

44    ti["+"] = {"fl_samba", checkerboard=0} .. ti({"fl_wood", checkerboard=1})

Просто для красоты мы хотим, чтобы на полу в правой части нашего уровня был шахматный узор. Это можно сделать, используя атрибут checkerboard. Мы снова объединяем определения двух объектов в одной секции. Оба они — покрытия. Это значит, что для каждой ячейки сетки мы пытаемся установить оба типа покрытия, но только одно удовлетворит условиям "шахматного узора" и будет использовано.

Пожалуйста, обратите внимание, что мы преобразовали одно из определений объекта покрытия в определение секции, вызвав функцию ‘ti()’. Это необходимо, потому что Lua не знает, как объединить два анонимных списка. Один из объединяемых параметров должен быть секцией.

46    ti["1"] = {"#ac_marble"}

Наконец, нам понадобится наш шарик. В отличие от остальных объектов он может располагаться в любом месте решётки. Самое распространённое место — это центр решётки. Для этого нам просто нужно предварить тип актёра знаком решётки ‘#’.

48    if wo["IsDifficult"] then
49        ti["="] = ti["~"]
50    else
51        ti["="] = ti["~"] .. {"it_strip_ew"}
52    end

Мы рекомендуем нашим создателям уровней предоставить для уровней упрощённый режим. В данном примере приводятся определения разных секций для разных режимов. Как и в строке 16, мы обращаемся к атрибуту мира. Но в этот раз это чтение атрибута IsDifficult. В упрощённом режиме мы хотим, чтобы на поверхности воды была полоска суши (it_strip), которая позволит шарику пересечь её и нажать на триггер. В сложном режиме прохода быть не должно. Таким образом, специальная секция идентична секции воды, определённой в строке 20.

54    w, h = wo(ti, " ", {
55        "####################",
56        "#      ....++++++~ #",
57        "L   PM ..N.++~~~~OE#",
58        "#######  T~++++++. #",
59        "#     ^   ~++++++# #",
60        "#         =++++++X X",
61        "#         ~++++++# #",
62        "#~~~~~~~~~~~~~+++X X",
63        "#    ~   B   ~+++###",
64        "F    ~   B   ~+++++#",
65        "# 1  ~   B   #+++++#",
66        "S   v~V  B   D+++++#",
67        "####################"
68    })

После того, как все секции будут заданы, мы можем создать наш мир, просто нанеся его на карту, используя наши коды секций. Первый аргумент — это наше представление ‘ti’, которое определяет, как следует преобразовывать коды. Второй аргумент — код нашего покрытия по умолчанию. Третий аргумент — карта в виде списка строк, по одной строке списка в каждой строке карты.

Создание мира возвращает ширину и высоту нашего мира, которые рассчитаны по размеру карты.

70    wo:shuffleOxyd()

После того, как мир создан и все объекты размещены, мы можем провести какую-нибудь постобработку перед началом уровня. Самой частой задачей является перемешивание оксидов, представляющее собой простой вызов метода shuffleOxyd для нашего громадного объекта мира.

5.1.2 Colored Turnstiles

Так как этот уровень входит в состав пакетов уровней Enigma, мы советуем сначала поиграть на нём, чтобы познакомиться с используемыми объектами и их поведением.

Теперь давайте взглянем на важную часть Lua исходного кода уровня, чтобы понять, как подобная идея может быть реализована с использованием нового API:

ti[" "] = {"fl_sahara"}
ti["#"] = {"st_purplegray"}
ti["@"] = {"#ac_marble_black", "marble_black"}

ti["N"] = {"st_turnstilearm_n"}
ti["S"] = {"st_turnstilearm_s"}
ti["E"] = {"st_turnstilearm_e"}
ti["W"] = {"st_turnstilearm_w"}
ti["R"] = {"st_turnstile", action = {"open", "close"}, target = {"red#*", "green#*"}}
ti["G"] = {"st_turnstile", action = {"close", "open"}, target = {"red#*", "green#*"},
                           flavor = "green"}
ti["r"] = {"it_blocker", "red#"} .. ti({"fl_red"})
ti["g"] = {"it_blocker", "green#"} .. ti({"fl_lawn"})

ti["O"] = {"st_oxyd", flavor = "d", oxydcolor = OXYD_GREEN}
ti["o"] = {"st_oxyd", flavor = "d", oxydcolor = OXYD_RED}

w, h = wo(ti, " ", {
 -- 01234567890123456789
   "#O#####O############",
   "#   r N g N rO##O#O#",
   "#WRE#WGE# R ####g#r#",
   "#   r N r S  r N   #",
   "#g#g#WG #g##r# REr##",
   "# # N S r    g S  gO",
   "#@g RE#g#gWGE###g###",
   "# # S   g    r N  ro",
   "#r#r#WGE#r##g#WGEg##",
   "# N r S g N  r     #",
   "#WGE# RE# RE####r#g#",
   "#   g S r S go##o#o#",
   "#o#####o############"
})

wo:shuffleOxyd()

Здесь всего четыре определения секций, которые отвечают за все динамические действия. Давайте сначала посмотрим на определения блокирующего предмета:

ti["r"] = {"it_blocker", "red#"} .. ti({"fl-red"})
ti["g"] = {"it_blocker", "green#"} .. ti({"fl-leaves"})

Все блокирующие предметы на красных покрытиях получают имена автоматически, объединением приставки ‘red#’ и уникального случайного номера, добавляемого движком так, как описано в разделе Именование объектов. Это даёт нам возможность позже обращаться ко всем этим блокирующим предметам.

ti["R"] = {"st_turnstile", action = {"open", "close"}, target = {"red#*", "green#*"}}
ti["G"] = {"st_turnstile", action = {"close", "open"}, target = {"red#*", "green#*"},
                           flavor = "green"}

Всякий раз, когда шарик проходит через турникет (st_turnstile), он (турникет) осуществляет действия над своими целями. В данном случае автор мудро использовал несколько целей и действий так, как описано в разделе Цель-действие. При каждом повороте красного турникета все объекты с именем вида ‘red#*’, то есть всем нашим блокирующим предметам на красном покрытии, будет отправлено сообщение ‘open’, тогда как все блокирующие камни на зелёном покрытии, вторая группа целей, получат второе сообщение действия ‘close’. Важно выбрать сообщения ‘open’ и ‘close’ вместо ‘toggle’, так как последовательно могут повернуться несколько красных турникетов, однако только первый поворот красного турникета должен "переключить" все блокирующие камни. Соответственно, следующее переключение должно произойти при первом повороте зелёного турникета.

Надеемся, основная идея нового API понятна. Теперь можно начать свои первые эксперименты с уровнями. Но чтобы создавать более интересные уровни, следует вернуться и прочесть следующие разделы с обзором и более сложными примерами.

5.2 Обзор API 2

После того, как мы проанализировали первый уровень, настало время рассмотреть возможности API 2. Сделаем это, перечислив различные возможности и их использование на примерах.

5.2.1 Обзор типов

Для начала мы должны рассказать о специальных типах значений Enigma, отличных от стандартных типов Lua ‘nil’, ‘boolean’, ‘string’, ‘function’ и ‘table’:

Типы:

position:  см. раздел Позиция

Позиция в мире, которую можно задать координатами x и y.

positions: стандартная переменная: po; см. раздел Хранилище позиций

Единый тип хранилища всех именованных позиций.

object:  см. раздел Объект

Объект Enigma, такой как камень, предмет, покрытие и т.п. Каждому объекту также соответствует позиция.

group:  см. раздел Группа

Список объектов.

namedobjects: стандартная переменная: no;   см. раздел NamedObjects

Единый тип хранилища всех именованных объектов.

default: стандартная переменная: DEFAULT;   см. раздел Атрибуты объектов

Единый тип значений по умолчанию, который может использоваться вместо типа Lua ‘nil’ в определениях анонимных списков секций.

tile:  см. раздел Описание секций и объектов

Описание для одной секции одного или нескольких объектов (покрытие, предмет, камень, актёр).

tiles: стандартная переменная: ti;   см. раздел Хранилище секций

Единый тип хранилища всех экземпляров секций.

world: стандартная переменная: wo;   см. раздел Мир

Единый тип мира, содержащий все объекты.

position list:  см. раздел Именованные позиции

Список позиций.

Пожалуйста, обратите внимание на четыре представления: ‘po’, ‘no’, ‘ti’ и ‘wo’. Два из них уже можно было заметить в предыдущем разделе Примеры простых уровней на языке Lua. Это четыре переменные, которые должны быть настроены перед тем, как будет выполнен код уровня.

Обычно, для часто используемых переменных и функций API 2 использует двухсимволные имена, чтобы сократить код уровня и сделать его более читаемым. Авторам рекомендуется использовать либо одиночные символы, либо имена из трёх и более символов для имён локальных переменных.

В оставшейся части этого раздела мы предполагаем, что ‘obj’ — это объектная ссылка на камень, предмет или покрытие; это значит, что его тип — ‘object’. И предположим, что ‘pos’ — допустимая переменная типа ‘position’.

5.2.2 Работа с позициями

Подробности можно узнать в разделе Позиция.

Создание позиций:

pos = po(7, 3) — использование функции "po()" для создания объекта позиции pos = po({7, 3}) — использование в качестве аргумента списка констант позиции pos = obj — каждый объект представляет собой допустимую позицию pos = po(12.3, 3.7) — позиция в сетке (для актёра)

Абсолютные позиции создаются функцией ‘po()’. Но самым распространённым способом должно быть представление объекта в качестве позиции. Это позволяет размещать новые объекты относительно заданных объектов.

Константы позиции:

{7,3} — позиция, допустимая для всех параметров и операций (см. Предупреждение)

Анонимные списки всего с двумя числовыми значениями во многих случаях могут использоваться непосредственно как константы позиции. В случае ошибок, например, когда операторы заданы не самым лучшим образом, вроде сложения двух констант, что приводит к попытке объединения двух списков Lua, для преобразования констант используют функцию ‘po()’.

Доступ к координатам:

x, y = pos.x, pos.y x, y = pos["x"], pos["y"] x, y = pos:xy() x, y = obj.x, obj.y x, y = obj:xy()

Координаты позиции или объекта (x и y), как и любой атрибут объекта, можно прочитать. Вызов метода позиции или объекта под названием ‘xy()’ возвращает значения сразу обеих координат. Изменить значение позиции, используя доступ на запись, нельзя. Объекты должны быть помещены на новую позицию в мире. Для задания новой позиции можно использовать арифметические операции.

Расчёт позиции:

pos = obj + {2,7} dpos = obj1 - obj2 dpos2 = 2 * dpos dpos3 = dpos / 2

Чтобы получить вектор расстояния, позиции можно складывать и вычитать. Их можно умножать и делить на любое число.

Центрирование позиции для размещения актёров

pos_centered1 = pos + {0.5, 0.5} pos_centered2 = #pos pos_centered3 = #obj

По большей части для размещения актёров, иногда необходимо знать позицию центра ячейки решётки. Конечно, её можно получить добавлением константы позиции. Однако то же самое можно сделать и проще, применив к позиции или актёру оператор ‘#’.

Округление позиции до границ ячейки

grid_pos = pos:grid() grid_pos = ((pos1 - pos2)/2):grid()

Иногда результат расчёта позиции необходимо округлить до целых координат решётки. Это делается методом ‘grid()’.

Сравнение позиций

pos_centered1 == pos_centered2 pos_centered1 ~= pos_centered2 — Оператор неравенства Lua

Позицию можно легко проверить на соответствие.

Существование позиций

pos:exists()

Возвращает ‘true’, если позиция находится в пределах мира. Все позиции за пределами мира возвращают ‘false’.

5.2.3 Работа с атрибутами

Подробности можно узнать в разделе Объект.

Установка одного атрибута:

obj["destination"] = po(7,3) wo["Brittleness"] = 7

Как и атрибуты мира, атрибуты объекта могут устанавливаться как список значений Lua. Они могут получать значения специальных типов Enigma, таких как позиция, объект или группа.

Установка нескольких атрибутов:

obj:set({target=mydoor, action="open"})

С помощью объектного метода ‘set()’ для любого объекта можно установить несколько атрибутов. Аргумент представляет собой анонимный список Lua с именами атрибутов в качестве ключевых полей и соответствующими выбранными вами значениями.

Запрос атрибутов:

value = obj["attr_name"] value = wo["Brittleness"] if wo["IsDifficult"] then ... end

Атрибуты объектов и мира можно прочесть в виде списка ключевых полей и значений Lua.

Сброс атрибутов:

obj["length"] = nil — длина по умолчанию, например ‘1’ obj["color"] = nil — удаляет атрибут цвета — убирает цвет obj["length"] = DEFAULT — длина по умолчанию, например ‘1’

Любой атрибут объекта может быть сброшен к своему значению по умолчанию, что представляет собой операцию "удаления" атрибутов, присвоением ему значения ‘nil’ из Lua или значения ‘DEFAULT’ из Enigma.

5.2.4 Работа с объектами

Подробности можно узнать в разделе Объект.

Создание объектов:

wo[pos] = {"st_chess", color=WHITE, name="Atrax"} — на секции решётки wo[#pos] = {"ac_bug"} — актёр, помещённый в центре секции решётки wo[pos] = {"#ac_bug"} — актёр, помещённый в центре секции решётки wo[pos] = {"ac_bug", 0.3, 0.7} — актёр, смещённый от границ секции решётки wo[my_floor] = {"it_magicwand"} — размещение на заданном объекте покрытия волшебной палочки wo[pos] = ti["x"] — определение объекта на основе секции

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

Именование объектов:

no["Atrax"] = obj wo[pos] = {"st_chess", name="Atrax"} wo[pos] = {"st_chess", "Atrax", color=WHITE}

Как сказано в разделе Именование объектов, имена — это единственные ссылки на объект, которые существуют длительное время. Чтобы назвать объект, как ключевое поле, можно явно дать объекту имя присвоив его в хранилище именованных объектов ‘no’. Но, в основном, просто давайте объектам имена через атрибут объекта. При передаче атрибута с именем через второе значение в анонимном списке атрибутов, чтобы немного сократить код, можно опустить ключевое поле ‘name =’.

Автоматическое именование объектов:

wo[pos] = {"st_chess", name="Atrax#"}

Как описано в разделе Именование объектов, к имени можно добавить знак решётки ‘#’ и использовать полученную строку для произвольного количества подобных объектов. Это особенно полезно при создании групп.

Обращение к объектам:

obj = no["Atrax"] — получение именованного объекта из хранилища obj = it(pos) obj = it(x,y) obj = st(pos) obj = wo:it(pos) my_item = it(my_floor) — получить предмет, который находится на заданном покрытии

Как правило, сначала объектам присваиваются имена, после чего к ним можно обратиться посредством ссылки на этот объект в хранилище ‘no’. Если известна позиция нужного объекта, то можно воспользоваться одной из функций или методов мира ‘fl’, ‘it’, ‘st’, которые принимают в качестве параметра позицию, объект, позицию которого можно использовать, или просто две координаты. Особенно полезным может быть запрос объектов одного типа, которые размещены в той же ячейке, что и другой объект (камень на поверхности и т.п.).

Уничтожение объектов:

wo[pos] = {"it_nil"} obj:kill()

Объект удаляется, размещением заменяющего его объекта на том же месте и в том же слое. Если нет нужды размещать новый объект, то можно использовать объекты "пустышки" ‘fl_nil’, ‘it_nil’, ‘st_nil’. Другой способ состоит в вызове метода объекта ‘kill()’ или отправке сообщения ‘kill’. Удалять можно только объекты, которые размещены на решётке. Ни актёры, ни связанные с ними объекты, как например предметы в инвентаре игрока, не могут быть уничтожены — они просто будут игнорировать подобную попытку.

Сравнение объектов

obj1 == obj2 obj1 ~= obj2

Объекты можно непосредственно проверять на эквивалентность. Это сравнение сущностей, которое может подтвердить, что две ваши ссылки ссылаются на один и тот же объект.

Существование объекта

obj:exists() -obj — унарный оператор отрицания перед объектом if -obj then ...

Ссылки на объекты могут стать недействительными после уничтожения объектов. Так как обращения к недоступным объектам просто будут игнорироваться, то в большинстве случаев это не проблема. Но если логика уровня зависит от существования объекта, можно вызвать метод ‘exists()’ или просто предварить ссылку унарным оператором отрицания ‘-’. Оба способа возвращают простое значение булевого типа, сообщающее, действительна ли ещё ссылка на объект.

Сообщения:

my_boulder:message("orientate", WEST) my_boulder:orientate(EAST) my_door:open()

Сообщения — основная возможность Enigma. Их можно отправить напрямую каждому объекту методом ‘message()’ или используя любое сообщение как сам вызов метода.

Классификация объектов:

obj:is("st_chess") obj:is("st") obj:is("st_chess_black")

Новые объекты создаются с помощью задания типа объекта (см. раздел Тип объекта). Позже заданный объект можно проверить на соответствие указанному классу или типу. Не смотря на то, что нельзя создавать объекты абстрактного типа, например ‘st’, таким образом можно проверить, является ли объект камнем. Проверка особых подтипов может даже определить текущее состояние или другие атрибуты объекта, чтобы сообщить о его текущей классификации.

5.2.5 Работа с группами

Подробности можно узнать в разделе Группа.

Создание групп:

group = no["Atrax#*"] — группа всех объектов с похожим названием — можно использовать маски "*","?" group = grp(obj1, obj2, obj3) group = grp({obj1, obj2, obj3}) — группа объектов собрана в список

При правильном использовании масок, запрос объектов из хранилища именованных объектов вернёт группу объектов. Добавление звёздочки ‘*’ к символу автоименования, решётке, вызовет все объекты, у которых в имени есть такой суффикс. Кроме того, группу можно создать и с помощью функции ‘grp’. Просто добавьте в качестве аргументов требуемые объектные ссылки, или по одной, или в виде списка.

Использование групп:

floor_group["friction"] = 3.2 — установить атрибут для всех покрытий в группе door_group:message("open") door_group:open() stone_group:kill() wo[floor_group] = {"it_coin_m"} — положить немного денег на все участки покрытия wo[pos] = {"st_switch", target=door_group, action="open"} wo[pos] = {"st_switch", target="door#*", action="close"}

Таким способом к группе можно применять многие операции над объектами. Операции будут применяться к каждому члену группы. Можно устанавливать атрибуты, посылать сообщения или вызывать любой метод.

Объект мира тоже получает группу в качестве ключевого поля. Объекты указанного вида можно разместить в нескольких местах одновременно.

Другое использование групп — их применение в качестве значений атрибутов. Например, используя группу, можно задать несколько целей.

Операции над группами:

doors_lasers = doorgrp + lasergrp — объединение двух групп lasergrp = doors_lasers - doorgrp — разность двух групп common_doors = doorgrp1 * doorgrp2 — пересечение двух групп

Группы предлагают несколько стандартных операций, знакомых по работе с наборами.

Члены группы:

count = #mygroup — количество объектов в группе obj = mygroup[5] — 5-й объект группы obj = mygroup[-1] — последний объект группы for i = 1, #mygroup do obj = mygroup[i] ... end for obj in mygroup do ... end

К членам группы можно обратиться по порядковым индексам. Размер группы сообщается стандартным оператором Lua, решёткой ‘#’. Если требуется последовательно перебирать все объекты группы, то можно просто написать циклы на Lua. Можно как использовать счётчик, так и напрямую перебирать содержимое объектов.

Перемешанная группа:

shuffled_group = sorted_group:shuffle() shuffled_group = no["Atrax#*"]:shuffle()

После получения сообщения "shuffle", любая группа вернёт перемешанную группу, состоящую из её элементов.

Отсортированная группа:

sorted_group = group:sort("linear", po(2, 1)) sorted_group = group:sort("linear") sorted_group = group:sort("circular") sorted_group = group:sort()

Линейно сортирует группу в порядке, заданном вектором направления или первыми двумя объектами, или же связывает каждый объект с центральным. Если аргумент не задан, то объекты сортируются лексически.

Отделение подгруппы:

sub_group = group:sub(2) — первые два объекта sub_group = group:sub(-2) — последние два объекта sub_group = group:sub(2, 4) — объекты со 2 по 4 sub_group = group:sub(2, -2) — два объекта, начиная со 2

По заданным индексам и числам формирует подгруппу.

Ближайший объект:

object = group:nearest(reference)

Ищет в группе объект, ближайший к указанному.

5.2.6 Работа с секциями и миром

Подробности можно узнать в разделах Описание секций и объектов, Хранилище секций и Мир.

Секции:

ti["_"] = {"fl_sahara"} ti["__"] = {"fl_sahara"} ti[".."] = {"fl_sand"} ti["##"] = {"st_blocker"} ti["switch_template"] = {"st_switch"} ti[".."] = {"fl_abyss"} — переопределение приводит к ошибке, чтобы исключить работу с неверными данными ti[".w"] = ti[".."] .. {"it_magicwand"} ti[" w"] = {"fl_abyss"} .. ti({"it_magicwand"})

Хранилище секций ‘ti’ напоминает список, но ориентированный на хранение определений секций. В качестве ключевого поля разрешается использовать любую строку. Одно и то же определение можно хранить в двух разных ключевых полях. Но уже заполненное ключевое поле переопределить нельзя. Это сделано исключительно с целью защиты от часто возникающих ошибочных ситуаций. Находящееся в хранилище определение может использоваться в последующих определениях. Обращение к записи в хранилище секций по заданному ключевому полю в виде ‘ti[".."]’ возвращает значение секции. Такие значения секций могут быть объединены оператором ‘..’ с другими значениями секций и анонимными списками, содержащими определения объектов. Последний пример — это объединение двух ранее не объявленных определений объектов. Нельзя объединить два анонимных списка. В Lua это запрещено. Объединение становится возможным после преобразования любого из двух списков в значение секции с помощью оператора ‘ti()’.

Заполнение мира:

width, height = wo(ti, "__", { — второй аргумент: ключевое поле секции (по умолчанию), которое "##__......", — также задаёт основу — в этом примере "##..__.w__", — для каждой секции/ячейки отводится 2 символа "##.. w__.." })

Мир заполняется вызовом ‘wo()’, который подробно рассматривается в разделе Создание мира. В простой форме в качестве первого аргумента передаётся ‘ti’. Второй аргумент — код определения секции по умолчанию, который задаёт покрытие по умолчанию, которое будет установлено, если в секции нет другого объекта покрытия. Кроме того, своим размером этот код задаёт стандартную длину кода, используемого в последующей карте. Третий аргумент — карта, задаваемая анонимными списками строк. Размер мира задаётся максимальной длиной передаваемых строк и их количеством. Эти значения возвращаются вызовом.

5.2.7 Работа с именованными позициями

Подробности можно узнать в разделе PositionList.

Использование именованных позиций:

obj["name"] = "anchor1" obj:kill() pos = po["anchor1"] po["anchor2"] = pos

Позиция любого именованного объекта может быть получено напрямую. После того, как объект уничтожен, его позиция всё ещё доступна по имени. Кроме того, можно самому давать позициям имена. Следует заметить, что у позиции существующего объекта больший приоритет, чем у простой позиции с тем же именем.

Создание списков позиций:

polist = po["deepwater#*"] polist = po(grp)

При правильном использовании шаблонов, на запрос позиций будет выдан список позиций. В список позиций можно преобразовать и указанную группу объектов.

Использование списка позиций:

wo[polist] = ti["x"] grp = fl(polist)

Список позиций можно использовать для установки секций или получения групп покрытий, предметов, камней.

Операции со списком позиций:

wo[polist .. po["beach#*"]] = {"it_banana"}

Два списка позиций можно объединить. Также к списку позиций можно добавлять отдельные позиции.

Элементы списка позиций:

for i = 1, #polist do wo[polist[i]] = {"it_cherry"} end

К отдельным элемента списка позиций можно обратиться по индексу. Обработать весь список можно с помощью простого цикла (for). Оператор "решётка" (‘#’) возвращает количество позиций в списке.

5.3 Примеры сложных уровней на языке Lua

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

5.3.1 Color Maze

Давайте посмотрим на часть исходного кода уровня, написанную на Lua. В первые две колонки мы добавили номера строк, чтобы на них можно было ссылаться в этом разделе. Эти номера строк не являются частью самого исходного кода!

01    wo["ConserveLevel"] = false
02    wo["FollowGrid"] = false
03    wo["FollowMethod"] = FOLLOW_SCROLL
04
05    ti[" "] = {"fl_fake_abyss"} .. ti({"st_lightglass"})
06
07    ti["!"] = {"fl_blueslab", "blue#", _color="blue"}
08    ti["@"] = {"fl_pinkbumps", "orange#", _color="orange"}
09    ti["#"] = {"fl_redslab", "red#", _color="red"}
10    ti["$"] = {"fl_lawn_b", "green#", _color="green"}
11
12    ti["b"] = ti["!"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
13    ti["B"] = ti["!"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
14    ti["o"] = ti["@"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
15    ti["O"] = ti["@"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
16    ti["r"] = ti["#"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
17    ti["R"] = ti["#"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
18    ti["g"] = ti["$"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
19    ti["G"] = ti["$"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
20
21    ti["d"] = {"it_document", text="text1"}
22    ti["5"] = ti["b"] .. ti["d"]
23    ti["6"] = ti["O"] .. ti["d"]
24    ti["7"] = ti["r"] .. ti["d"]
25    ti["8"] = ti["G"] .. ti["d"]
26
27    ti["x"] = {"it_sensor", invisible=true, target="gates"}
28    ti["*"] = ti["x"] .. {"#ac_marble_black", "me"}
29
30    ti["?"] = {"st_oxyd_a"}
31
32    wo(ti, " ", {
33    --      |         1    1   |2    2
34    --      |1   5    0    5   |0    5
35           "                           ",
36           " xO@OxR#RxO@OxB!BxR#RxB!Bx ", --01
37           " b   r   g   g   b   g   r ",
38           " !   #   $   $   !   $   # ",
39           " b   r   g   g   b   g   r ",
40           " xR#RxB!BxO@OxG$GxO@OxO@Ox ", --05
41           " g   g   r   g   g   b   b ",
42           " $   $   #   $   $   !   ! ",
43           " g   g   r   g   g   b   b ",
44           " xR#RxO@OxG$GxR#RxG$GxR#Rx ",
45           " g   b   b   o       b   r ", --10
46           " $   !   !   @       !   # ",
47           " g   b   5   o   ?   b   r ", --
48           " xO@OxO@6*8$Gx   xG$GxR#Rx ",
49           " r   b   7   b   ?   o   o ",
50           " #   !   #   !       @   @ ", --15
51           " r   b   r   b       o   o ",
52           " xG$GxB!BxR#RxO@OxR#RxG$Gx ",
53           " g   o   o   g   g   o   b ",
54           " $   @   @   $   $   @   ! ",
55           " g   o   o   g   g   o   b ", --20
56           " xB!BxO@OxR#RxR#RxO@OxB!Bx ",
57           " o   r   g   g   b   b   g ",
58           " @   #   $   $   !   !   $ ",
59           " o   r   g   g   b   b   g ", --
60           " xR#RxB!BxB!BxR#RxO@OxR#Rx ", --25
61           "                           "} --
62    --      |         1    1   |2    2
63    --      |1   5    0    5   |0    5
64    )
65
66    last = it(no["me"])   -- the last visited sensor
67    move = 0              -- the count of link moves
68    sequence = {}         -- the sequence of the 4 colors that the user did choose
69
70    function gates(value, sender)
71        if last ~= sender then
72            local middle = last + (sender - last)/2
73            local color = fl(middle)["_color"]
74            if color == nil then return end  -- someone cheated, avoid throwing an exception
75            st(no[color.."#*"]):close()
76            sequence[move%4] = color
77            if move >= 3 then
78                st(no[sequence[(move+1)%4].."#*"]):open()
79            end
80            move = move + 1
81            last = sender
82        end
83    end

Давайте сосредоточимся на новых аспектах, не обсуждавшихся ранее в разделе Примеры простых уровней на языке Lua.

01    wo["ConserveLevel"] = false
02    wo["FollowGrid"] = false
03    wo["FollowMethod"] = FOLLOW_SCROLL

Этот уровень должен запрещать пользователю воскрешать шарик в начальной позиции. В то же время пользователь должен видеть окружающую его местность как можно полнее. Поэтому нужно установить и режим прокрутки. Всё это делается установкой специальных глобальных атрибутов (см. раздел Глобальные атрибуты).

05    ti[" "] = {"fl_fake_abyss"} .. ti({"st_lightglass"})
32    wo(ti, " ", {

Недоступные места были заполнены прозрачным стеклом на чёрном покрытии, как указано в строке 5. Заполнение мира использует это определение секции в качестве секции по умолчанию. Если оно содержит определение покрытия, то всё в порядке. Дополнительные объекты, такие как стеклянные камни, при использовании по умолчанию никогда не будут размещены.

07    ti["!"] = {"fl_blueslab", "blue#", _color="blue"}
08    ti["@"] = {"fl_pinkbumps", "orange#", _color="orange"}
09    ti["#"] = {"fl_redslab", "red#", _color="red"}
10    ti["$"] = {"fl_lawn_b", "green#", _color="green"}

Каждому объекту покрытия присваивается автоматически сгенерированное имя, чтобы позже можно было обратиться к группе. К тому же каждый объект покрытия устанавливает пользовательский атрибут, добавляемый после его имени и предваряемый символом подчёркивания ‘_’. Этот атрибут хранит строку, которая позже понадобится нам в функции обратного вызова.

12    ti["b"] = ti["!"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
13    ti["B"] = ti["!"] .. {"st_door", flavor="d", faces="ew", state=OPEN}

Двери размещаются без присвоения им имён, потому что мы будем использовать их как цели, определяемые их позицией.

27    ti["x"] = {"it_sensor", invisible=true, target="gates"}

Шаги актёров обнаруживаются невидимыми it_sensorами, которые размещаются на каждом пересечении. Их целью является Функция обратного вызова ‘gates’. Можно опустить действие, так как имя функции представляет собой уникальную цель.

66    last = it(no["me"])   — последний пройденный датчик

Переменная Lua, в которой хранится последний пройденный шариком датчик. Изначально он указывает начальную позицию шарика. Мы обращаемся к шарику по имени, а под ним сохраняем предмет датчика, который представляет собой безымянный объект.

67    move = 0              — количество переходов через сенсоры
68    sequence = {}         — последовательность из 4 цветов, которую выбрал пользователь

Это важные переменные для нашего алгоритма. Пользователь волен выбирать любую последовательность разноцветных поверхностей. Изначально мы задаём для последовательности анонимный список, который будет заполнен названиями цветов. Дополнительный счётчик перемещений предоставляет нам текущий индекс в этом списке.

70    function gates(value, sender)
71        if last ~= sender then

Функция обратного вызова даёт нам возможность работать с отправителем, it_sensor, который вызывает действие. Это текущий датчик. Так как шарик может вернуться к последнему датчику, то перед тем как предпринимать какие-либо действия, мы должны убедиться, что это новый датчик. Достаточно простого сравнения объектов.

72            local middle = last + (sender - last)/2
73            local color = fl(middle)["_color"]

Нам нужно знать цвет полоски покрытия, по котороой прошёл шарик. Мы вычисляем позицию центра этой полоски покрытия, применяя расчёт позиции. Мы просто получаем среднюю позицию между предыдущим и текущим пересечением. Как только у нас появится средняя позиция, мы можем узнать объект покрытия и получить частный пользовательский атрибут с описанием цвета.

74            if color == nil then return end  — если кто-то жульничает, то не производим никаких действий

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

75            st(no[color.."#*"]):close()

Зная цвет, мы хотим закрыть все двери, расположенные на полосках покрытия того же цвета. Мы автоматически дали имена покрытиям, добавив соответствующие приставки к их именам. Таким образом мы можем получить все покрытия заданного цвета, объединив строку с названием цвета и суффикс ‘#*’ и обратившись к хранилищу именованных объектов. Так как нас интересуют двери, мы обращаемся к камням на каждом покрытии. Мы передаём группу покрытий и получаем группу камней. Не на каждом покрытии есть дверь. Это не имеет значения, потому что в результирующую группу камней добавляются только существующие объекты. Определив камни, мы просто посылаем всем им сообщение ‘close’.

76            sequence[move%4] = color

Нам нужно помнить последовательность цветов. Мы просто храним название цвета в списке под индексом, полученным по количеству шагов по модулю 4 (остаток от деления кол-ва шагов на 4 — прим. перев.). Мы, конечно, могли бы ограничить это выражение первыми четырьмя шагами. Но зачем? Операция взятия остатка проще, чем условные выражения.

77            if move >= 3 then
78                st(no[sequence[(move+1)%4].."#*"]):open()
79            end