teleportxr 1.0.91 → 1.0.93

package/client/client.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const fs= require("fs");
+const path= require("path");
 const core= require("../core/core.js");
 const command= require("../protocol/command.js");
 const message= require("../protocol/message.js");
@@ -54,6 +56,9 @@ class Client {
         this.clientID=cid;
         this.origin_uid=0;
         this.handshakeMessage=new message.HandshakeMessage();
+		// The client's axes standard, learned from its Handshake. Used to pick the matching
+		// cubemap variant to stream (e.g. GlStyle -> *_ogl.ktx2). NotInitialized until handshake.
+		this.clientAxesStandard=core.AxesStandard.NotInitialized;
 		this.geometryService=new gs.GeometryService(cid);
 		// Per-client avatar negotiation state. The host application drives
 		// when (and whether) policy is sent via this service.
@@ -223,6 +228,9 @@ class Client {
 		this.setupCommand.int64_startTimestamp_utc_unix_us = BigInt(core.getStartTimeUnixUs());
 		if(this.scene)
 		{
+			// Tell the client which axes standard the server authored the scene in. Node transforms
+			// are converted to the client's own standard at encode time (see SendNode).
+			this.setupCommand.AxesStandard_axesStandard=this.scene.serverAxesStandard;
 			if(this.scene.backgroundTexturePath&&this.scene.backgroundTexturePath!="")
 			{
 				this.setupCommand.BackgroundMode_backgroundMode=BackgroundMode.TEXTURE;
@@ -545,7 +553,9 @@ class Client {
 		var node=this.scene.GetNode(uid);
 		const MAX_NODE_SIZE=500;
 		const buffer = new ArrayBuffer(MAX_NODE_SIZE);
-		const nodeSize=node_encoder.encodeNode(node,buffer);
+		// Convert the node's transform from the server's axes standard to this client's, exactly as
+		// the C++ server does in GeometryEncoder::encodeNodes (ConvertTransform server->client).
+		const nodeSize=node_encoder.encodeNode(node,buffer,this.scene.serverAxesStandard,this.clientAxesStandard);
 		const view2 = new DataView(buffer, 0, nodeSize);
 		if(!this.webRtcConnection)
 		{
@@ -564,6 +574,34 @@ class Client {
 		if(sendSuccess)
 			this.geometryService.EncodedResource(uid);
 	}
+	//! For a cubemap resource, return the URL of the variant matching this client's axes
+	//! standard (e.g. /envCloudyCubemap.ktx2 -> /envCloudyCubemap_ogl.ktx2). Returns undefined
+	//! to mean "use the resource's base url" — for non-cubemaps, unknown axes standards, or
+	//! when the variant file is missing under the public path (so streaming never breaks).
+	CubemapUrlForClient(resource)
+	{
+		if(!resource || !resource.isCubemap)
+			return undefined;
+		const suffix=core.AxesStandardToCubemapSuffix(this.clientAxesStandard);
+		if(!suffix)
+			return undefined;
+		const candidate=resources.InsertCubemapAxesSuffix(resource.url, suffix);
+		if(candidate===resource.url)
+			return undefined;
+		// Only serve the variant if it actually exists; otherwise fall back to the base file.
+		if(this.scene&&this.scene.publicPath)
+		{
+			// URLs are server-relative (e.g. "/envCloudyCubemap.ktx2"); strip any scheme/host.
+			const rel=candidate.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]*/, "");
+			const full=path.join(this.scene.publicPath, rel);
+			if(!fs.existsSync(full))
+			{
+				console.warn("Cubemap variant "+full+" not found; serving base "+resource.url+" to client "+this.clientID);
+				return undefined;
+			}
+		}
+		return candidate;
+	}
 	SendGenericResource(uid)
 	{
 		var resource=resources.GetResourceFromUid(uid);
@@ -572,9 +610,10 @@ class Client {
 			console.warn("No resource of uid ",uid," was found.")
 			return;
 		}
+		const urlOverride=this.CubemapUrlForClient(resource);
 		const MAX_BUFFER_SIZE=resource.encodedSize();;
 		const buffer = new ArrayBuffer(MAX_BUFFER_SIZE);
-		const resourceSize=resource_encoder.EncodeResource(resource,buffer);
+		const resourceSize=resource_encoder.EncodeResource(resource,buffer,urlOverride);
 		const view2 = new DataView(buffer, 0, resourceSize);
 		if(!this.webRtcConnection)
 		{
@@ -588,7 +627,7 @@ class Client {
 			return;
 		}
 		const sendSuccess = this.webRtcConnection.sendGeometry(view2);
-		console.log("[T+"+this.elapsedMsSinceStart()+"ms, conn+"+this.elapsedMsSinceConnected()+"ms] Sending resource "+uid+" "+resource.url+" to Client "+this.clientID+", size: "+resourceSize+" bytes — "+
+		console.log("[T+"+this.elapsedMsSinceStart()+"ms, conn+"+this.elapsedMsSinceConnected()+"ms] Sending resource "+uid+" "+(urlOverride||resource.url)+" to Client "+this.clientID+", size: "+resourceSize+" bytes — "+
 			(sendSuccess ? "OK" : "FAILED"));
 		if(sendSuccess)
 			this.geometryService.EncodedResource(uid);
@@ -619,6 +658,10 @@ class Client {
         }
         var handshakeMessage=new message.HandshakeMessage();
 		core.decodeFromUint8Array(handshakeMessage,data);
+		// Remember the client's axes standard so cubemaps are streamed in the matching variant.
+		this.clientAxesStandard=handshakeMessage.AxesStandard_axesStandard;
+		console.log("Client "+this.clientID+" handshake axesStandard="+this.clientAxesStandard
+			+" (cubemap suffix '"+core.AxesStandardToCubemapSuffix(this.clientAxesStandard)+"')");
         const excess		=data.length-message.HandshakeMessage.sizeof();
         const numReceived	=excess/core.UID_SIZE;
         if(numReceived!=handshakeMessage.uint64_resourceCount) {

package/core/core.js

@@ -175,12 +175,136 @@ const AxesStandard =
 	LeftHanded: 2,
 	YVertical: 4,
 	ZVertical: 8,
-	EngineeringStyle: this.ZVertical | this.RightHanded,
-	GlStyle: 16 | this.YVertical | this.RightHanded,
-	UnrealStyle: 32 | this.ZVertical | this.LeftHanded,
-	UnityStyle: 64 | this.YVertical | this.LeftHanded,
+	// NB: these must be explicit literals, not `this.ZVertical | ...`. Inside an object
+	// literal `this` is the module scope, not the object, so the bitwise expressions would
+	// silently evaluate to the wrong values (e.g. EngineeringStyle=0, GlStyle=16). The wire
+	// protocol and clients use 9 and 21, so hard-code the resolved values to match.
+	EngineeringStyle: 8 | 1,	// ZVertical | RightHanded = 9
+	GlStyle: 16 | 4 | 1,		// 16 | YVertical | RightHanded = 21
+	UnrealStyle: 32 | 8 | 2,	// 32 | ZVertical | LeftHanded = 42
+	UnityStyle: 64 | 4 | 2,		// 64 | YVertical | LeftHanded = 70
 };
 
+//! Map a client's axes standard to the filename suffix used for the matching cubemap
+//! variant. e.g. GlStyle -> "ogl", so /envCloudyCubemap.ktx2 -> /envCloudyCubemap_ogl.ktx2.
+//! Returns "" for an unknown/uninitialised standard, meaning "serve the original file".
+function AxesStandardToCubemapSuffix(axesStandard)
+{
+	switch (axesStandard)
+	{
+		case AxesStandard.GlStyle:			return "ogl";
+		case AxesStandard.EngineeringStyle:	return "eng";
+		case AxesStandard.UnrealStyle:		return "unreal";
+		case AxesStandard.UnityStyle:		return "unity";
+		default:							return "";
+	}
+}
+
+// ---- Axes-standard conversions for object transforms ----
+// Ported from the C++ server (libavstream common_maths.h ConvertPosition/Rotation/Scale), which
+// converts each node's transform from the server's axes standard to the client's during encoding.
+// The C++ table only covers Unreal/Unity <-> Gl/Engineering (its server is engine-driven), so the
+// Engineering <-> GlStyle cases below are added here (both right-handed: position/quat vector part
+// maps as (x, z, -y); its inverse as (x, -z, y); scale permutes y/z).
+function ConvertPosition(from, to, p)
+{
+	const A = AxesStandard;
+	if (from === to) return { x: p.x, y: p.y, z: p.z };
+	if (from === A.UnrealStyle)
+	{
+		if (to === A.GlStyle)          return { x: +p.y, y: +p.z, z: -p.x };
+		if (to === A.EngineeringStyle) return { x: p.y, y: p.x, z: p.z };
+	}
+	else if (from === A.UnityStyle)
+	{
+		if (to === A.GlStyle)          return { x: p.x, y: p.y, z: -p.z };
+		if (to === A.EngineeringStyle) return { x: p.x, y: p.z, z: p.y };
+	}
+	else if (from === A.EngineeringStyle)
+	{
+		if (to === A.UnrealStyle)      return { x: p.y, y: p.x, z: p.z };
+		if (to === A.UnityStyle)       return { x: p.x, y: p.z, z: p.y };
+		if (to === A.GlStyle)          return { x: p.x, y: p.z, z: -p.y };	// added
+	}
+	else if (from === A.GlStyle)
+	{
+		if (to === A.UnrealStyle)      return { x: -p.z, y: +p.x, z: +p.y };
+		if (to === A.UnityStyle)       return { x: p.x, y: p.y, z: -p.z };
+		if (to === A.EngineeringStyle) return { x: p.x, y: -p.z, z: p.y };	// added
+	}
+	console.warn("ConvertPosition: unsupported axes "+from+"->"+to+"; leaving unchanged");
+	return { x: p.x, y: p.y, z: p.z };
+}
+
+function ConvertRotation(from, to, q)
+{
+	const A = AxesStandard;
+	if (from === to) return { x: q.x, y: q.y, z: q.z, w: q.w };
+	if (from === A.UnrealStyle)
+	{
+		if (to === A.GlStyle)          return { x: -q.y, y: -q.z, z: +q.x, w: q.w };
+		if (to === A.EngineeringStyle) return { x: -q.y, y: -q.x, z: -q.z, w: q.w };
+	}
+	else if (from === A.EngineeringStyle)
+	{
+		if (to === A.UnrealStyle)      return { x: -q.y, y: -q.x, z: -q.z, w: q.w };
+		if (to === A.UnityStyle)       return { x: -q.x, y: -q.z, z: -q.y, w: q.w };
+		if (to === A.GlStyle)          return { x: q.x, y: q.z, z: -q.y, w: q.w };	// added
+	}
+	else if (from === A.GlStyle)
+	{
+		if (to === A.UnrealStyle)      return { x: +q.z, y: -q.x, z: -q.y, w: q.w };
+		if (to === A.UnityStyle)       return { x: -q.x, y: -q.y, z: q.z, w: q.w };
+		if (to === A.EngineeringStyle) return { x: q.x, y: -q.z, z: q.y, w: q.w };	// added
+	}
+	else if (from === A.UnityStyle)
+	{
+		if (to === A.GlStyle)          return { x: -q.x, y: -q.y, z: q.z, w: q.w };
+		if (to === A.EngineeringStyle) return { x: -q.x, y: -q.z, z: -q.y, w: q.w };
+	}
+	console.warn("ConvertRotation: unsupported axes "+from+"->"+to+"; leaving unchanged");
+	return { x: q.x, y: q.y, z: q.z, w: q.w };
+}
+
+function ConvertScale(from, to, s)
+{
+	const A = AxesStandard;
+	if (from === to) return { x: s.x, y: s.y, z: s.z };
+	if (from === A.UnrealStyle)
+	{
+		if (to === A.GlStyle)          return { x: +s.y, y: +s.z, z: s.x };
+		if (to === A.EngineeringStyle) return { x: s.y, y: s.x, z: s.z };
+	}
+	else if (from === A.UnityStyle)
+	{
+		if (to === A.GlStyle)          return { x: s.x, y: s.y, z: s.z };
+		if (to === A.EngineeringStyle) return { x: s.x, y: s.z, z: s.y };
+	}
+	else if (from === A.EngineeringStyle)
+	{
+		if (to === A.UnrealStyle)      return { x: s.y, y: s.x, z: s.z };
+		if (to === A.UnityStyle)       return { x: s.x, y: s.z, z: s.y };
+		if (to === A.GlStyle)          return { x: s.x, y: s.z, z: s.y };	// added (abs of position map)
+	}
+	else if (from === A.GlStyle)
+	{
+		if (to === A.UnrealStyle)      return { x: s.z, y: +s.x, z: +s.y };
+		if (to === A.UnityStyle)       return { x: s.x, y: s.y, z: s.z };
+		if (to === A.EngineeringStyle) return { x: s.x, y: s.z, z: s.y };	// added
+	}
+	return { x: s.x, y: s.y, z: s.z };
+}
+
+//! Convert a {position, orientation, scale} pose from one axes standard to another.
+function ConvertPose(from, to, pose)
+{
+	return {
+		position:    ConvertPosition(from, to, pose.position),
+		orientation: ConvertRotation(from, to, pose.orientation),
+		scale:       ConvertScale(from, to, pose.scale || { x: 1, y: 1, z: 1 }),
+	};
+}
+
 const GeometryPayloadType =
 {
 	Invalid: 0,
@@ -441,7 +565,9 @@ function put_string(dataView, byteOffset, name) {
 
 module.exports = {
 	UID_SIZE, endian, SizeOfType, encodeIntoDataView, decodeFromDataView
-	, vec4, BackgroundMode, AxesStandard, GeometryPayloadType, DisplayInfo, RenderingFeatures, LightingMode, VideoCodec
+	, vec4, BackgroundMode, AxesStandard, AxesStandardToCubemapSuffix
+	, ConvertPosition, ConvertRotation, ConvertScale, ConvertPose
+	, GeometryPayloadType, DisplayInfo, RenderingFeatures, LightingMode, VideoCodec
 	, VideoConfig, ClientDynamicLighting, encodeToUint8Array, decodeFromUint8Array
 	, generateUid, getStartTimeUnixUs, getTimestampUs,
 	unixTimeToUTCString, put_float32, put_uint16, put_int32, put_uint32

package/package.json

@@ -16,7 +16,7 @@
   },
   "name": "teleportxr",
   "description": "Teleport Spatial Server on node.js",
-  "version": "1.0.91",
+  "version": "1.0.93",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/simul/teleport-nodejs.git"

package/protocol/encoders/node_encoder.js

@@ -13,13 +13,15 @@ function putPlaceholderSize(dataView)
 }
 
 // return the size of the encoded node.
-function encodeNode(node,buffer)
+// fromAxes/toAxes, when supplied, convert the node's transform from the server's axes standard to
+// the client's during encoding (matches the C++ server). Omit them to encode the pose unchanged.
+function encodeNode(node,buffer,fromAxes,toAxes)
 {
 	var byteOffset=0;
-	const dataView = new DataView(buffer); 
+	const dataView = new DataView(buffer);
 	byteOffset=putPlaceholderSize(dataView);
 
-	var t=node.encodeIntoDataView(dataView,byteOffset);
+	var t=node.encodeIntoDataView(dataView,byteOffset,fromAxes,toAxes);
 	byteOffset=t;
 	// Actual size is now known: write the count of bytes that follow the
 	// size field, in little-endian (the protocol convention). Without the

package/protocol/encoders/resource_encoder.js

@@ -13,12 +13,14 @@ function putPlaceholderSize(dataView)
 }
 
 // return the size of the encoded resource.
-function EncodeResource(res,buffer)
+// urlOverride, if supplied, is passed to the resource so it can encode a client-specific
+// url (e.g. an axes-standard cubemap variant) without mutating the shared resource.
+function EncodeResource(res,buffer,urlOverride)
 {
 	var byteOffset=0;
-	const dataView = new DataView(buffer); 
+	const dataView = new DataView(buffer);
 	byteOffset=putPlaceholderSize(dataView);
-	var t=res.encodeIntoDataView(dataView,byteOffset);
+	var t=res.encodeIntoDataView(dataView,byteOffset,urlOverride);
 	byteOffset=t;
 	t-=8;
 	// Actual size is now known: write the count of bytes that follow the

package/scene/node.js

@@ -308,7 +308,7 @@ class Node {
 		);
 		this.components.push(tc);
 	}
-	encodeIntoDataView(dataView, byteOffset) {
+	encodeIntoDataView(dataView, byteOffset, fromAxes, toAxes) {
 		byteOffset = core.put_uint8(
 			dataView,
 			byteOffset,
@@ -317,8 +317,19 @@ class Node {
 
 		byteOffset = core.put_uint64(dataView, byteOffset, this.uid);
 		byteOffset = core.put_string(dataView, byteOffset, this.name);
+		// Convert the node's transform into the client's axes standard (server -> client). When no
+		// conversion is requested, or the standards match, the pose is encoded unchanged.
 		var clientsidePose = this.pose;
-		
+		if (fromAxes !== undefined && toAxes !== undefined && fromAxes !== toAxes &&
+			toAxes !== core.AxesStandard.NotInitialized)
+		{
+			const c = core.ConvertPose(fromAxes, toAxes, this.pose);
+			clientsidePose = new Pose();
+			clientsidePose.position = c.position;
+			clientsidePose.orientation = c.orientation;
+			clientsidePose.scale = c.scale;
+		}
+
 		byteOffset = clientsidePose.encodeIntoDataView(dataView, byteOffset);
 		
 		byteOffset = core.put_uint8(dataView, byteOffset, this.stationary);

package/scene/resources.js

@@ -16,16 +16,21 @@ class Resource {
 		this.uid = uid;
 		this.url = url;
 		this.type = type;
+		// True for environment cubemaps (background/diffuse/specular). Such resources are
+		// served per-client in the variant matching the client's axes standard.
+		this.isCubemap = false;
 	}
 	encodedSize(){
 		return 500;
 	}
-	encodeIntoDataView(dataView, byteOffset) {
+	//! urlOverride, if supplied, replaces this.url for this encoding only (e.g. to send a
+	//! client-specific cubemap variant). The stored this.url is left untouched.
+	encodeIntoDataView(dataView, byteOffset, urlOverride) {
 		byteOffset = core.put_uint8(dataView, byteOffset, this.type);
 		byteOffset = core.put_uint64(dataView, byteOffset, this.uid);
-		var url = this.url;
-		if (this.url.search("://") == -1)
-			url = Resource.defaultPathRoot + this.url;
+		var url = urlOverride || this.url;
+		if (url.search("://") == -1)
+			url = Resource.defaultPathRoot + url;
 		byteOffset = core.put_string(dataView, byteOffset, url);
 		return byteOffset;
 	}
@@ -211,6 +216,28 @@ function GetOrAddTexture(url) {
 	return GetOrAddResourceFromUrl(core.GeometryPayloadType.TexturePointer, url);
 }
 
+//! Get or add a cubemap texture, flagging the resource so it is served per-client in the
+//! variant matching the client's axes standard. Returns the resource uid.
+function GetOrAddCubemap(url) {
+	const uid = GetOrAddTexture(url);
+	const res = GetResourceFromUid(uid);
+	if (res)
+		res.isCubemap = true;
+	return uid;
+}
+
+//! Insert an axes suffix before a cubemap URL's extension:
+//!   InsertCubemapAxesSuffix("/envCloudyCubemap.ktx2", "ogl") -> "/envCloudyCubemap_ogl.ktx2"
+//! Returns the url unchanged when the suffix is empty.
+function InsertCubemapAxesSuffix(url, suffix) {
+	if (!suffix || !url)
+		return url;
+	const dot = url.lastIndexOf(".");
+	if (dot < 0)
+		return url + "_" + suffix;
+	return url.substring(0, dot) + "_" + suffix + url.substring(dot);
+}
+
 //! Get or add the mesh url as a resource.
 function GetOrAddMesh(url) {
 	return GetOrAddResourceFromUrl(core.GeometryPayloadType.MeshPointer, url);
@@ -238,6 +265,8 @@ module.exports = {
 	GetOrAddResourceUidFromUrl,
 	GetResourceFromUid,
 	GetOrAddTexture,
+	GetOrAddCubemap,
+	InsertCubemapAxesSuffix,
 	GetOrAddMesh,
 	AddFontAtlas,
 	AddTextCanvas,

package/scene/scene.js

@@ -15,6 +15,10 @@ class Scene {
 		this.specularCubemapPath="";
 		this.assetsPath="assets";
 		this.publicPath="http_resources";
+		// The axes standard the scene (node poses, cubemaps) is authored in. Node transforms are
+		// converted from this to each client's axes standard when streamed. Z-up Engineering by
+		// default, matching the C++ client's native frame and the *_eng cubemap source.
+		this.serverAxesStandard=core.AxesStandard.EngineeringStyle;
 	}
 	GetOrCreateNode(uid) {
 		if (!this.nodes.has(uid)) {
@@ -191,17 +195,19 @@ class Scene {
 			if(j.environment.background_texture)
 			{
 				this.backgroundTexturePath=j.environment.background_texture;
-				resources.GetOrAddTexture(this.backgroundTexturePath);
+				// The environment background is a cubemap; flag it so each client is served the
+				// variant matching its axes standard (falls back to the base file if absent).
+				resources.GetOrAddCubemap(this.backgroundTexturePath);
 			}
 			if(j.environment.diffuse_cubemap)
 			{
 				this.diffuseCubemapPath=j.environment.diffuse_cubemap;
-				resources.GetOrAddTexture(this.diffuseCubemapPath);
+				resources.GetOrAddCubemap(this.diffuseCubemapPath);
 			}
 			if(j.environment.specular_cubemap)
 			{
 				this.specularCubemapPath=j.environment.specular_cubemap;
-				resources.GetOrAddTexture(this.specularCubemapPath);
+				resources.GetOrAddCubemap(this.specularCubemapPath);
 			}
 		}
 		if(j.font_atlases)