(R/M2)TW Unit Browser RDK

[Tyblitz]

(R/M2)TW Unit Browser RDK (DL. links coming soon)

Description

TW Unit Browser Resource Development Kit is a command-line utility that enables anyone to build an interactive RTW/ M2TW mod unit browser in the format of a webpage.
Some 'interactive' components include: view filters (unit categories), search, morale & extended attack stats.
This webpage can be 'shipped' with a mod release or in a separate ZIP package. If the mod has a webhosting, uploading the project folder will make the unit browser available online.
This utility automates a whole pack of tasks including .pak unpacking, text file merging & conversion, optional unit stat transformations, and most importantly a ready-to-use unit browser framework.
I would appreciate that you keep the attribution part in the readme file bundled with your project, or at least show me your unit browser .

What does it look like?

For screenshots, you can head over to the RSII Unit browser thread which contains some. Here's one:

Spoiler Alert, click show to read: 

How to use

Initial setup

1. Extract this ZIP package to somewhere without UAC (User Account Control), eg your Desktop.
2. Copy the following text files from your RTW/M2TW install to the RDK's src/text/ dir:
   
   • In data/, export_descr_unit.txt and descr_sm_factions.txt.
   • In data/text/, export_units.txt and shared.txt.
   
   Note: These text files are often encoded in ANSI; to avoid incompatibilities with special text characters, open the files in Notepad++ first, set the encoding to UTF-8 (without BOM) and save.
3. Copy the TGA files from your RTW/M2TW data/loading_screens/symbols/ dir to the RDK's src/img/symbols/ dir.
4. Now either:
   
   • If your unit TGA's are packed (ui_1.pak), simply copy the ui_1.pak to the RDK's root folder (next to launch.bat, config.txt, etc.);
     in config.txt, set the use_pak option to 1.
   • If your unit TGA's are not packed, copy all subfolders from your RTW/M2TW UNITS/ folder to the RDK's src/img/units/ dir.

Customization

You have the following options for customizing the Unit Browser assets to your mod:

• In src\ folder, write (optional) readme copy in readme.txt. Even if you don't do this, a readme with standard instructions will be generated.
• In src\img\ folder, replace background.png with a tileable (preferably seamless) texture of your choice. Normally a large image bigger than 1920px width should be ok too.
• In src\img\ folder, replace logo.png with the logo for your mod (for best results, with a transparent background).
• In src\img\ folder, replace icon.png with the icon to be displayed in the browser tab + used as desktop icon (for best results, with a transparent background).
• Open up the RDK's src\js\vue-app.js file in a text editor. Go to the 5th line (var config = ...) and modify the options to fit your mod (instructions in comments).
• If you know HTML/CSS, you can tweak the display of your unit browser in the project/your_project/ dir, in the files: index.html, and/ or css/style.css.

Output Configuration

Open config.txt in a text editor and set the options as you desire:

