Руководство по использованию WeiDU

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

Краткая информация о WeiDU

У WeiDU есть в Интернете домашняя страница:http://weidu.org/. Рекомендую вам загрузить оттуда самую свежую версию.

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

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

Вы можете смело использовать эту программу для разработки и распространения своих собственных модов на Infinity Engine. На WeiDU распространяется действие GNU (General Public License), но, в расширение ее, вы имеете право, если пожелаете, свободно включать в состав мода бинарный исполняемый файл WeiDU.EXE (в неизмененном виде и без исходного кода).

Я решил написать свои собственную утилиту для работы с DLG и TLK в Infinity Engine, потому что не смог добиться от TeamBG DLG Editor и Mass Converter правильной работы. Эти программы не анализируют строки или могут испортить текст или могут вдруг зависнуть ... где ни ткни, везде плохо. К тому же все они основаны на GUI (графическом интерфейсе). Будучи воспитанным на unix, я обожаю программы, работающие в командной строке, а как дипломированный PL-специалист (специалист по языкам программирования, - прим.перев.), я люблю разрабатывать всякие языки и компиляторы. WeiDU изначально состоял из нескольких маленьких программочек с ничего не говорящими названиями: DC, DD и TP. Более привлекательный термин "WeiDU" (который рифмуется с "IDU" - сокращение от interface data unit, интерфейсный блок данных, прим.перев. - и "Eye-Dee-You" - не очень понятное сочетание; наверное наиболее интересным является созвучность с "we do", мы делаем, - прим.перев.) придумали Джейсон Комптон (Jason Compton) и Грейфэйн (Ghreyfain) - выдающиеся авторы модов для BGII.

Без паники!

Пошаговое руководство к WeiDU для новичков: Без паники. Многие из вас - дети эры графических пользовательских интерфейсов (GUI). Но программы, которые работают в командной строке, тоже могут быть вашими друзьями, и, по большому счету, они работают гораздо быстрее, а использовать их, на самом деле, гораздо проще.

Наилучший способ научиться писать код в формате WeiDU - формате D - прочитать код, написанный в формате WeiDU - формате D. Начните с декомпиляции уже существующих игровых файлов DLG, которые вы хорошо знаете, и прочитайте полученные файлы. Сравните то, как они выглядят в WeiDU и то, как они выглядят в других редакторах, с которыми вы, возможно, лучше знакомы (например, Near Infinity и Infinity Explorer).

Наилучший способ научиться писать код в формате WeiDU - формате D - прочитать код, написанный в формате WeiDU - формате D, часть 2. Все больше аддонов к BG2 создаются при помощи WeiDU. Список можно найти здесь: http://www.pocketplane.net/modlist/. Они помогут вам понять, как использовать более сложные функции WeiDU, такие как добавление диалогов, работа со скриптами и 2DA-файлами, а также вещами (item), заклинаниями (spells) и существами (creature), которые используются непосредственно в игре. Поставьте себе такую задачу: скачать определенный мод и разобраться КАК ИМЕННО он работают.

Посмотрите некоторые примеры в этом документе. Есть замечательное руководство к WeiDU (написанное Japheth): http://forums.pocketplane.net/index.php?topic=55.0 (русский перевод здесь). Если чувствуете, настоящее руководство для вас слишком сложно, зайдите сначала туда. Там также объясняется как установить утилиту. Ghreyfain написал туториал "как создать NPC при помощи WeiDU" http://forums.pocketplane.net/index.php?topic=52.0 (русский перевод здесь )

Есть специальный форум для обсуждения WeiDU: http://forums.pocketplane.net/index.php?board=50.0. Для того, чтобы получить ответ на вопросы по использованию WeiDU (и по разработке модов тоже), этот форум - самое подходящее место.

Ну, и наконец, если Вы используете Mac и собираетесь пользоваться WeiDU, посетите http://weidu.org/Mac.html - там содержится информация по созданию копии WeiDU, работающей под OS X.

Концепция D и DLG-файлов

В этом разделе описано, как в принципе устроены DLG-файлы в Infinity Engine. Для начала, давайте воспользуемся WeiDU, чтобы создать SCSARLES.D, и посмотрим на диалог Сэра Сарльза (Sir Sarles).

WeiDU можно устанавливать где угодно, но мой вам совет - лучше разместите его в директории, куда установлена игра Baldur’s Gate 2. Впрочем, WeiDU использует реестр Windows чтобы обнаружить, куда установлена игра BG2.

Итак, чтобы сделать намеченное (создать SCSARLES.D, - прим.перев.), откройте режим командной строки DOS, перейдите в директорию (пользуясь командами DOS: буква с двоеточием - C: - для смены диска, и CD Program Files\Black Isle\BGII - SoA, как в примере, для перехода в нужную директорию, прим.перев.), куда установлена игра BGII, и затем, напечатайте нижеприведенный текст:

 C:\Program Files\Black Isle\BGII - SoA\>weidu SCSARLES.DLG

В текущей директории будет создан текстовый файл SCSARLES.D. Откройте его в Блокноте, или в Microsoft Word, или любым другим текстовым редактором. Вы увидите - это обычный текстовый файл, в котором определенным образом подробно расписан диалог игры.

