FTL: Multiverse Wiki Tools

This project contains files, mods, and scripts for FTL: Multiverse used to make editing the FTL: Multiverse Wiki easier. It is written with Python.

Features

FTL: Multiverse scripts and mods adding Wiki information to the blueprints of most objects found on Player ships.
A script exporting ship information so it can be easily copy-pasted to the Wiki.
A script comparing old/new versions of FTL: Multiverse to determine which object blueprints were added, removed, or changed.
A JSON file mapping the blueprint "name" attributes from Vanilla FTL: Faster Than Light to those found in FTL: Multiverse. It is limited to the items found in blueprints.xml and dlcBlueprints.xml files.

Requirements

The game FTL: Faster Than Light
The mod FTL: Multiverse 5.0+ and everything it requires.
SlipstreamModManager
Python version 3.9.2 or later. If Python is not installed on your system, download it.
The FTL: Multiverse mod files to be in SlipstreamModManager's /mods/ folder.
Load order: In SlipstreamModManager, all the mods should be patched AFTER FTL: Multiverse.

Introduction

View Explanation

In FTL: Faster Than Light, game data is contained in XML files. Each in-game object has a blueprint: an XML element detailing the object and dictating its behavior.

FTL: Multiverse follows the same schema. However, it introduces more than 500 objects compared to the original game. This can make updating the FTL: Multiverse Wiki between FTL: Multiverse updates time-consuming when done manually.

A script to extract game information from object blueprints could help in editing the Wiki. However, most object blueprints do not contain enough information to determine what page on the FTL: Multiverse Wiki they belong to. This means that extracted information for objects would not include hyperlinks to their page on the Wiki. Hyperlinks would have to be added manually. Additionally, details from an object's blueprint, like its in-game name, do not always match its heading or how it is referred to on the Wiki.

This project includes a two-step solution. The first step matches object blueprints to their Wiki page and provides additional information where necessary. The second step adds elements containing Wiki information to existing blueprints. This enables a script extracting game information to refer to objects correctly and include hyperlinks to their Wiki page.

Show Two-Step Solution Details

Step 1: Add blueprintLists to Game Files

The first step involves a .append file in the folder Append Wiki blueprintsLists, autoBlueprints.xml.append. It is an XML file that uses blueprintLists to associate in-game objects with their corresponding Wiki page. It also contains information for objects where the blueprint information doesn't match the Wiki.

See the autoBlueprints.xml.append file file for more information.

Before the next step, the .append file is added to the game's existing files using SlipstreamModManager.

Step 2: Append Information to blueprints

A script called appendWikiElements.py generates .append files adding Wiki information to existing blueprints. It uses the added information from the last step to override blueprint information where necessary.

The generated .append files are added to the game files with SlipstreamModManager. With that, each blueprint referred to by Player Ships is given elements detailing their location on the Wiki.

Show Details for Other Scripts

Exporting Ship Data

After following the two-step solution, a script called wikiShipExport.py can be used to extract information about Player Ships from the game files and format it for the Wiki. The resulting file is inserted into a file called wikiShips.txt.

Instructions

Before using the mod, ensure all Requirements have been met and that the Disclaimer has been read.

There are two ways to use the script adding information to the game files. The first way is automatically, which is recommended. The second way is manually.

Disclaimer

The scripts use mods whose effect on game data while running FTL: Multiverse is untested. Your game data could become corrupted and unusable. It is recommended to backup game data before using the mods and scripts. Game data is commonly found in the folder Documents/My Games/FasterThanLight. Copy all files in that folder to another folder to backup the game data.

Automatic Method

Show Automatic Method

Windows:

The name of the FTL: Multiverse files to be patched should be specified in wikiToolsInit.py by editing the field multiverseFiles. They are included by default, but editing this field may be required between updates.
Double-click wikiTools.bat in File Explorer to run the script. By default, it includes a command to extract ship information. To disable that, delete the line python wikiToolsCLI.py --wikiShipExport.
Note that the batch file may stall if you click and drag the terminal window while it is executing. Pressing the ENTER key with the window selected fixes this.

Mac/Linux

Follow the instruction from Running in terminal, deviating from Windows-specific instructions where necessary.

Enter the following into terminal, one after the other:

python wikiToolsCLI.py --init

python wikiToolsCLI.py --wikiInfo

python wikiToolsCLI.py --wikiShips

Script Details

wikiToolsCLI.py accepts command-line arguments to executes files based on user input.
wikiToolsInit.py finds the location of SlipstreamModManager's modman.jar on your system. It requires modman.jar and the project to be on the same hard drive. Additionally, there must be only one copy of modman.jar on the current drive.

