ThreeJS bindings and utils for GameWall

This package provides some essential utilities to work with ThreeJS in the GameWall environment. Most of ThreeJS works out of the box, but certain loaders like EXR or KTX2 assume a folder/URL structure on a remote host that's incompatible with how GameWall serves assets. This package fills that gap by providing custom loaders that work seamlessly with GameWall's asset management.

Installation

You can install the package via npm:

npm install @gamewall/threejs

SDK version 0.22.1 or higher is required for the WASM imports to work correctly. If you have an older SDK, please update with:

npm install gamewall@latest

Usage

The following utils are provided:

getExr(name: string, renderer: THREE.WebGLRenderer): THREE.Texture

Loads an EXR texture from the GameWall assets and automatically builds a PMREM environment map out of it. Commonly used for backgrounds and environment maps.

• name is the filename of the EXR file in the GameWall assets folder.
• renderer is your ThreeJS WebGLRenderer instance. Providing it allows the function to create the PMREM map correctly.

import * as THREE from 'three';
import { getExr } from '@gamewall/threejs';

function loadEnvironment() {
  const envMap = getExr('environment.exr', renderer);
  scene.background = envMap; // Use the environment map as background
  scene.environment = envMap; // Use the environment map for reflections
}

This function can operate synchronously because it relies on GameWall's getBuffer function, and ThreeJS's EXRLoader can parse from an ArrayBuffer directly.

async loadKtx2(name: string, renderer: THREE.WebGLRenderer): Promise<THREE.CompressedTexture>

Loads a KTX2 compressed texture from the GameWall assets.

• name is the filename of the KTX2 file in the GameWall assets folder.
• renderer is your ThreeJS WebGLRenderer instance. KTX2Loader needs it to determine supported compressed texture formats.

import * as THREE from 'three';
import { loadKtx2 } from '@gamewall/threejs';

async function loadTexture() {
  const texture = await loadKtx2('texture.ktx2', renderer);
  const material = new THREE.MeshStandardMaterial({ map: texture }); // Use the loaded texture
}

This function is asynchronous because KTX2 textures may require transcoding, which is done in a Web Worker.

ℹ️ Note: You can use KTX-Software to convert your textures to KTX2 format with the following command:

toktx --t2 --bcmp output.ktx2 input.png

• --t2 ensures the texture is in KTX2 format
• --bcmp applies Basis Universal supercompression

async loadGltf(name: string, renderer: THREE.WebGLRenderer): Promise<[THREE.Object3D, { [name: string]: THREE.MeshPhysicalMaterial }]>

Loads a GLTF/GLB model from the GameWall assets, with support for KTX2 and Meshopt.

• name is the filename of the GLTF/GLB file in the GameWall assets folder.
• renderer is your ThreeJS WebGLRenderer instance. This is needed for the KTX2Loader integration.

import * as THREE from 'three';
import { loadGltf, loadKtx2 } from '@gamewall/threejs';

async function loadModel() {
  const [model, materials] = await loadGltf('model.gltf', renderer);
  scene.add(model); // Add the loaded model to the scene

  // Optionally modify materials
  if ('sponsorLogo' in materials) {
    sponsorLogo = await loadKtx2('sponsorLogo.ktx2', renderer);
    materials['sponsorLogo'].map = sponsorLogo;
  }
}

This function returns a touple containing the loaded model (as a THREE.Object3D) and a dictionary of materials by their names. This allows you to easily modify specific materials after loading.

⚠️ Warning: The returned materials dictionary only includes PBR materials (MeshPhysicalMaterial). Please make sure your 3D modeling tool exports materials in this format for compatibility. If you use Blender, the default "Principled BSDF" shader corresponds to MeshPhysicalMaterial in ThreeJS.

It is also asynchronous because GLTF loading may involve fetching multiple resources (like textures) and decoding them, including KTX2 textures.

⚠️ Warning: you cannot rely on an internet connection in the GameWall environment. We recommend using self-contained GLB files with embedded resources for best compatibility.

ℹ️ Note: you can use gltfpack to compress your GLTF models with Meshopt and KTX2 for optimal performance and size with the following command:

gltfpack -c -tc -tp -kn -km -noq -i input.glb -o output.glb

• -c enables mesh compression with Meshopt
• -tc enables KTX2 texture compression
• -tp converts textures to power-of-two dimensions for better GPU compatibility
• -kn keeps the names in the model to allow modifying specific nodes
• -km keeps the material names in the model to allow modifying specific materials
• -noq keeps original UV coordinates, to allow for retexturing

On average, you should see around 70-80% size reduction compared to uncompressed GLTF/GLB files.

async loadTexture(name: string): Promise<THREE.Texture>

Loads a standard texture (PNG, JPEG, etc.) from the GameWall assets. Convenience wrapper around ThreeJS's TextureLoader.

• name is the filename of the texture file in the GameWall assets folder.

import * as THREE from 'three';
import { loadTexture } from '@gamewall/threejs';

async function loadStandardTexture() {
  const texture = await loadTexture('sponsorLogo.png');
  const material = new THREE.MeshStandardMaterial({ map: texture }); // Use the loaded texture
}

ℹ️ Note: This works with image properties in the configurables section of your manifest too.