Вы увидите примерно следующее (приведен пример начала файла диалога, выдаваемого версией 204, с дополнительными комментариями, не указанными в оригинальном руководстве- прим.перев.):

 // creator  : c:\bgate\WeiDU\weidu.exe
 // argument : SCSARLES.DLG
 // game     : C:\Program Files\Black Isle\BGII - SoA
 // source   : C:\Program Files\Black Isle\BGII - SoA\data\Dialog.bif
 // dialog   : C:\Program Files\Black Isle\BGII - SoA\DIALOG.TLK
 // dialogF  : (none)
 
 BEGIN ~SCSARLES~
 //////////////////////////////////////////////////
 // WARNING: this file contains non-trivial WEIGHTs (ВНИМАНИЕ: данный файл содержит нестандартные "веса", прим.перев.)
 //////////////////////////////////////////////////
 
 IF WEIGHT #1 /* Triggers after states #: 34 even though they appear after this state */
 ~NumTimesTalkedTo(0)
 ~ THEN BEGIN 0 // from:
   SAY #28655 /* ~Кто это? Могу я спросить, зачем вы прервали мои размышления? Муза моего творчества должна пробуждаться нежно, а ваше топанье просто ничего не даст.~ [SARLES02] */
   IF ~~ THEN REPLY #28656 /* ~Мои извинения. Я оставлю тебя твоим раздумьям.~ */ GOTO 1
   IF ~~ THEN REPLY #28657 /* ~Я прошу прощения, но мне нужен твой талант для выполнения важной работы.~ */ DO ~SetGlobal("TalkedToSarles","GLOBAL",1)
 ~ GOTO 2
 END
 
 IF ~~ THEN BEGIN 1 // from: 0.0
   SAY #28661 /* ~Тогда я забуду, что вы вообще здесь были. На самом деле это будет изумительно легко сделать.~ */
   IF ~~ THEN DO ~SetNumTimesTalkedTo(0)
 ~ EXIT
 END

Диалоги в играх на Infinity Engine работают, как конечные автоматы (finite state machine, FSM - термин, обозначающий вычислительную модель с определенным числом состояний, переход к которым осуществляется управляющими командами на основании внешних данных, - прим.перев.). Если вы не имеете ни малейшего представления о том, что такое конечные автоматы, загляните на http://whatis.techtarget.com/definition/0,,sid9_gci213052,00.html или на http://www.c3.lanl.gov/mega-math/workbk/machine/mabkgd.html. Каждый блок, имеющий вид:

 IF ~Изначальное условие~ THEN BEGIN шаг1
   SAY ~Что-нибудь~
   IF ~Условие для ответа~ THEN REPLY ~Текст ответа~ GOTO шаг2
 END