• project_folder - specify the project folder name that will be created with launch.bat in project/ (may contain spaces). Consider specifying a version at the end (so older versions in the project/ dir don't get overwritten)
• project_zip - specify the project zip name that will be created with zip.bat in project/ (avoid spaces). Consider specifying a version at the end (so older versions in the project/ dir don't get overwritten)
• use_pak - set to 0 if your unit images are not packed; set to 1 if they are (tells launch.bat whether XPAK should be run first)
• exclude_factions - (default: construction, slave) All faction names (and non-faction media folder names in the UNITS directory) that should NOT be displayed in the unit browser
• exclude_units_imgs - (default: diplomat,spy,assassin) All unit names that should NOT be displayed in the unit browser
• units_rename - (default: #) All characters or character sequences that should be removed from the unit filenames
• factions_rename - (default: symbol128_) All characters or character sequences that should be removed from the symbol files and faction folders
• units_prop_whitespace - Any properties in export_descr_unit.txt that has whitespace in its name must be listed here.
• units_prop_first - If the mod adds a property before the 'type' property in export_descr_unit.txt blocks, it must be specified here.
• units_prop_last - If the mod adds a property after the 'ownership' property in export_descr_unit.txt blocks, it must be specified here.
• units_prop_array - Comma-separated list of properties that may contain multiple, comma-separated values in addition to 'ownership' and 'attributes'.
• readme_forum - A forum topic to refer to from the readme.txt
• readme_version - The version of the unit browser
• readme_updated - The 'last updated' date of the unit browser
• readme_author - The author of the unit browser
• readme_license - The license of the unit browser

For example, if you didn't want to include naval units in the output, you could add naval_* to the exclude_units_imgs option (* = wildcard).

Building it

1. In the RDK's root, run launch.bat. If your units were pak'ed and a second command prompt window opens up, hit Enter after it has completed.
2. If you followed the instructions you should now have a subdirectory in the RDK's project/ folder (with the name you specified for project_folder in config.txt).
3. Verify that the output works by opening index.html (in your project's subdirectory) in the browser.

Distributing it

If you're happy with the results, you can either:

• bundle for local use (packaged with mod/ downloadable): run zip.bat which will generate a ZIP archive in the RDK's project/ folder (with the name you specified in config.txt for project_zip).
• bundle for online use: simply open up FTP, and upload the project/your_folder folder to the website. The webpage should work out of the box.

Debugging it

You will possibly get errors during the command-line build/ when you open the file in your browser (trust me, you will).
Please first refer to the FAQ below, and if that doesn't work, contact me for help with all details possible on the error (when in the process? what error message? ).

RDK contents

The following is a short overview of the files/ tools included in the RDK package, and what they are used for.

/
├── config.txt - specify config options in this file before running a .bat file
├── readme.txt - short instructions on how to use
├── launch.bat - run when config.txt is properly configured. Will set up/ update a project folder in /project
├── zip.bat    - run when your project is finished; will auto-zip it in the /project directory
├── /src
|   ├── index.html - Webpage for the Unit Browser. Open in your browser to view
|   ├── create_shortcut.bat - Creates a shortcut to index.html on the desktop (Windows only)
|   ├── /img
|   |     ├── /symbols - copy paste the TGA files from RTW/M2TW's data/loading_screen/symbols/ directory here
|   |     ├── /units   - copy paste the entire RTW/M2TW's DATA/UI/UNITS/ folder here (*if pak'ed, read on)
|   |     ├── icon.png - Icon used in the browser tab and for generating a desktop icon
|   |     ├── logo.png - Mod's/ Game's logo displayed in the Unit browser page
|   |     └── background.png - Seamlessly tiled background of the Unit browser page
|   ├── /js
|   |     └── vue.min.js - Vue.js MVVM library
|   |     └── vue-app.js - Unit Browser's main script; provides functionality like search, filter, etc.
|   ├── /text  - copy paste text resources from RTW/M2TW here: export_descr_unit.txt, export_units.txt, descr_sm_factions.txt & shared.txt
|   └── /css
|         └── style.css - Unit Browser's stylesheet; if you know CSS feel free to tweak
├── /tools
|   ├── xpak.bat - A modified version of Vercingetorix' xpak.bat launcher
|   ├── xpak.exe - Vercingetorix' XPAK tool for RTW
|   ├── nconvert.exe - XnView command line utility for image conversion
|   ├── 7za.exe - 7zip command line utility (zipping)
|   ├── node.exe - NodeJS standalone command line wrapper
|   ├── readme-template.txt - Renders the readme with variables from the config + body text in src/readme.txt
|   ├── stat_modifiers.js - Can be used to modify unit stats in the output file
|   ├── text_convert.js - Is run with node.exe. Converts files in src\text\ to the required format
|   └── fs.js - Is run with node.exe, through launch.bat. Handles and coordinates all file ops
|
└── /project - will contain the project generated from \src with launch.bat (and the ZIP files generated with zip.bat)

Changelog

v1.0 2015-12-25
- First public release

v0.2 2015-10-01
- Added option for extended attack statistics (displays melee 2nd, AP weapons, and weapon type)
- Added ability 'Throws missile before charging' for 'prec' attribute units
- Moved unit counts to the view filter menu

v0.1 2015-09-25
- Fixed search & filter functions
- Added a scrollbar for longer descriptions
- Added faction-wide unit statistics (top right of the screen)
- Added readme.txt
- Reformatted and cleaned Javascript code

Credits

A special thanks goes out to:

- dvk901 and all other Roma Surrectum II enthusiasts for feedback on the first output prototype of this RDK.
- MasterOfNone (twcenter.net) for pre-testing this RDK with the RTW mod: The Fourth Age
- z3n for pre-testing this RDK with the MT2W Kingdoms mod: Europa Barbarorum II
- Aradan for his comprehensive EDU guide
- Vercingetorix for his PAK extractor tool
- The XnView team for their great command-line Nconvert (image conversion) tool
- Igor Pavlov for his 7zip command-line tool

[Tyblitz]

FAQ

*** PLACEHOLDER ***