VoxelForge/Standalone/Tools/webviewer

VoxelForge local web viewer

This folder contains a Python standard-library server, a .vfmesh to GLB converter, and a Three.js page for viewing exported VoxelForge worlds. The converter accepts VFMSH001 and VFMSH002 files, preserves vertex normals and tile/triangle counts, and writes metre-scale GLB geometry. It rotates VoxelForge's Z-up coordinates to glTF's Y-up coordinates.

Three.js and its GLTF loader are loaded from jsDelivr at the pinned version 0.160.0, so the browser needs internet access the first time it loads the page. Python and the viewer server need no package installs.

Convert existing meshes

From this directory, convert one or more existing exports:

python3 convert.py \
  ../../../Saved/Linux/l32/capture-sw-far-v20-settled-surface.vfmesh \
  ../../../Saved/Linux/l32/fi-floor-v20-lod4-focus.vfmesh \
  ../../../Saved/Linux/linux23/capture-fi-mouth.vfmesh

The GLBs go into meshes/ by default. To use another output folder, add --out-dir /path/to/glbs. The converter reads the source mesh directly and does not regenerate a world.

Start and view

cd Standalone/Tools/webviewer
python3 server.py

Open http://127.0.0.1:8000/ in a WebGL-capable browser on the same machine. The server binds only to 127.0.0.1; it does not listen on the LAN. To serve GLBs from a different local folder:

python3 server.py --mesh-dir /path/to/glbs --port 8000

On Windows with Python 3, run py -3 server.py --mesh-dir .\meshes from this folder and open http://127.0.0.1:8000/ on that Windows machine. For a phone or Quest browser on another device, this localhost-only server is not reachable from that device. Remote access, including a Tailscale setup, is outside this round.

Controls

• Click the world to capture the mouse, then use W/A/S/D and mouse movement to fly and look. Space rises; C or Ctrl descends. Esc releases the mouse.
• On touch screens, drag the left pad to move and the right pad to look. Touch pads can show or hide the pads; this also makes them available in headset browsers that do not report a coarse pointer.
• Adjust flight speed with the slider. Toggle wireframe or normal-colour shading in the panel.
• Choose mesh A and an optional mesh B. Click Show B or press B to switch between them. Fit view frames the active mesh.
• The overlay shows the active mesh's triangles and tiles and the camera position in metres.

The viewer uses normal-based lighting and distance fog. It applies a simple viewer material; VFMSH002 resource material IDs are read and skipped by the converter.