wows-model-exporter

glTF/GLB exporter for World of Warships ship 3D models.

3D Model Formats

General formats and organization is detailed here MODEL.md (ship mesh pipeline — GameParams, assets.bin, LOD, textures).

The .geometry (actual 3D mesh) is detailed here: GEOMETRY.md.

Build

Clone the repository (submodules are required for bundled wows-depack on Linux):

git clone --recurse-submodules https://github.com/wows-tools/wows-model-exporter.git
cd wows-model-exporter

Linux (Debian / Ubuntu)

Install dependencies from packages (tinygltf is not bundled on Linux — use libtinygltf-dev):

sudo apt install cmake zlib1g-dev libpcre2-dev libmeshoptimizer-dev libtinygltf-dev \
                 python3-dev git clang

Configure and build (BUNDLE_WOWS_DEPACK compiles wows-depack from deps/wows-depack; omit it if you have a system libwows-depack and matching CMake package):

cmake . -DBUNDLE_WOWS_DEPACK=ON
make
 
./wows-gltf-exporter --help

Windows

C++ and Python dependencies are declared in vcpkg.json (zlib, pcre2, meshoptimizer, python3) and installed automatically by the bundled vcpkg submodule at deps/vcpkg on the first CMake configure. wows-depack and tinygltf are built from their submodules (BUNDLE_WOWS_DEPACK and BUNDLE_TINYGLTF). No separate Python install is required on Windows.

Prerequisites

• Git
• CMake

Automated build

From PowerShell in the repo root (CMake and Git on PATH):

.\scripts\setup_windows.ps1
.\scripts\setup_windows.ps1 -BuildType Debug

The script initializes submodules, bootstraps deps\vcpkg if needed, configures, and builds under build\.

Manual build

Matches Windows CI:

git submodule update --init --recursive
deps\vcpkg\bootstrap-vcpkg.bat -disableMetrics
 
cmake -B build `
  -DCMAKE_BUILD_TYPE=Release `
  -DBUILD_TESTS=OFF `
  -DBUNDLE_WOWS_DEPACK=ON `
  -DBUNDLE_TINYGLTF=ON
 
cmake --build build --config Release

Binaries are under build\Release\. To ship a portable folder or zip with the embedded Python runtime:

.\scripts\package_windows.ps1

This copies the tools from vcpkg_installed\x64-windows\tools\python3\ (python*.dll, Lib\, DLLs\) next to the executables.

Tools

wows-gltf-exporter: full ship GLB assembler

Reads the game files, in particular GameParams.data and assets.bin (via wows-depack), and stitches the model parts (.geometry vertices, .dds textures) together to export to .gltf/.glb format.

wows-gltf-exporter -W <wows-dir> -s <ship> -o <output.glb> [options]
 
Required:
  -W DIR     Root game directory (--wows-dir)
  -s NAME    Ship name or pattern (case-insensitive, words joined as .*w1.*w2.*)
  -o FILE    Output .glb file
 
Optional:
  -H UPG     Hull upgrade name substring (default: latest)
  -t         Exclude turret / mounted-component models
  -T         Skip DDS texture application
  -Z N       Max texture dimension in pixels (default: 2048)
  -L N       LOD level (-1 = auto, default: -1)
  -D         Include damage/crack geometry (default: excluded)
  -v         Verbose progress output

Hidden options (not shown in --help, but supported): -g / --gameparams and -a / --assets-bin to pass explicit paths to GameParams.data and assets.bin, this might be useful when working on unpacked resources (e.g. after extracting game all game files with wows-depack) instead of relying on auto-detection under -W.

export Kongo with all defaults:

wows-gltf-exporter -W /path/to/World\ of\ Warships/ -s Kongo_1942 -o kongo.glb

export Kongo specific hull, no turrets, Level of Detail 2 (LOD is 0 to 4, with 0 being the highest level):

wows-gltf-exporter -W /path/to/World\ of\ Warships/ -s Kongo_1942 -H HullB -t -L 2 -o kongo_hullb_lod2.glb

On Windows, assuming you installed WoWs through Steam, the equivalent commands should work:

# Note: don't add a trailing '\'
 
# List ships
.\wows-list-ships.exe -W 'C:\Program Files (x86)\Steam\steamapps\common\World of Warships'
 
