Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/timkurvers/dota2-model-viewer
Web-based Dota 2 model viewer
https://github.com/timkurvers/dota2-model-viewer
Last synced: 17 days ago
JSON representation
Web-based Dota 2 model viewer
- Host: GitHub
- URL: https://github.com/timkurvers/dota2-model-viewer
- Owner: timkurvers
- Created: 2021-02-02T13:59:21.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-04-24T19:38:41.000Z (over 1 year ago)
- Last Synced: 2024-10-12T03:20:06.539Z (about 1 month ago)
- Language: JavaScript
- Size: 296 KB
- Stars: 24
- Watchers: 4
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Dota 2 Model Viewer
A web-based model viewer for Dota 2 with additional support for rendering
portrait images, normally shown in the bottom part of the HUD on selection.
# Overview
This project is split into two parts:
- Model viewer web client ([`src/web`](./src/web))
- Pipeline server ([`src/pipeline`](./src/pipeline))
The pipeline server delivers Dota 2 assets to the web client on-demand, after these
assets have been extracted, decompiled and converted into web-compatible formats
using the excellent [ValveResourceFormat] library:
- Textures are delivered as PNGs.
- Models/meshes as [glTF binary files](https://www.khronos.org/gltf/).
- Valve's [KeyValues files](https://developer.valvesoftware.com/wiki/KeyValues) as JSON.
For simplicity's sake the pipeline server also serves up the web client from the
`public`-folder.
# Setup
1. Clone the repository:
```shell
git clone git://github.com/timkurvers/dota2-model-viewer.git
```
2. Download and install [Node.js] 14+ for your platform.
3. Install dependencies:
```shell
npm install
```
4. Download the latest version of [ValveResourceFormat]'s decompiler.
5. Copy `.envrc-sample` to `.envrc` and configure its contents.
Make sure that `DOTA2_DIR_VPK_PATH` points to Dota's `pak01_dir.vpk`-file and
`VRF_DECOMPILER_PATH` to VRF's decompiler from step 4 above.
6. Source the `.envrc`-file loading the configuration into the environment:
```shell
source .envrc
```
Alternatively, have [direnv] do this automatically 👍
7. Build the web client:
```shell
npm run build
```
8. Run the pipeline server on `localhost:3000` (default):
```shell
npm start
```
**Disclaimer:** The pipeline serves up resources to the browser over HTTP. Depending
on your network configuration these may be available to others. Respect laws and
do not distribute game data you do not own. This also includes content extracted
or placed into the folder indicated by `VRF_EXTRACT_PATH`.
# Usage
Instruct the viewer which model to load using the `model` query parameter:
http://localhost:3000/?model=models/creeps/roshan/roshan.vmdl
Visit http://localhost:3000/models.json for a list of available models.
To experiment freely with the scene, enable the debug panel:
http://localhost:3000/?model=models/creeps/roshan/roshan.vmdl&debug
All query parameters:
- `animate`: set to `false` to disable animations.
- `background`: sets scene background color; must be one of:
- `transparent`
- a named color, e.g. `red`.
- a URL-encoded hex triplet, e.g. `%23FF0000`.
- `debug`: enables the debug panel to allow fine-grained control of the scene.
- `helpers`: enables axes, grid, lighting and portrait camera visual helpers.
- `material`: overrides primary material.
- `portrait`: renders the model in portrait mode with a backdrop; supports two modes:
- present but without a value, defaults to matching the model rendered.
- with an explicit value, e.g. `default_courier`.
- `primaryMesh`: name of the mesh to render.
When the model viewer is not in portrait mode, freely rotate the camera using the
left mouse button, and pan using the right mouse button.
## Portrait pages
To quickly find portraits for various units, use the pre-made portrait pages:
- Selection of units: http://localhost:3000/portraits/index.html
- Selection of couriers: http://localhost:3000/portraits/couriers.html
- Lane creeps: http://localhost:3000/portraits/lane-creeps.html
- Neutral creeps: http://localhost:3000/portraits/neutral-creeps.html
- Structures: http://localhost:3000/portraits/structures.html
- Summons: http://localhost:3000/portraits/summons.html
- Wards: http://localhost:3000/portraits/wards.html
## Batch screenshots
To easily screenshot multiple models, create a batch-file:
```
roshan.png: model=models/creeps/roshan/roshan.vmdl
navi-courier.png: model=models/courier/navi_courier/navi_courier_flying.vmdl&portrait
```
Now pass this file as an argument to the bundled screenshot-command:
```shell
npm run screenshot batch.txt screenshots/ -- --width 250 --height 250
```
For a full overview of options, see its help: `npm run screenshot`.
## Known issues
- Heroes and other units lack attachments, such as weapons, armor, and sometimes
even their heads.
- Models are not correctly shaded nor lit in comparison to [ValveResourceFormat]'s
rendering. In particular: specular, rim and directional ambient lighting are missing.
- The portrait animation gets chosen based on a pattern matching heuristic, as
opposed to retrieving the right one directly from the Dota 2 game files.
- Only portraits listed in Dota 2's internal game file `scripts/npc/portraits.txt`
are currently supported.
- To debug the [ValveResourceFormat] decompiler, set the `DEBUG` environment variable
to `vrf:*`, for example: `DEBUG=vrf:* npm run start`.
# Development
Dota 2 Model Viewer is written in [ES2020+], powered by [MobX], controllable using
[dat.gui], modularized using [ECMAScript modules] and bundled with [webpack].
Run the pipeline server in development mode to automatically monitor source files:
```shell
npm run start:dev
```
Contributions more than welcome!
# Legalese
- Dota 2 is a registered trademark of [Valve Corporation].
- Image resources, lore and other references are property of [Valve Corporation].
[ECMAScript modules]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
[ES2020+]: https://www.strictmode.io/articles/whats-new-es2020/
[MobX]: https://mobx.js.org
[Node.js]: https://nodejs.org/
[Valve Corporation]: https://www.valvesoftware.com/
[ValveResourceFormat]: https://github.com/SteamDatabase/ValveResourceFormat
[dat.gui]: https://github.com/dataarts/dat.gui
[direnv]: https://direnv.net/
[webpack]: https://webpack.js.org/