classic-wow-model-viewer

Web-based renderer for World of Warcraft 1.12.x (vanilla/classic) character models. Renders characters with equipment, animations, and configurable asset sources using Three.js.

Live Demo | GitHub

Install

npm install classic-wow-model-viewer three

Quick Start

import { ModelViewer, createCdnResolver } from 'classic-wow-model-viewer';

const viewer = new ModelViewer({
  container: document.getElementById('viewer')!,
  assets: createCdnResolver('https://your-cdn.com'),
});

await viewer.loadCharacter('human', 'male');
viewer.playAnimationByName('EmoteDance');

API

ModelViewer

Turnkey viewer — creates a Three.js scene, camera, controls, lighting, and render loop.

const viewer = new ModelViewer({
  container: HTMLElement,       // DOM element to mount into
  assets: AssetResolver,       // Where to fetch model files
  backgroundColor?: number,    // Default: 0x333333
});

| Method | Description | |--------|-------------| | loadCharacter(race, gender) | Load a character model | | equip(equipment) | Equip weapon, offhand, and/or armor | | unequip() | Clear all equipment | | getAnimations() | Get available animation list | | playAnimation(seqIndex) | Play animation by index | | playAnimationByName(name) | Play animation by name (e.g. 'Stand', 'Walk', 'EmoteDance') | | dispose() | Clean up all resources | | static getRaces() | Get list of supported races |

Supported races: Blood Elf, Dwarf, Gnome, Goblin, Human, Night Elf, Orc, Scourge, Tauren, Troll

createCdnResolver(baseUrl)

Creates an AssetResolver that prepends a base URL to all asset paths.

// Remote CDN
createCdnResolver('https://your-cdn.com')

// Local dev server
createCdnResolver('')

Low-level API

For consumers who manage their own Three.js scene:

import { loadModel, loadAnimations, AnimationController } from 'classic-wow-model-viewer';

const model = await loadModel('/models/human-male', resolver);
const animData = await loadAnimations('/models/human-male', resolver);
const controller = new AnimationController(animData, model.boneData, model.bones);

Equipment

await viewer.equip({
  weapon: { path: '/items/weapon/arcanite-reaper' },
  armor: {
    torsoUpperBase: '/item-textures/TorsoUpperTexture/Plate_A_01Silver_Chest_TU',
    helmet: 'helm-plate-d-02',
    helmetGeosetVisID: [67, 67],
    shoulderSlug: 'leather-blood-b-01',
    shoulderHasRight: true,
    handGeoset: 2,
    footGeoset: 2,
  },
});

The viewer handles rendering. Mapping item IDs to asset paths is the consumer's responsibility — see the Chronicle demo for an example.

Asset CDN

The viewer fetches models from a CDN you provide. You can:

1. Use an existing CDN — point createCdnResolver at any hosted asset set
2. Host your own — extract assets from a WoW 1.12.x game client using the extraction tools, then upload the public/ folder to any static host

See the CDN Pipeline Guide for full details.

Framework Integration

The viewer takes a DOM element and has a dispose() method — works with any framework.

React

import { useRef, useEffect } from 'react';
import { ModelViewer, createCdnResolver } from 'classic-wow-model-viewer';

function WowViewer({ race, gender }) {
  const ref = useRef(null);
  const viewerRef = useRef(null);

  useEffect(() => {
    const v = new ModelViewer({ container: ref.current, assets: createCdnResolver('https://your-cdn.com') });
    viewerRef.current = v;
    return () => v.dispose();
  }, []);

  useEffect(() => { viewerRef.current?.loadCharacter(race, gender); }, [race, gender]);

  return <div ref={ref} style={{ width: '100%', height: '400px' }} />;
}

Svelte / Vue / Solid

See the framework examples in the repo README.

License

MIT — see LICENSE for details.

This package is a rendering tool only. It does not include any game assets. All World of Warcraft game data is the intellectual property of Blizzard Entertainment, Inc. This project is not affiliated with or endorsed by Blizzard Entertainment.