Skip to content

Home

Jump to bottom
Argent77 edited this page Nov 4, 2023 · 15 revisions
WeiDU Install Tool: A graphical front end for WeiDU Mods

  1. Overview
  2. Installation
  3. Features
  4. Building from Source
  5. Credits
Main Window and Details

Overview

Weidu Install Tool is a graphical front end for the WeiDU command line tool to install modifications for Infinity Engine games, such as Baldur's Gate, Icewind Dale or Planescape Torment.

The tool offers all the functionality of the WeiDU command line interpreter as well as many usability improvements and convenience features to help with the mod installation task. It is meant as a replacement or alternative to the setup executables that are included in most mod archives, but can also be used for more general WeiDU operations. It is not intended to be a full-fledged mod manager like Project Infinity.

The front end is written in Java and uses the JavaFX framework to provide a modern UI look and feel. The source code is licensed under the Apache License, Version 2.0.

Installation

Installation builds are available as installers and portable packages for Windows, GNU/Linux and macOS. They can be downloaded from the Releases section of the project.

It is recommended to download the installer version for Windows, the PKG archive for macOS, or the distribution-specific package types for Linux (deb, rpm) for the best integration of the application into the system. A Flatpak package for Linux is planned for later.

Note: On macOS the app has to be approved by the Gatekeeper before it can be used. Since the app is neither digitally signed nor distributed over the App Store it has to be unlocked manually. There are several websites available which describe how to install and open apps from uncertified sources.

Note 2: It is possible that some antivirus or security tools are overly sensitive and block download or installation of the file because of problematic executables. These are false positives if you downloaded the file from the official GitHub Releases page. Most antivirus tools provide options to whitelist the problematic files or mark them as safe and allow you to continue with the process.

Features

The main focus of the application lies on a guided procedure for installing mods. For that reason it provides several helpful options to find out more about the mod or assist with the installation itself.

The guided mode kicks in if the application is started with the path to the mod's tp2 file as the first parameter, which is always the case when the application is started by opening an associated tp2 mod file. If no arguments are specified then a file dialog allows you to choose a tp2 mod file manually.

To enforce use of the non-guided mode for unattended installations or advanced WeiDU operations you can pass an empty option (--) as the first argument to the application executable or start with a different argument.

Tp2 Mod File Association

If the application is installed by the Windows installer or through a package manager like apt, rpm or flatpak then the application is automatically associated* with tp2 mod files. Opening a mod file with the .tp2 extension in the file manager will automatically start mod installation or uninstallation with the Weidu Install Tool. The game will be automatically determined, otherwise it can be manually chosen.

* This feature is not supported on macOS.

Drag and Drop Support

With this feature it is possible to drag tp2 mod files or the mod folders themselves onto an open application to initiate a mod installation process. The application must have completed a previous mod installation before a new installation can be started.

Quick Input

On the right side of the main window you can find a number of commonly used commands that can be sent to the WeiDU process, such as I for installing a mod component, or Q for quitting the mod installation. These buttons can be used as an alternate option to the keyboard for sending input to the mod installation process.

Character Encoding Selection

Charset Selection

Mods allow customized output in different languages. However, in the past existed many different ways to encode text characters into data that the WeiDU process could understand.

A right-click on the output text area opens a context menu with the option to select different character encodings. They are grouped by geographic regions to quickly determine potential encodings for the selected mod language. By default the text is encoded in UTF-8 which should be the best choice for English and many Western European languages.

Mod Details

Details button

A Details window allows you to get a detailed overview of available mod components. Filter options can be used to switch between mod languages or display only mod components of a specific components group.

To help with different text encodings of component names it is possible to choose other character encodings through a context menu that can be opened by right-clicking on the components tree. This is mostly helpful for languages with special umlaut or accent characters as well as for languages with non-latin alphabets if the application could not determine the right character encoding automatically.

The bottom area of the Details window is reserved to provide general information about the mod itself, which includes the mod name, mod authors, links to readme and project websites as well as a short description of the mod. This information is only available if the mod provides Project Infinity mod information.

Customization

The application allows you to adjust many aspects of the application behavior and visualization. Many options can be set in the main window itself. A few advanced options for diagnostic or troubleshooting purposes can also be defined in the application's configuration file.

Tool Options

The Options menu provides the following entries:

  • Quit on Enter
    • If this option is enabled then pressing the Enter key will automatically close the application if a mod installation has finished. It is enabled by default, except on Linux.
  • Visualize State of WeiDU Operation
    • If this option is enabled then a color-coded frame is shown around the output text area when a mod installation has finished. Green color indicates a successfull operation. Orange inidcates that warnings appeared during the installation process. A red frame signals that the operation could not be completed. This option is enabled by default.
  • Warn about Mod Order Conflicts
    • Enable this option to trigger warning dialogs if a mod is expected to be installed before other mods that have already been installed for the game. This information is provided by the mod's own Project Infinity data and may not always be accurate. It is always possible to continue mod installations despite the warning. This option is enabled by default.
  • Dark User Interface
    • This option can be used to toggle between a light and a dark UI of the application on the fly. It is applied to all windows of the application. This option is disabled by default.
  • Run Application in Single Instance Mode
    • If this option is enabled then only one instance of the application will be open at the same time. Starting a new mod installation by double-clicking on an associated tp2 mod file will reuse the current instance of the application if available. This option reduces loading times considerably since opening new application instances are more resource-demanding than starting a mod installation in the terminal.
      On Windows this option will also enable a system tray icon that allows you to hide the main window when a mod installation is completed. A click on the tray icon will restore the application window. The application itself can be terminated by a right-click on the tray icon to open a context menu, and selecting the "Quit" option. This option is enabled by default, except on macOS.
  • Show Status in Tray Icon
    • If this option is enabled then the system tray icon will be differently colored while a mod installation is running. This option is only available on Windows if "Single Instance Mode" is enabled. It is disabled by default.
  • Show Log Window
    • This option shows or hides a log window with diagnostic messages about the mod installation. The log messages can be filtered by severity, such as error, warning or info levels. It is mostly useful for troubleshooting purposes.
  • Use Separate Folder for Mod Debug Files
    • This option can be used to specify a subfolder relative to the game directory where debug files of mod installations are created. By default debug files are created in the game directory.
  • Adjust output text font size
    • This option allows you to adjust the font size of the mod installation output.
  • Adjust Output Buffer Size
    • This option defines the size of the internal output text buffer, in number of characters. The application preserves the total output of the mod installation process, so that it can be reconstructed if the user chooses a different character encoding or for other reasons. The option exists mostly for performance reasons, since a large buffer size can reduce the general performance of the mod operation.

