⬡ NWN MDL Viewer

A browser-based 3D model viewer for Neverwinter Nights 1: Enhanced Edition binary AND decompiled ASCII .mdl files. No installation, no server — just open index.html locally or use it directly via GitHub Pages.

🌐 Live Demo: https://dunahan.github.io/nwn_mdl_webviewer/

---

✨ Features

• MDL ASCII Parser — Parses all node types: trimesh, skin, dummy, emitter, aabb, light, reference
• 3D Rendering — Phong shading with ambient, directional and fill lights
• Scene Graph — Full node hierarchy in the sidebar, each node individually toggleable
• Node Inspector — Click any node to see vertices, faces, bitmap name, position, diffuse colour, alpha
• Camera Controls — Orbit (LMB drag), Zoom (scroll wheel), Pan (RMB drag), touch support
• Wireframe Overlay — Adjustable opacity slider
• Lighting Control — Intensity slider
• Extras — Auto-rotation, Bounding Box display, Grid toggle, Flat/Smooth shading
• Zero dependencies — Only Three.js r152 (loaded from CDN); runs fully offline once cached

---

🚀 Quick Start

Option A — GitHub Pages (recommended)

1. Fork or clone this repository
2. Go to Settings → Pages → Source → Deploy from branch → main / (root)
3. Visit https://<your-username>.github.io/nwn_mdl_webviewer/

Option B — Local use (with a release)

1. Download the latest Release from GitHub.
2. Open in browser (Chrome, Firefox, Edge)
3. Drag .mdl + texture files (.tga, .dds etc) into the drop zone.

Option C — Local use (python3 needed!)

git clone https://github.com/dunahan/nwn_mdl_webviewer.git
cd nwn_mdl_webviewer

# creates dist/index.html
python3 build.py

# Simply open index.html in any modern browser:
cd dist
open index.html          # macOS
start index.html         # Windows
xdg-open index.html      # Linux

---

📁 File Format

NWN stores models as compiled binary .mdl files. This viewer uses the CleanModelsEE WASM release from plenarius to get the readable ASCII file. Despite everything, I recommend converting the binary model using Cleanmodels and ideally also repairing it.

How to decompile/repair

Using cleanmodels:

Grab the latest binary for your platform for CleanModelsEE

# Decompile a binary MDL to ASCII (will overwrite the compiled file)
cleanmodels decompile plc_torch.mdl plc_torch.mdl

# Output to a separate folder (originals untouched and will produce ASCII files)
cleanmodels repair -a -r haks/ cleaned/

# Save everything (stdout + stderr)
cleanmodels check -r -v models/ &> log.txt

For more details, take a look at the CleanModelsEE

Using nwnmdlcomp (command line tool):

# Download from:
# https://neverwintervault.org/project/nwn1/other/tool/nwnmdlcomp-nwn-model-compiler

nwnmdlcomp -d c_dragon.mdl
# → outputs c_dragon_ascii.mdl  (or similar name)

Using other tools:

Tool	Platform	Notes
NWNExplorer	Windows	GUI, can export ASCII MDL

---

📂 Project Structure

nwn-mdl-webviewer/
├── index.html              # Main application (self-contained)
├── README.md               # This file
├── LICENSE                 # MIT License
├── build.py                # Python script for building the release
├── .gitignore
├── wasm/                   # Where the cleanmodel.wasm resides
├── testfiles/              # some files for testing
├── src-tauri/icons         # the generated icons for a Tauri build (later)
├── scripts/                # scripts for manual building the resources for a offline version
├── lang/
│   ├── de.json             # German translation file
│   ├── en.json             # English Translation file
│   └── README.md	        # HowTo set up a new translation and integrate it
├── js/                     # JavaScript files
├── docs/
│   ├── FORMAT.md           # NWN MDL format reference
│   └── DECOMPILE.md        # Step-by-step decompilation guide
├── css/                    # CSS definition
└── .github/
    └── workflows/
        └── pages.yml       # GitHub Pages auto-deploy workflow

---

🎮 Usage

1. Open the viewer in your browser
2. Drag & drop a de-/compiled .mdl file onto the viewport — or click the drop zone and pick a file
3. Use the sidebar to inspect nodes and toggle visibility
4. Click any node name in the list to see its details

Controls

Action	Control
Orbit	Left mouse drag
Zoom	Scroll wheel
Pan	Right mouse drag
Inspect node	Click sidebar item
Toggle visibility	Click ⬡ icon next to node

Features for Enhanced Edition models (MTR)

Symbol	Color	Meaning
$\textcolor{gold}{\textsf{✓}}$	gold	Texture loaded and active
$\textcolor{yellow}{\textsf{?}}$	amber	Referenced in MTR, but file not loaded
$\textcolor{darkgrey}{\textsf{—}}$	grey	Slot not defined in MTR

Error Log

• A ▲ button with a counter badge appears on the right side of the status bar.

• In case of an error, the panel opens automatically.

• In case of a warning, the badge lights up orange, but it does not open automatically.

• Clicking ▲/▼ manually opens/closes the panel.

• When a new model is loaded, the log is automatically cleared.

Sign	Color	Hint
$\textcolor{red}{\textsf{✕}}$	Red	Error (TGA/DDS parse, MDL, file read)
$\textcolor{orange}{\textsf{⚠}}$	Orange	Warnung
$\textcolor{darkgrey}{\textsf{·}}$	Grey	Info

All error sources now write to the panel: for example TGA, DDS, MDL and FileReader errors — with timestamp and filename.

---

⚠️ Known Limitations

• Animations: Keyframe animations defined in newanim blocks are parsed (count shown) but not yet played back
• Binary MDL: Only ASCII/decompiled format is supported
• Walkmesh: AABB nodes are shown as markers but walkmesh geometry is not rendered separately
• Not every model has been tested yet, so there may still be display errors.

---

🗺️ Roadmap

• Texture loading (TGA via tga.js, DDS support)
• Animation playback (keyframe interpolation)
• Export to glTF/OBJ
• Multiple file loading (supermodel chain)
• Walkmesh visualisation overlay

---

🛠️ Tech Stack

Technology	Version	Purpose
Three.js	r152	3D rendering (WebGL)
Vanilla JS	ES2020	MDL parser, UI logic
HTML/CSS	—	UI (no framework)
Cinzel	—	Display font (Google Fonts)
Share Tech Mono	—	Monospace UI font

---

📜 License

MIT — see LICENSE

---

🙏 Credits

• Bioware / Beamdog for the NWN MDL format
• Three.js contributors
• NWN community tools: nwneetools, NWNExplorer

---

Made with ♥ for the Neverwinter Nights modding community