# Example model
.\wows-gltf-exporter.exe -W 'C:\Program Files (x86)\Steam\steamapps\common\World of Warships' -s Kongo_1942 -o kongo.glb --verbose

To visualize and inspect the model, you can load it in babylonjs sandbox, or locally, you can use blender or f3d:

# sudo apt install f3d # if not available
f3d kongo_hullb_lod2.glb

wows-list-ships: enumerate available ships

Lists all ships found in GameParams.data, with optional filtering by nation or type:

wows-list-ships [-W <wows-dir>] [-n nation] [-t type]
 
  -W DIR     Root game directory (--wows-dir; auto-detects GameParams.data)
  -n STR     Filter by nation (case-insensitive substring)
  -t STR     Filter by ship type (case-insensitive substring)

Can be combined to export all ships to gltf (requires ~40GB):

wows-list-ships -W /path/to/World\ of\ Warships  | sed 's/[[:space:]].*//' | \
while read line;
do
    echo "------ $line ----";
    wows-gltf-exporter -W /path/to/World\ of\ Warships -s $line -o $line.glb --verbose;
done

wows-geometry-cli - single-file inspector / exporter

Parses one .geometry file, prints its structure, or exports it as GLB.

wows-geometry-cli -i <file.geometry> [-p] [-v] [-o output.glb] [-s 0,1,...]
 
  -i FILE    Input .geometry file
  -p         Print parsed structure
  -v         Print all vertex data (use with -p)
  -o FILE    Export submeshes to GLB (--output-glb)
  -s 0,1,…   Comma-separated vertex section indices to export (default: all)

Library API

wows-geometry exposes a C++ API for embedding ship export into your own tools. The main entry point is wows_stitch_export_ship() from inc/wows-model-exporter.h.

Full API reference: wows-tools.github.io/wows-model-exporter

Quick start

#include "wows-model-exporter.h"
 
wows_ship_export_options opts;
// all fields have sensible defaults; override only what you need:
// opts.hull_upgrade         = "HullB";   // empty = latest
// opts.with_turrets         = false;
// opts.with_textures        = false;
// opts.max_tex_size         = 1024;
// opts.lod_level            = 0;         // -1 = auto
// opts.exclude_damage       = false;
// opts.gameparams_path      = "/explicit/path/GameParams.data";  // auto-detected if empty
// opts.wows_assets_bin_path = "/explicit/path/assets.bin";       // auto-detected if empty
 
bool ok = wows_stitch_export_ship("/path/to/World\ of\ Warships/", "Kongo_1942", "kongo.glb", opts);

wows_stitch_export_ship handles everything: auto-detecting GameParams.data and assets.bin under game_dir, resolving hull and turret models, loading HP_ transforms and BlendBone corrections, decoding geometry, merging, texturing, and writing the GLB. Errors are printed to stderr; Python is initialised and finalised internally.

Export fields

Field	Default	Description
gameparams_path	""	Path to GameParams.data; auto-detected from game_dir if empty
wows_assets_bin_path	""	Path to assets.bin; auto-detected from game_dir if empty
hull_upgrade	""	Hull upgrade name substring (e.g. "HullB"); empty = latest
with_turrets	true	Include turret / mount geometry
with_textures	true	Apply DDS albedo textures
max_tex_size	2048	Maximum texture dimension in pixels
lod_level	-1	LOD level; -1 = auto-select highest triangle count
exclude_damage	true	Strip damage/crack render sets

Verbose output

wows_stitch_verbose = true;   // prints progress to stderr

Linking

target_link_libraries(my_tool wows-geometry)

Python 3 and all other dependencies are already linked into wows-geometry.

Lower-level API

If you need finer control (custom merge logic, streaming parts, etc.) the building-block functions used internally by wows_stitch_export_ship are also public: wows_stitch_find_hull_geoms, wows_stitch_geom_to_model, wows_stitch_merge_parts, wows_stitch_apply_textures, and the wows_assets_bin_* helpers in inc/wows-assets-bin.h.

Unit Tests

sudo apt install libcunit1-dev

To build and run tests with coverage (requires GCC):

cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCOVERAGE=ON -DBUILD_TESTS=ON .
make
make test
make coverage

Changelog

0.2.1

• better bundling of deps in Linux release

0.2.0

• Windows Support & CI

0.1.0

• First Release