@pietrovich/wot-utils 0.2.2 → 0.2.4

package/README.md

@@ -1,10 +1,13 @@
 # pie-wot
 
-A CLI toolkit for World of Tanks modders. Fetches live vehicle data from the Wargaming API, manipulates DDS textures and texture atlases, and generates custom icon sets — all from the terminal, no build step required.
+A CLI toolkit for World of Tanks modders. Fetches fresh vehicle data from the Wargaming API, manipulates DDS textures 
+and texture atlases, and generates custom icon sets — all from the terminal, no build step required.
 
-The long-term goal is to make it trivial to maintain and publish a custom icon set: when new vehicles are added to the game or tank characteristics change, re-running a handful of commands should be enough to produce an updated, publish-ready set. The [PogS icon set](https://github.com/pavelmaca/WoT-PogsIconSet) by @pavelmaca serves as the reference implementation and first supported style.
+The long-term goal is to make it trivial to maintain and publish a custom icon set: when new vehicles are added to 
+the game or tank characteristics change, re-running a handful of commands should be enough to produce an updated, 
+publish-ready set. The [PogS icon set](https://github.com/pavelmaca/WoT-PogsIconSet) by @pavelmaca served as the reference implementation and first supported style.
 
-## Pre-baked ready to use sets
+## Pre-baked, ready-to-use sets
 
 If you just want the icons without running the pipeline yourself, pre-baked sets are published periodically at [pietrovich/wot-pogs-like-icon-sets](https://github.com/pietrovich/wot-pogs-like-icon-sets) and kept in sync with game updates.
 
@@ -17,7 +20,7 @@ cp .env.example .env  # add your WG_APP_ID
 
 Get a free application ID at [developers.wargaming.net](https://developers.wargaming.net/).
 
-> **Node.js ≥ 24** required.
+> **Node.js ≥ 24** recommended. May work with older versions
 
 ## Uninstall
 
@@ -35,6 +38,9 @@ pie-wot vehicle stats             # short-name character statistics
 pie-wot vehicle best-config       # best module configuration per vehicle
 pie-wot vehicle chars             # character distribution in short names
 
+pie-wot game extract-icon-assets  # extract battle atlas files from a WoT installation
+pie-wot game extract-icons        # (alias for extract-icon-assets)
+
 pie-wot atlas inspect <map>       # list texture names in an atlas XML
 pie-wot atlas pick <map> <img>    # extract a single named texture
 pie-wot atlas extract             # extract all textures to a directory
@@ -44,11 +50,11 @@ pie-wot dds decode <file>         # decode a DDS texture to PNG
 pie-wot dds encode <file>         # encode a PNG to DXT5/BC3 DDS
 
 pie-wot icon dump-background      # generate per-type background images (PogS style)
-pie-wot icon render <query>       # render a vehicle icon: type background + short name label
+pie-wot icon render <query>       # render a vehicle icon (use --simple for simplified variant)
 
 pie-wot font render [font] [text] # render text as PNG using a pixel font
 
-pie-wot cache purge               # clear the local API response cache
+pie-wot cache purge               # clear the local WG API response cache
 
 pie-wot bake <script>             # run a bundled build script (see below)
 ```
@@ -71,6 +77,31 @@ Available scripts:
 | `clear` | PogS clear variant (no colour background) |
 | `color` | PogS colour variant with DMG/FSR/VR/RLD labels |
 
+### Customizing battle atlases
+
+To replace vehicle icons in the Player Panels on the battle screen, you need to work with the game's atlas files. 
+These are large texture sheets containing many icons packed together, defined by an XML location map.
+
+**Step 1: Extract original atlases from the game installation**
+
+```bash
+pie-wot game extract-icon-assets /path/to/wot /path/to/atlas-work
+```
+
+This extracts four files and converts the DDS textures to PNG for easier manipulation:
+- `battleAtlas.dds` (Player Panel icons)
+- `battleAtlas.xml` (location map)
+- `battleAtlas.dds` → `battleAtlas.png` 
+- `vehicleMarkerAtlas.dds` (vehicle marker icons)
+- `vehicleMarkerAtlas.xml` (location map)
+- `vehicleMarkerAtlas.dds` → `vehicleMarkerAtlas.png` 
+
+**Step 2–4: Split, replace, reassemble**
+
+Use the XML files to split the atlases into individual icon pieces, replace them with your custom versions, 
+and reassemble into new atlases. The final PNG can be saved with a `.dds` extension — the game will load 
+PNG-compressed assets transparently, giving you better quality than DDS without needing to encode to DXT5.
+
 ## Development
 
 ### Running from source
@@ -83,19 +114,6 @@ npm start -- <command>
 npm start -- vehicle list
 ```
 
-### LOCAL_DEV
-
-The bundled baker scripts (`scripts/`) detect whether the `pie-wot` global binary is available and use it by default. Set `LOCAL_DEV=true` in your `.env` (or environment) to force them to use `npm start` from the local clone instead:
-
-```
-LOCAL_DEV=true
-```
-
-This is useful when iterating on the CLI itself — changes to `src/` take effect immediately without a publish/reinstall cycle.
-
-## How it works
-
-API responses are cached locally (SHA-256 keyed, no TTL) so repeated runs don't hammer the Wargaming API. DDS encode/decode uses a trimmed BC1/BC3 codec derived from [photopea/UTEX.js](https://github.com/photopea/UTEX.js). Image compositing uses [sharp](https://sharp.pixelplumbing.com/).
 
 ## Credits