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

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

2 Без паники!

Пошаговое руководство к 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.

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

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

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

Декомпилирование из 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.

Извлечение содержимого 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

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

Результат обработки (см.файл 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 секунд).

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

(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". Обратите внимение, что регистр букв не имеет значения.

Отображение перекрестных диалогов в одном с помощью --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 может легко впасть в бесконечный цикл. Ничего не поделаешь, прошу извинить.

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, очевидно, ошибочно - исправлено.)

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. Неверный ключ коммандной строки.