The WeiDU Options submenu provides options that can be applied to WeiDU calls when installing mods:

  • Performance: Suppress component names in WeiDU.log
    • Applies the WeiDU parameter --quick-log to guided mod installations if enabled. This parameter instructs WeiDU not to fetch and print descriptive mod component names to the WeiDU.log which will speed up mod installations.
  • Performance: Update WeiDU.log After Each Mod Component Installation
    • Applies the WeiDU parameter --safe-exit to guided mod installations if enabled. This parameter instructs WeiDU to update WeiDU.log after starting the installation of every mod component.
  • Diagnostic: Print OCaml Stack Trace
    • Applies the WeiDU parameter --print-backtrace to guided mod installations if enabled. This parameter prints the OCaml stack trace to the output when reporting an exception. It is rarely of interest to end-users.
  • Diagnostic: Print OCaml Debugging Information
    • Applies the WeiDU parameter --debug-ocaml to guided mod installations if enabled. This parameter enables random debugging information for the Ocaml source. It is rarely of interest to end-users.
  • Diagnostic: Print Files Changed by BUT_ONLY_IF_IT_CHANGES
    • Applies the WeiDU parameter --debug-boiic to guided mod installations if enabled. This parameter prints out which files have been changed by BUT_ONLY_IF_IT_CHANGES.
  • Diagnostic: Print Warning When Unmodified COPY_EXISTING is Performed
    • Applies the WeiDU parameter --debug-change to guided mod installations if enabled. This parameter prints a warning if a file is being COPY_EXISTED without receiving a change.
  • Apply Custom WeiDU Options
    • This option allows you to specify custom parameters to be applied to guided mod installations. Caution: Custom parameters are applied to the WeiDU call without additional safety checks.

In addition to the selectable options the application will provide an up to date WeiDU command line tool that is required to perform the actual mod installations. It will use an existing WeiDU executable if detected on the system. Otherwise, the latest version can be downloaded or chosen manually on the system.

Advanced Customization

A small number of options can only be defined in the configuration file of the application.

The location of the configuration file is system-specific and can be found in the following places:

  • Windows:
    • %LOCALAPPDATA%\wit\wit.ini (which points to C:\Users\<username>\AppData\Local\wit\wit.ini in a standard Windows installation)
  • Linux:
    • $XDG_DATA_HOME/wit/wit.ini (which points to /home/<username>/.local/share/wit/wit.ini by default)
  • macOS:
    • /Users/<username>/Library/Application Support/wit/wit.ini
    • Note: The Library folder is hidden by default in the Finder and must be manually enabled in the "View Options".

The following options are currently available:

  • UI Language Override
    • This option expects a two-letter language code that is used to display text and messages in the application. It overrides the language that is otherwise autodetected from the regional settings of the system. It will default to English if the specified language is not available.
    • Example: UI Language Override = de forces text and messages to be displayed in the German language.

Building from Source

Required tools:

Note: JDK 21 is automatically provided if an older Java installation is found on the system.

The following commands will build the application and create packages in the format native to the current platform.

Windows (installer):

cd WeiduInstallTool
gradlew.bat jpackage

Windows (portable zip):

cd WeiduInstallTool
gradlew.bat portableZip

Linux and macOS (installer):

cd WeiduInstallTool
chmod +x gradlew
./gradlew jpackage

Linux and macOS (portable tarball):

cd WeiduInstallTool
chmod +x gradlew
./gradlew portableTar

The resulting package(s) can be found in the ./build/distribution folder. File type associations are only configured by the installer version of the application.

The jpackage task requires the following software to be installed on the system:

  • Windows: WiX 3.0 or later is required.
  • macOS: Xcode command line tools are required when the --mac-sign option is used to request that the package be signed.
  • Linux:
    • For Red Hat Linux, the rpm-build package is required.
    • For Ubuntu Linux, the fakeroot package is required.

More details can be found in Oracle's Packaging Tool User's Guide.

Credits

Weidu Install Tool © 2023 by Argent77.

Translations

English: Argent77

German: Argent77 (Proofreading: Shai Hulud)

French: JohnBob

Brazilian Portuguese: Felipe

Russian: abalabokhin

WeiDU Install Tool - A graphical front end for WeiDU mods
Project | Download | Discussion on G3 Forums

Clone this wiki locally