@gamewall/threejs 1.0.1 → 1.2.0

package/README.md

@@ -61,12 +61,12 @@ This function is asynchronous because KTX2 textures may require transcoding, whi
 
 > ℹ️ Note: You can use [KTX-Software](https://github.com/KhronosGroup/KTX-Software) to convert your textures to KTX2 format with the following command:
 > ```bash
-> toktx2 --t2 --bcmp output.ktx2 input.png
+> 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 }]>`
+### `async loadGltf(name: string, renderer: THREE.WebGLRenderer): Promise<[THREE.Object3D, { [name: string]: THREE.MeshPhysicalMaterial }, GLTF]>`
 
 Loads a GLTF/GLB model from the GameWall assets, with support for KTX2 and Meshopt.
 
@@ -89,7 +89,13 @@ async function loadModel() {
 }
 ```
 
-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.
+This function returns a touple containing
+
+- the loaded model (as a THREE.Object3D),
+- a dictionary of materials by their names, and
+- the full GLTF object.
+
+This allows you to easily access the 3D object and modify specific materials after loading and access other GLTF data. For advanced use cases, like modifying animations or accessing specific nodes, you can use the GLTF object directly.
 
 > ⚠️ 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.
 
@@ -99,7 +105,7 @@ It is also asynchronous because GLTF loading may involve fetching multiple resou
 
 > ℹ️ Note: you can use [gltfpack](https://meshoptimizer.org/gltf/) to compress your GLTF models with Meshopt and KTX2 for optimal performance and size with the following command:
 > ```bash
-> gltfpack  -c -tc -tp -kn -km -i input.glb -o output.glb
+> gltfpack -c -tc -tp -kn -km -noq -i input.glb -o output.glb
 > ```
 > 
 > - `-c` enables mesh compression with Meshopt
@@ -107,5 +113,24 @@ It is also asynchronous because GLTF loading may involve fetching multiple resou
 > - `-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.
+
+```typescript
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamewall/threejs",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "ThreeJS utils for GameWall",
   "main": "src/index.ts",
   "scripts": {

package/src/gltf.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three'
-import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
+import { GLTFLoader, GLTF } from 'three/addons/loaders/GLTFLoader.js'
 import { getBuffer } from 'gamewall'
 import { extractBuffer } from './utils'
 
@@ -19,7 +19,7 @@ export function getGltfLoader(renderer: THREE.WebGLRenderer): GLTFLoader {
   return loader;
 }
 
-export async function loadGltf(url: string, renderer: THREE.WebGLRenderer): Promise<[THREE.Object3D, { [name: string]: THREE.MeshPhysicalMaterial }]> {
+export async function loadGltf(url: string, renderer: THREE.WebGLRenderer): Promise<[THREE.Object3D, { [name: string]: THREE.MeshPhysicalMaterial }, GLTF]> {
   const glbBuffer = extractBuffer(getBuffer(url));
   const gltfLoader = getGltfLoader(renderer);
 
@@ -52,5 +52,5 @@ export async function loadGltf(url: string, renderer: THREE.WebGLRenderer): Prom
     }
   });
 
-  return [result, Object.fromEntries(materials)];
+  return [result, Object.fromEntries(materials), gltf];
 }

package/src/index.ts

@@ -1,3 +1,4 @@
 export { getExr } from './exr';
 export { loadKtx2 } from './ktx2';
 export { loadGltf } from './gltf';
+export { loadTexture } from './texture';

package/src/texture.ts

@@ -0,0 +1,19 @@
+import * as THREE from 'three';
+import { getUrl } from 'gamewall';
+
+let loader: THREE.TextureLoader | null = null;
+
+export function getTextureLoader(): THREE.TextureLoader {
+    if (!loader) {
+        loader = new THREE.TextureLoader();
+    }
+    return loader;
+}
+
+export async function loadTexture(url: string): Promise<THREE.Texture> {
+    const textureLoader = getTextureLoader();
+
+    return new Promise<THREE.Texture>((resolve, reject) => {
+        textureLoader.load(getUrl(url), resolve, undefined, reject);
+    });
+}