Manual Method

Show Manual Method

Step 1: Add blueprintLists

Go to SlipstreamModManager Process, with {modName} as Append Wiki blueprintLists.

Step 2: Add Information

After following Step 1. There are multiple options:

Run from Terminal (easier for beginners)
Run from IDE (better option for editing and development)

Running from Terminal Step 2

Complete the Running from Terminal instructions to open the terminal and navigate to the correct directory.
Enter in terminal python ./appendWikiElements.py. This activates the script appendWikiElements.py to create the .append files in the Append wikiElements folder.
Go to SlipstreamModManager Process, with {modName} being Append wikiElements.

Step 3: Export Ships

If the terminal was closed, or the directory changed, repeat the Running from Terminal instructions.
Enter in terminal python ./wikiShipExport.py. This activates the script wikiShipExport.py, which outputs text to a file called wikiShips.txt.

SlipstreamModManager Process:

Make sure that ZIP files are recognized by SlipstreamModManager. To enable this, in SlipstreamModManager, click in this sequence: File -> Preferences. In the popup, ensure the allow_zip option is checked.

{modName} is a generic name used for the name of the mod's ZIP file.

ZIP the 'data' folder in the {modName} folder.
Move the ZIP file to SlipstreamModManager/mods/. After you've done this once for a specific ZIP file, in the future, you can change the ZIP target path to SlipstreamModManager/mods/ and overwrite the existing ZIP file instead of moving it from the local directory.
In SlipstreamModManager folder, double-click modman.jar to start SlipstreamModManager.
In the list of mods, check the {modName} file.
Click 'Validate' to ensure the {modName} file contains valid XML. Ignore warnings about the invalid character '🗲'. For other warning messages, fix it using the information provided by SlipstreamModManager.
'Patch' FTL with the relevant FTL: Multiverse mod files and the ZIP file checked. Ensure the ZIP file is listed AFTER FTL: Multiverse. Otherwise, the patch will not work.
If you receive a popup asking to start FTL, DO NOT do it. See Disclaimer for details. The popup after patching can be disabled by following the sequence in SlipstreamModManager: File -> Preferences and ensuring that 'never_run_ftl' is checked.
Do File-> Extract Dats... and select the FTL DAT folder. It is important that the FTL DAT folder is selected because the scripts rely on the game data being in the same directory.
Click Save in the Extract Dats... popup. Wait for the files to be extracted.

If coming from Step 1, go to Step 2.

If coming from Step 2, go to Step 3.

Running from Terminal

(Guide for Windows)

In the Windows search bar, type "terminal". The app "Command Prompt" should appear. Click it to open the Command Prompt.
In File Explorer, locate and copy the file path of the project folder, referred to as projectFilePath.
In the terminal, enter cd {projectFilePath}. This changes the working directory of the terminal to where the scripts are.
If coming from the Manual Method, also enter cd project.

Terminal Input Example

Development Tools

Linux Compatibility

This is a general issue report for the problems I've found running these tools on a linux system according to the instructions in the readme:

Line 25 of wikiToolsInit.py: drive = pathlib.Path.home().drive returns a blank string on a linux system as it does not recognise unix file structure.
Fix: Somewhat of a band-aid fix, but I simply added this conditional to replace the drive with the home directory. It assumes that all files are located under the home directory, which is usually true:

drive  = pathlib.Path.home().drive
if len(drive) == 0:
    drive = pathlib.Path.home()

At various points '//' is appended to path strings. This ends up causing issues when using os.path.join, resulting in a path that looks like this: "/this/is/a/\path" on Linux. On Windows this becomes "this\is\a\path", which I assume works fine. Simply remove these ending slashes.
The fix for the above issue results in several places where paths are simply added together breaking completely. This isn't great anyway, so replace these instances with os.path.join(), i.e:
modmanCfgPath = f'{config[mainPaths][slipstream]}{modmanCfg}'
becomes
modmanCfgPath = os.path.join(f'{config[mainPaths][slipstream]}', modmanCfg)

This is just the first command - python wikiToolsCLI.py --init. Running the second results in every stage giving an invalid syntax java error, and I don't quite understand what these java commands are doing - the first one seems to be trying to execute java -jar modman.jar --validate Append Wiki blueprintLists.zip. I'm not sure if the last part (Append Wiki blueprintLists.zip) is intentional or if that actually works as java command syntax. Haven't tried to run the third.

withaspirit / ftl-mv-wiki-tools Goto Github PK

ftl-mv-wiki-tools's Introduction