описывает один шаг (state) (более детально см. ниже). Когда игрок начитает общение с НПС (NPC), движок игры сканирует все шаги в DLG-файле этого NPC в порядке, определяемом их "весом" (WEIGHT), и выбирает один не являющийся пустым и проверка "Изначальное условие" которого выдает ПРАВДА (true). Если таких шагов не найдено, то игра выдает сообщение: "Нечего вам сказать" (в окне сообщений выдается имя НПС и строка #32092 ~ has nothing to say to you.~, - прим.перев.). Про порядок определения "весов" не думайте - это пока не нужно.

Итак, если шаг найден, говорящий (в данном случае, Сэр Сарльз) говорит то, что указано после SAY. В строках REPLAY приводятся возможные ответы игрока. Если проверка "Условие для ответа" выдает ПРАВДА, то игроку дается возможность сказать фразу "Текст ответа" и перейти к другому шагу диалога (где Сарльз, возможно, скажет что-нибудь еще).

Запомните: SAY - это то, что говорит НПС, а REPLAY - то, что ему отвечает игрок. Если обратить внимание, то легко заметить, что абсолютно все диалоги в играх на Infinity Engine построены таким образом.

В условиях используется тот же синтаксис, что и в триггерах скриптов BCS в Infinity Engine. Хорошо бы, конечно, вам изучить написание скриптов в Infinity Engine - это отдельная большая тема. Строки заключаются справа и слева в тильды (~), знаки процентов (%) или кавычки (") - на ваш выбор - по умолчанию же WeiDU использует тильды. После SAY, или REPLY, или JOURNAL можно, вместо одной, давать две строки (string): первая используется для DIALOG.TLK, а вторая - для DIALOGF.TLK (версия диалога, когда главный персонаж женского пола - для иностранных языков, в которых такое различие существенно). Если вы указываете только одну строку, то предполагается, что в обоих случаях текст будет одинаковым (если имеется DIALOGF.TLK, то в него всегда заносится текст - две строки указано или одна, - прим.перев.).

Можно также использовать цифры, перед которыми стоит знак "#" (например, #1234) - так указывается прямая ссылка на номер строки в DIALOG.TLK. Это удобно, когда изменяется уже имеющийся диалог (скажем, Духа судьбы в ТОБ), в этом случае, если диалог будет инсталлировать иностранный пользователь, то в тех строках, которые не изменялись, будет использоваться текст из его игры и их не надо будет переводить. Обычно ссылки на номера строк указываются сразу за SAY, а сам текст помещается в комментарии. Ключ командной строки --text, наоборот, позволяет в комментариях номера строк.

Сразу нужно сказать про звуковые файлы (WAV/WAVC) - они присоединяются к нужной строке в виде имени ресурса (не более 8 символов), заключенного в [квадратные скобки] после текста (не забудьте пробел после тильды, - прим.перев.), вот так:

 SAY ~Привет~ [HELLO]

Комментарии делаются аналогично принятому в C/C++: все, что идет после // и до конца строки - это комментарий, так же, как и все, что /* находится между слэшами со звездочкой */. Комментарии WeiDU игнорирует - они только для вашего удобства. Пример:

 SAY ~Привет~ [HELLO]   // это все идет комментарий        ... аж до сюда!
 IF /* здесь тоже комментарий */ ~~ THEN EXIT

Ответы (REPLAY) могут также содержать и действия (указание делается ключевым словом DO) - практически, точно такие же, как скриптовые действия (script actions BCS) в Infinity Engine. Кроме того, в ответах можно добавлять записи журнала (Journal entries), завершать диалог (EXIT) или даже переключаться на диалог другого НПС (EXTERN).

Примеры:

 IF ~~ THEN BEGIN 2 // from: 0.1 (комментарий формирует по умолчанию сам WeiDU, поэтому он оставлен непереведенным, - прим.перев.)

Вышеприведенная строка означает, что в диалоге начался шаг 2. Комментарий поясняет, что этот шаг может быть доступен после ответа-перехода 1 в шаге 0.

 IF ~~ THEN REPLY ~Мои извинения. Я оставлю тебя твоим раздумьям.~ // #28656
     GOTO 1

Данный ответ будет доступен всегда (поскольку условие не задано - ~~, - прим.перев.) и в окне сообщений будет выведена строка: "Мои извинения...". Номер строки, соответствующей этому тексту - 28656. Если персонаж игрока (PC - player character) выбирает данный ответ, происходит переход к шагу 1. (Пример несколько отличается от содержимого SCSARLES.DLG, полученного ранее, - текст строки указан частью программы диалога, а не в комментарии, - данный вид обычно имеют классические, жестко закодированные, диалоги модов, что и объясняет выбор примера, - прим.перев.)

Наконец, переход иметь такой вид:

 COPY_TRANS имя_файла ярлык

Во время исполнения диалога, COPY_TRANS будет заменен переходами, взятыми из шага "ярлык" файла имя_файла. Копирование происходит до начала выполнения других команд диалога (D-actions).

Формат D-файла диалога (D-формат)

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

Описание формата D-файлов представлено здесь с использованием расширенной контекстно-свободной грамматики (extended context-free grammar notation). Если термин CFG ни о чем вам не говорит, загляните на http://www.wikipedia.com/wiki/Context-free_grammar, http://cs.wpi.edu/~kal/PLT/PLT2.1.2.html или http://www.cs.rochester.edu/users/faculty/nelson/courses/csc_173/grammars/cfg.html. Впрочем, досконально разбираться в CFG не обязательно.

Чтобы разобраться, как это все работает, с помощью WeiDU создайте для себя JAHEIRA.D и смотрите его в текстовом редакторе. Не лишним будет просмотр и тестирование примеров, которые прилагаются к WeiDU (в папке examples, - прим.перев.).

Все ключевые слова синтаксиса даны в ВЕРХНЕМ РЕГИСТРЕ. Остальные ключевые слова символические (призваны интуитивно подсказывать, чем их в реальности заменять, - прим.перев.). Запомните, что:

• "list" после выражения означает "0 или более штук этого выражения";
• "[выражение в квадратных скобках]" означает "не обязательное выражение" или "0 или 1 выражение";
• многоточие (...) после выражения означает "можно повторить выражение столько раз, сколько захочется".
• под термином "выражение" подразумевается ключевое слово, то есть часть команды, отделенная о других знаками пробела, - прим.перев.

D-файл		D-файл - это текстовый файл, который содержит определенный набор D-действий (D Action). D-файлы указывают WeiDU, каким образом создавать и изменять DLG-файлы, используемые движком Infinity Engine.
это	D-действие list	D-файл - это список D-действий. В принципе, только одна - BEGIN - указывает на создание нового диалога. Остальные D-действия используются для изменения существующих диалогов.
D-действие		D-действия указывают WeiDU, каким образом создавать и изменять DLG-файлы, используемые движком Infinity Engine.
это	BEGIN имя_файла [ nonPausing ] шаг list	BEGIN указывает WeiDU, что вы собираетесь создать с помощью программы новый DLG-файл. DLG-файл с аналогичным именем будет заменен создаваемым. Новый файл будет содержать только те шаги, которые вы укажете. Если зададите переменной nonPausing значение, отличное от нуля, то во время диалога время останавливаться не будет. По умолчанию же во время диалога игра встает на паузу.
или	APPEND [ IF_FILE_EXISTS ] имя_файла шаг list END	Данная команда указывает WeiDU добавить указанные шаги в конец уже существующего файла имя_файла.DLG. Если указан параметр IF_FILE_EXISTS, а файла в игре не существует, то действие не выполняется.

Специальные ключи для использользования в командной строке (Command Line Options)

Компилирование и декомпилирование (Compiling And Decompiling)
FILE.D	Компилировать FILE в DLG-файл (dialogue file - файл диалога, используемый движком игры, прим.перев.).
FILE.DLG	Декомпилировать файл FILE в D-файл (dialogue text file - файл диалога в текстовом виде, прим.перев.).
число	При декомпилировании DLG-файла в D-файл вывести только шаг с определенным номером. Вы можете использовать это несколько раз и будут выведены только те шаги диалога, которые вы указали.
числоA-числоB	При декомпилировании DLG-файла в D-файл вывести только шаги с номерами, начиная с числаА и заканчивая числомB (включительно). Вы можете использовать это несколько раз и будут выведены только те шаги диалога, которые вы указали.
FILE.BAF	Компилировать файл FILE в BCS-файл (script file - файл скрипта в бинарном виде, используемый в игре, прим.перев.).
FILE.BCS	Декомпилировать файл FILE в BAF-файл (script text file - файл скрипта в текстовом виде, прим.перев.).
--script-style X	Использовать для BAF/BCS указанный тип скриптов. Допустимые значения X: BG, BG2, PST, IWD, IWD1 или IWD2.
--transin X	Использовать файл FILE в качестве источника текстовых строк при работе с D и BAF-файлами.
FILE.TRA	Равнозначно --transin FILE.TRA

Команды, не указанные в разделе "Command Line Options" документации WeiDU

Ключи для перевода (Translation Options)
--traify-comment	добавляет в D-файл содержимое строк, на которые даны ссылки, в виде комментариев, используется с командой --traify

Примеры использования

Декомпилирование из DLG-файлов в D-файлы

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu bodhi.dlg --log log.txt

(ключ --log log.txt добавлен здесь и далее в командах для возможности сохранения протокола работы команды в файле log.txt и возможности его просмотра после завершения работы WeiDU, - прим.перев.)

Результат (см. файл log.txt - прим.перев.):

 [C:\Program Files\Black Isle\BGII - SoA\chitin.key] 182 BIFFs, 41793 resources
 [C:\Program Files\Black Isle\BGII - SoA\DIALOG.TLK] 84458 string entries
 [C:\Program Files\Black Isle\BGII - SoA\data\Dialog.bif] 2729 file entries
 [BODHI.DLG] loaded
 [.\BODHI.D] created from [BODHI.DLG]

Данная команда загружает файл BODHI.DLG (первый обнаруженный - прим.перев.), производя поиск по стандартному пути (то есть в текущей директории, папке override и, наконец, в BIFF-файлах игры) и создает из него файл BODHI.D (поскольку не задан ключ --out, файл будет помещен в текущую директорию, - прим.перев.).

Декомпилирование DLG-файлов в удобный для перевода формат

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu bodhi.dlg --trans --log log.txt

Результат (см.файл log.txt - прим.перев.):

       ...
 [.\BODHI.TRA] created as translation file
 [.\BODHI.D] created from [BODHI.DLG]

Данная команда, так же как и предыдущая, создает файл BODHI.D, но также создает еще и файл перевода - BODHI.TRA (этот файл, TRA-файл, представляет собой перечень всех текстовых строк из BODHI.D, что удобно для перевода и проверки ошибок) (WeiDU игнорирует совпадающие строки, в том числе и при создании TRA-файлов - повторения строк не будут выведены, даже если D-файл ссылается на разные строки DIALOG.TLK с одинаковым содержанием, - прим.перев.). В файле BODHI.D будут сделаны специальные ссылки на строки из файла BODHI.TRA.

Это довольно удобно, особенно при конвертировании в формат WeiDU модификаций, созданных ранее с помощью других утилит, например IDU. Одновременно создается и D-файл для WeiDU и TRA-файл, содержащий все необходимые ссылки, и к тому же, удобный для перевода.

Некоторые опции при декомпилировании DLG-файлов

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --nofrom bodhi.dlg --out foozle.d --text --log log.txt

Результат (см.файл log.txt - прим.перев.):

       ...
 [.\foozle.d] created from [BODHI.DLG]

Данная команда создает файл foozle.d (а не BODHI.D, как в предыдущем примере), но не указывает в нем комментарии "// from:" (такие комментарии WeiDU создает по умолчанию - они указывают на взаимосвязь веток диалога - прим.перев.). Текстовые строки в команде SAY (и всех других тоже, - прим.перев.) также не заменяются. То есть будет создано:

SAY ~Hello~ /* #1 */ 

вместо

SAY #1 /* ~Hello~ */

Декомпилирование нескольких DLG-файлов

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu bodhi.dlg jaheira.dlg --out test --log log.txt

Результат (см.файл log.txt - прим.перев.):

       ...
 [test\JAHEIRA.D] created from [JAHEIRA.DLG]
 [test\BODHI.D] created from [BODHI.DLG]

Данная команда загружает из игры (согласно стандартному пути поиска, - прим.перев.) файлы BODHI.DLG и JAHEIRA.DLG и создает из них файлы BODHI.D and JAHEIRA.D соответственно. Дополнительный аргумент --out test указывает WeiDU записать получившиеся файлы в директорию test.

Компилирование D-файла

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu bodhi.d --log log.txt

Результат (см.log.txt - прим.перев.):

       ...
 [bodhi.d] parsed
 [BODHI.DLG] saved       135 states, 259 trans, 16 strig, 66 ttrig, 54 actions

Эта команда загружает bodhi.d, анализирует его, а затем исполняет все указанные в нем инструкции. В результате из вашего bodhi.d будет создан BODHI.DLG (далее речь идет о ссылках на номера строк в DIALOG.TLK, следовательно, имеется в виду тот bodhi.d, который был создан командой из предыдущего примера - без ключа --trans, - прим.перев.). Если в bodhi.d содержатся строки, которые отсутствуют в DIALOG.TLK, то DLG-файл будет создан с неправильными ссылками на строки.

Компилирование D-файла, в котором имеется новый текст

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu bodhi.d --tlkout new-DIALOG.TLK --log log.txt

Результат (см.log.txt - прим.перев.):

       ...
 [bodhi.d] parsed
 [BODHI.DLG] saved       135 states, 259 trans, 16 strig, 66 ttrig, 54 actions
 [new-DIALOG.TLK] created, 84459 string entries

Данная команда загружает bodhi.d, анализирует его, а затем исполняет все указанные в нем инструкции. В результате из вашего bodhi.d будет создан BODHI.DLG. Если в bodhi.d содержатся какие либо строки, отсутствующие в DIALOG.TLK, то будет создана его новая версия, new-DIALOG.TLK, в которую они будут добавлены.

Компилирование нескольких D-файлов

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu ppworker.d bodhi.d --out test --log log.txt

Результат (см.log.txt - прим.перев.):

       ...
 [bodhi.d] parsed
 [ppworker.d] parsed
 [BODHI.DLG] saved       135 states, 259 trans, 16 strig, 66 ttrig, 54 actions
 [PPWORKER.DLG] saved    33 states, 81 trans, 4 strig, 12 ttrig, 10 actions

Эта команда создает в директории test файлы BODHI.DLG и PPWORKER.DLG на основании инструкций, указанных в файлах bodhi.d и ppworker.d соответственно. Если в этих файлах имеется новый текст, используйте команду --tlkout для создания нового DIALOG.TLK.

Компилирование D-файла с получением нескольких DLG-файлов

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

 C:\Program Files\Black Isle\BGII - SoA\> weidu examples/sola/solae1.d --log log.txt

или

 C:\Program Files\Black Isle\BGII - SoA\> weidu examples\sola\solae1.d --log log.txt

Результат (см.log.txt - прим.перев.):

       ...
 [examples/sola/solae1.d] parsed
 [SOLA.DLG] loaded
 [SOLA.DLG] saved        336 states, 401 trans, 64 strig, 18 ttrig, 125 actions
 [SOLAE1.DLG] saved      36 states, 49 trans, 1 strig, 11 ttrig, 1 actions
 [SOLAE2.DLG] saved      3 states, 3 trans, 0 strig, 0 ttrig, 0 actions
 [SOLAE3.DLG] saved      2 states, 2 trans, 0 strig, 0 ttrig, 0 actions
 [SOLAE4.DLG] saved      3 states, 3 trans, 1 strig, 0 ttrig, 0 actions
 [SOLAE5.DLG] saved      2 states, 2 trans, 0 strig, 0 ttrig, 0 actions
 [SOLAE6.DLG] saved      4 states, 5 trans, 0 strig, 2 ttrig, 0 actions
 

Происходит следующее: solae1.d добавляет (с помощью команды APPEND, - прим.перев.) текст в файл SOLA.DLG и создает файлы SOLAE1.DLG, SOLAE1.DLG, SOLAE3.DLG, ..., SOLAE6.DLG. Вы можете сразу положить их все в директорию override командой --out override. Для разделения директорий можно пользоваться и косой чертой (/) и обратной (\) (прямой и обратный слэш, - прим.перев.). Если известно, что в этих файлах имеется новый текст, используйте команду --tlkout для создания нового DIALOG.TLK.

Компилирование D-файла, который использует TRA-файл

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

 C:\Program Files\Black Isle\BGII - SoA\> weidu examples/sola/solafoe.d --transin examples/sola/solafoe.tra --log log.txt

или

 C:\Program Files\Black Isle\BGII - SoA\> weidu examples/sola/solafoe.d examples/sola/solafoe.tra --log log.txt

Результат (см.log.txt - прим.перев.):

       ...
 [examples/sola/solafoe.tra] parsed (15 translation strings)
 [examples/sola/solafoe.d] parsed
 [SOLA.DLG] loaded
 [SOLA.DLG] saved        336 states, 401 trans, 65 strig, 18 ttrig, 124 actions
 [SOLAFOE.DLG] saved     11 states, 14 trans, 1 strig, 2 ttrig, 1 actions

Происходит следующее: solafoe.d использует 15 строк из файла перевода (TRA-файла), дописывает командой APPEND кусок к SOLA.DLG, а также создает SOLAFOE.DLG. Чтобы указать TRA-файл, можете использовать ключ --transin (как в первом примере команды, - прим.перев.) или просто укажите его в командной строке (если он, как и положено, имеет расширение TRA, как во втором примере команды, - прим.перев.). Если вы указываете несколько TRA-файлов, то для подстановки берется первая найденная строка с нужным номером, причем поиск начинается с последнего указанного файла - достаточно или нет строк в TRA-файлах не имеет значения. Если добавляется текст, используйте ключ --tlkout.

Отображение строковых ссылок

(String References, строковые ссылки или просто строки - это нумерованные ссылки на строки в файле DIALOG.TLK, - прим.перев.) Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --string 123 --strfind understudy --strfind acid.*rows

(результат будет возможно увидеть только на экране - ключ --out здесь не работает, - прим.перев.)

       ...
 [C:\Program Files\Black Isle\BGII - SoA\chitin.key] 182 BIFFs, 41793 resources
 [C:\Program Files\Black Isle\BGII - SoA\DIALOG.TLK] 84458 string entries
 String #123 is ~Haer' Dalis, all of you, stop them!~
 String #6763 is ~Acid Arrows~
 String #11662 is ~Biff The Understudy~
       ...

На экране будет отражена строка #123, все строки, содержащие слово "understudy", а также все строки содержимое соответствующие регулярному выражению "acid.*rows". Обратите внимание, что регистр букв не имеет значения.

Изменение DIALOG.TLK вручную

Пример команды: C:\Program Files\Black Isle\BGII - SoA\> weidu --strapp ANewString --tlkout happy.tlk --log log.txt

Результат (см.log.txt - прим.перев.):

 [C:\Program Files\Black Isle\BGII - SoA\DIALOG.TLK] 84458 string entries
 [.\happy.tlk] created, 84459 string entries

Комментарий простой: в файле happy.tlk теперь есть строка #84459 с текстом “ANewString”.

Получение списка содержимого BIFF-файла

Пример команды: C:\Program Files\Black Isle\BGII - SoA\> weidu --biff data/dialog.bif --out res.txt (ключ --out res.txt добавлен здесь и далее в командах для возможности сохранения результата работы команды в файле res.txt и возможности его просмотра после завершения работы WeiDU, - прим.перев.)

Результат обработки (см.файл res.txt, - прим.перев.):

       ...
 [data\Dialog.bif] contains    ABELA.DLG at index 0
 [data\Dialog.bif] contains    ACHEN.DLG at index 1
       ...

Это список всех ресурсов (то есть, ACHEN.DLG - это "ресурс"), которые запакованы в файле data/Dialog.bif.

Извлечение содержимого BIFF-файлов с помощью регулярных выражений (Regular Expressions, regxp)

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --biff-get sper.*itm --log log.txt

Результат обработки (см.файл log.txt, - прим.перев.)

 [.\chitin.key] loaded, 590551 bytes
 [.\chitin.key] 182 BIFFs, 41793 resources
 [.\DIALOG.TLK] loaded, 10154904 bytes
 [.\DIALOG.TLK] 77666 string entries
 [.\data\Items.bif] loaded, 659688 bytes
 [.\data\Items.bif] 1990 file entries
 [.\SPER01.ITM] 266 bytes, created from [.\data\Items.bif]
 [.\SPER02.ITM] 314 bytes, created from [.\data\Items.bif]
 [.\SPER03.ITM] 362 bytes, created from [.\data\Items.bif]
 [.\SPER04.ITM] 322 bytes, created from [.\data\Items.bif]
 [.\SPER05.ITM] 266 bytes, created from [.\data\Items.bif]
 [.\SPER06.ITM] 266 bytes, created from [.\data\Items.bif]
 [.\SPER07.ITM] 554 bytes, created from [.\data\Items.bif]
 [.\SPER08.ITM] 314 bytes, created from [.\data\Items.bif]
 [.\SPER09.ITM] 314 bytes, created from [.\data\Items.bif]
 [.\SPER10.ITM] 362 bytes, created from [.\data\Items.bif]
 [.\data\25Items.bif] loaded, 222370 bytes
 [.\data\25Items.bif] 479 file entries
 [.\SPER11.ITM] 314 bytes, created from [.\data\25Items.bif]
 [.\SPER12.ITM] 1610 bytes, created from [.\data\25Items.bif]
 [.\SPERMEL.ITM] 890 bytes, created from [.\data\25Items.bif]
 

При выполнении данной команды производился поиск в игре всех вещей (items, файлов с расширением .itm - прим.перев.), в названии которых используется "spear" и предполагалось, что игра установлена в ту же директорию, из которой запускалась команда. Обратите внимание, что ключ --biff-get использует регулярные выражения (regexp), но не групповые символы, которые используются в DOS. Также обратите внимание, что --biff-get не производит поиск в директории override (обычно, там не должно быть BIFF-файлов, - прим.перев.). И наконец, если вы используете Mac (или работаете под unix), можете без сомнений заключать регулярное выражение в кавычки, вот так:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --biff-get "sper.*itm"

это предусмотрено.

Поиск внутри BIFF-файлов

Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --biff-type CRE --biff-str SPWI911 --out res.txt

Результат обработки (см.файл res.txt, - прим.перев.)

       ...
 LICH01.CRE in [data\Creature.bif] matches
 HLKANG.CRE in [data\Creature.bif] matches
       ...

Данная команда находит все CRE-файлы, в которых содержится "SPWI911", что соответствует поиску всех оппонентов-магов, которые могут воспользоваться заклинанием "Шторм метеоров" (которое, как раз и называется "SPWI911"). Можете попробовать также вот такую команду:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --biff-type BCS --biff-str Terminsel --out res.txt

Результат обработки (см.файл res.txt, - прим.перев.)

       ...
 AR0300.BCS in [data\Scripts.bif] matches
 AR0308.BCS in [data\Scripts.bif] matches
 JAHEIRA.BCS in [data\Scripts.bif] matches
       ...

чтобы найти в игре все скрипты, использующие переменную с именем, включающим "Terminsel" (на самом деле, производится обычный поиск в тексте скриптов, просто, кроме переменных, данное поисковое слово нигде встретиться не может - прим.перев.). Как вы, возможно, и ожидали, Джахейра была найдена. Обратите внимание, что такие поиски требуют определенного времени (например, на поиск всех скриптов уходит около 20 секунд).

Отображение перекрестных диалогов в одном с помощью --transitive

(Banter - перешучивание, - прим.перев.) Пример команды:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --nocom --text --transitive banomen.dlg

Флаг --transitive указывает WeiDU при формировании D-файле следовать по ссылкам EXTERN. Таким образом файл BANOMEN.D, получившийся в результате выполнения команды, будет содержать примерно следующее:

 IF WEIGHT #31 ~InParty("Edwin")
 See("Edwin")
 Gender("Edwin",FEMALE)
 !StateCheck("Edwin",STATE_SLEEPING)
 Global("BAnomen1","LOCALS",0)~ THEN BEGIN 10
   SAY ~Hey, Edwina!  I shall be your champion at the next tournament that
   we come to if only you give me a piece of your robe, uh, that is, dress
   to adorn my shield.~ [ANOMEN49] 
   IF ~~ THEN DO ~SetGlobal("BAnomen1","LOCALS",1)~ EXTERN ~BEDWIN~ 104
 END
 
 IF ~~ THEN BEGIN BEDWIN 104
   SAY ~(My condition draws fools like flies to honey).  Silence, you idiot!
   You've a death wish that is larger than your swollen head.~ [EDWINW39]
   IF ~~ THEN GOTO 11
 END
 
 IF ~~ THEN BEGIN 11
   SAY ~Fair Edwina, I am truly bereft by your non-acceptance.  It is tragic
   when a knight has no fair maiden to moon over.  Heh he he...~
   IF ~~ THEN EXIT
 END

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

Один нюанс: из-за команды --transitive WeiDU может легко впасть в бесконечный цикл. Ничего не поделаешь, прошу извинить.

Инструкции по использованию WeiDU

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

7.9 Преобразование "жестко закодированного" D-файла в пару D/TRA (последнее обновление: v200)

Материал любезно предоставил Джейсон Комптон (Jason Compton).

D и TP2-файлы позволяют указывать текст либо прямо в программе (такой способ называется "жестко закодированный" - прим.перев.):

 // Greeting.d
 SAY ~Привет.~

либо с помощью дополнительного TRA-файла (от translation - перевод, прим.перев.), что позволяет, кроме прочего, использовать несколько языков:

 // Greeting.d
 SAY @1

 // Greeting.tra
 @1 = ~Привет.~

Суть в том, что для перевода, например, на французский, достаточно сделать Greeting.tra на французском:

 // French-Greeting.tra
 @1 = ~Bonjour.~

Однако, те пользователи WeiDU, которые для удобства или им просто не приходила в голову идея о переводе, и они использовали "жестко закодированные" диалоги, а теперь изменили свое решение, могут воспользоваться командой --traify, которая преобразует весь текст в командах SAY, REPLY и записи JOURNAL в формат, удобный для перевода (трафицированный формат - прим.перев.) Команда --traify также может быть использована для TP2-файлов.

Чтобы преобразовать "жестко-закодированный" D-файл FWKI.d в комбинацию из новых файлов D и TRA(трафицировать - прим.перев.), указать исходные и конечные имена файлов соответственно можно командами --traify и --out:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --traify fwki.d --out fwki-new.d

Через несколько секунд будут созданы файлы fwki-new.d и fwki-new.tra.

После выполнения команды --traify исходный код в файле fwki.d:

 APPEND J#KLSYJ
   IF ~~ THEN BEGIN KelseySAHPR4
     SAY ~Urk. Who was the lucky donor?~
     IF ~~ THEN EXTERN SAHPR2 10
   END
 END 

в файле fwki-new.d выглядит так:

 APPEND J#KLSYJ
   IF ~~ THEN BEGIN KelseySAHPR4
     SAY @0
     IF ~~ THEN EXTERN SAHPR2 10
   END
 END 

а во вновь созданном fwki-new.tra, будет соответственно:

 @0    = ~Urk. Who was the lucky donor?~

и теперь это диалог готов для перевода.

--traify выполняется для всего D-файла от начала до конца и нумерует строки, начиная с @0. Никакие уже имеющиеся строки НЕ пропускаются, даже если они и будут найдены под каким-либо номером (@x), поэтому, если ваш D-файл уже был частично трафицирован, то лучше дополнительно использовать ключ --traify-old-tra.

Поскольку, по умолчанию --traify начинает нумерацию с @0 и игнорирует любые имеющиеся в D-файле ссылки на строки типа @x, если Вы уже пытались трафицировать диалог вручную, скорее всего, Ваши ссылки @x будут конфликтовать с результатами команды --traify.

Другими словами, если у вас уже есть трафицированный кусок

 IF ~~ THEN BEGIN blah
   SAY @0
   IF ~~ THEN EXIT
 END

--traify не пропустит ссылку @0 и у Вас будет две ссылки с одинаковым номером @0, хотя вы намеревались использовать две различные строки, и это, как Вы понимаете, плохо.

Чтобы избежать такой проблемы, добавьте ключ (аргумент) --traify-old-tra, чтобы указать, что файл уже частично трафицирован:

 C:\Program Files\Black Isle\BGII - SoA\> weidu --traify fwki.d --traify-old-tra fwki.tra --out fwki-new

будут сохранены имеющиеся ссылки на номера строк и добавлены новые - на строки из нового файла fwki-new.tra.

Наконец, учтите, что --traify работает также и с BAF-файлами.

Замечание: Можно было бы посоветовать воспользоваться в этом случае ключом --traify#. Но, если вы не хотите, чтобы нумерация строк начиналась с какого-то определенного номера, используйте ключ --traify-old-tra.

Во всех случаях, возможно, Вы найдете полезным использование в командной строке также ключа --traify-comment, поскольку это позволит добавить в D-файл содержимое строк, на которые даны ссылки, но уже в виде комментариев (чтобы легче было редактировать его в будущем):

 C:\Program Files\Black Isle\BGII - SoA\> weidu --traify fwki.d --traify-old-tra fwki.tra --out fwki-new --traify-comment

Один нюанс: используя вместе ключи --traify-comment и --traify-old-tra, можно добавить в комментарии D-файла отсутствующие расшифровки строк. (Смысл фразы оригинала уточнен практической проверкой - отсутствующие комментарии, действительно, появляются в D-файле, так же, как отсутствующие строки-расшифровки в TRA-файле, прим.перев.)

(Прим.перев.: во всех практических примерах в оригинале вместо --traify-old-tra использовалось отсутствующее в списке ключей командной строки --traify-tra, очевидно, ошибочно - исправлено.)

7.11 ALTER_TRANS (последнее обновление: v204)

Настоящее руководство любезно предоставил CamDawg.

ALTER_TRANS - это более удобный способ чтобы вносить изменения в переходы существующих диалогов. Лучше всего показать на примере; возьмем шаг (state) 9 из doghma.dlg игры BG2:

 IF ~~ THEN BEGIN 9 SAY #45751
   IF ~~ THEN REPLY #45752 GOTO 2
   IF ~GlobalLT("chapter","GLOBAL",4)~ THEN REPLY #45753 GOTO 5
   IF ~~ THEN REPLY #45754 GOTO 4
   IF ~Global("RevealUmar","GLOBAL",1)
       PartyHasItem("miscbl")
       PartyHasItem("miscbm")
       PartyHasItem("miscbn")
       PartyHasItem("miscbo")~ THEN REPLY #57922 GOTO 10
  IF ~~ THEN REPLY #45755 GOTO 1
 END

Здесь проблема в переходе (transition) 3 (нумерация начинается с 0, - прим.перев.): в начале проверки должно быть указано OR(4), а уже за потом проверки PartyHasItem. Без ALTER_TRANS, наименее неудобным способом составленное исправление выглядело бы так:

 ADD_TRANS_TRIGGER DOGHMA 9 ~False()~ DO 3
 EXTEND_BOTTOM DOGHMA 9
 IF ~Global("RevealUmar","GLOBAL",1)
 OR(4)
 PartyHasItem("miscbl")
 PartyHasItem("miscbm")
 PartyHasItem("miscbn")
 PartyHasItem("miscbo")~ THEN REPLY #57922 GOTO 10
 END

Из этого сразу вытекает несколько условий совместимости. Во-первых, если другой мод уже изменял этот переход (например, было добавлено новое действие с помощью ADD_TRANS_ACTION), то изменения будут потеряны. Также изменится порядок вывода на экран ответов - это не имеет большого значения для переходов, связанных с ответами, а вот для переходов без ответов - имеет - там где они идут в определенной последовательности. Кроме того, другие моды, использующие данный переход, потеряют эту возможность, так как False() фактически отключает его. Теперь используем ALTER_TRANS:

 ALTER_TRANS DOGHMA // имя файла
 BEGIN 9 END // номер шага (может быть несколько)
 BEGIN 3 END // номер перехода (может быть несколько)
 BEGIN // перечень изменений, описание флагов см.ниже
   "TRIGGER" ~Global("RevealUmar","GLOBAL",1)
            OR(4)
              PartyHasItem("miscbl")
              PartyHasItem("miscbm")
              PartyHasItem("miscbn")
              PartyHasItem("miscbo")~
 END

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

• TRIGGER: Условие триггера, используемого для перехода, пример: "TRIGGER" ~Global("foo","GLOBAL",0)~
• ACTION: Действие, выполняемое, если выбран данный переход, пример: "ACTION" ~SetGlobal("foo","GLOBAL",1)~
• REPLY: Ответ игрока, если он требуется, пример (в оригинале была ошибка - исправлено, обратите внимание на знак @ а не #, - прим.перев.): "REPLY" ~#57922~
• JOURNAL: Можно добавить или изменить запись журнала, пример (в оригинале была ошибка - исправлено, - прим.перев.): "JOURNAL" ~@100~
• SOLVED_JOURNAL: То же, что и JOURNAL, только для записей, указываемых в разделе "сделано".
• UNSOLVED_JOURNAL: То же, что и JOURNAL, только для записей, указываемых в разделе "не сделано".
• EPILOGUE: Указывает заключительное действие перехода (GOTO, EXTERN, или EXIT), пример: EPILOGUE" ~EXTERN BVICONI 0~
• FLAGS: Используется для того, чтобы вручную устанавливать флаги в переходе, хотя я не представляю себе, для чего это нужно.

Давайте посмотрим последний пример. Это bviconi.dlg, шаг 103:

 IF WEIGHT #22 ~Global("LoveTalk","LOCALS",46)~ THEN BEGIN 103 SAY #10537
   IF ~~ THEN REPLY #10538 GOTO 367
   IF ~~ THEN REPLY #10539 EXTERN ~~ 0
 END

Как видите, во втором переходе указание на заключительное действие содержит ошибку (в EXTERN не указан диалог, - прим.перев.). Раньше это пришлось бы исправлять таким образом:

 ADD_TRANS_TRIGGER BVICONI 103 ~False()~ DO 1
 EXTEND_BOTTOM BVICONI 103
 IF ~~ THEN REPLY #10539 GOTO 368
 END

Теперь, используя ALTER_TRANS, это сделать значительно проще:

 ALTER_TRANS BVICONI BEGIN 103 END BEGIN 1 END BEGIN "EPILOGUE" ~GOTO 368~ END

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

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

Компоновка мода: TP2-файлы (Module Packaging: TP2 Files)

TP2-файл		A TP2 File is a text file that contains a number of mod Components. TP2 Files tell WeiDU how to install various parts of your mod on an end-user’s computer.
это	BACKUP directoryName AUTHOR emailAddress TP2 Flag list Language list Component list	A TP2 File is basically a prologue and then a list of Components. The BACKUP declaration tells WeiDU where to put backed-up versions of files that would be overwritten so that they can be uninstalled later. This directory will be created automatically if it is missing. The AUTHOR directive gives an email address for users to send bugs to if there are problems during the installation. The TP2_AUTHOR variable is set to the “emailAddress” value. The TP2_FILE_NAME variable is set to the name of the tp2 file. TP2 Flags set global options. Languages are the various languages in which your mod is available. The Finally, the Components make up the actual meat of your mod. Different Components can be installed or uninstalled separately, but all of the parts within a Component are treated as a unit.
TP2-флаг		A TP2 Flag declaration tells WeiDU to apply some global option to your TP2 file.
это	AUTO_TRA путь	Флаг AUTO_TRA испоьзуется вместе с инструкцией COMPILE TP2. Он указывает автоматически загрузить TRA-файлы, соответствующие D-файлам (соответствие подразумевает совпадение имен до расширения; TRA-файлы загружаются из указанного пути, в котором может использоваться переменная %s, которую WeiDU заменяет на указанную пользователем директорию языка, - прим.перев.).

11 Распространение WeiDU с модулями (модами) в виде: Setup-MyMod.exe

Если переименовать WeiDU.EXE так, чтобы получилось нечто похожее на Setup-MyMod.exe, то запуск этой программы будет соответствовать запуску WeiDU.EXE с такими аргументами командной строки:

• --tlkout DIALOG.TLK
• --ftlkout DIALOGF.TLK (если имеется DIALOGF.TLK)
• --log MyMod.DEBUG
• Setup-MyMod.tp2
• MyMod.tp2

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

11.2 Значения, которые возвращает WeiDU

Завершение работы WeiDU.exe (или Setup-MyMod.exe) заканчивается установкой величины, называемой "возвращаемое значение" (или “код завершения”, или “код состояния”, или “уровень ошибки”), которая зависит от успеха или неудачи определенных операций. В зависимости от Вашей операционной системы, можно использовать эту величину в программных скриптах или исполняемых фалах, которые запускают WeiDU. По общему правилу, WeiDU возвращает 0 в случае успеха. Значение, отличное от 0 означает сбой. Вот список возвращаемых значений:

• 0. Общий успех. Ошибок, указанных ниже, не отмечено.
• 1. Установить компонент TP2 невозможно. В результате ошибки установки выводится одна из следующих строк: “Stopping installation because of error” (Установка прекращена из-за ошибки), “ERROR Installing [Component], rolling back to previous state” (Ошибка при установке указанного компонента, возврат к предыдущему состоянию), “PLEASE email the file SETUP-MYMOD.DEBUG to AUTHOR” (Пожалуйста, отправьте файл SETUP-MYMOD.DEBUG разработчику), “ERROR Re-Installing [MyMod] component 1” (Переустановка компонента такого-то мода [MyMod] вызвала ОШИБКУ).
• 2. Ошибка авто-обновления.
• 3. Повторная попытка авто-обновления. WeiDU.exe успешно обновлен, нужно запустить WeiDU.exe еще раз.
• 4. Неверный ключ командной строки.