@downdraft/engine 0.2.0 → 0.3.1

package/dist/libraries/entities/src/model-renderer.js

@@ -9,7 +9,7 @@
 // — no per-draw bind-group creation or texture bind-group churn.
 // ============================================================================
 import { calculateViewProj, createLogger, createValidatedShaderModule, DEPTH_FORMAT, MSAA_SAMPLE_COUNT } from "@downdraft/engine";
-const MODEL_WGSL = "struct Uniforms {\n  viewProj: mat4x4<f32>,\n  cameraPos: vec3<f32>,\n  time: f32,\n  modelPos: vec3<f32>,\n  modelScale: vec3<f32>,\n  modelRot: vec4<f32>,\n  materialIndex: u32,\n  lightDirX: f32,\n  lightDirY: f32,\n  lightDirZ: f32,\n  lightAmbient: f32,\n  lightIntensity: f32,\n  // Per-draw highlight mode: 0 = normal shading, 1 = ghost hologram (cyan,\n  // used for the physgun's no-collision grab), 2 = hover outline (drawn by a\n  // separate inverted-hull pipeline — see vs_outline / fs_outline).\n  // Values >= 3 encode per-prop material overrides (spawn settings):\n  //   combined = u32(highlight) - 3\n  //   shaderMode = combined & 3   (0=Standard 1=Toon 2=Hologram 3=Outline)\n  //   texMode    = combined >> 2  (0=Default 1=Wireframe 2=Checker)\n  highlight: f32,\n  // Inverted-hull outline parameters (used by vs_outline / fs_outline only).\n  outlineWidth: f32,\n  outlineColor: vec3<f32>,\n};\n\n@group(0) @binding(0) var<uniform> uniforms: Uniforms;\n\n// Skin matrices for skinned meshes (@group(1)). A dynamic storage buffer of\n// mat4x4<f32>, one per bone. Updated per-frame by the renderer via\n// updateSkinMatrices(). Only bound when drawing skinned meshes.\n@group(1) @binding(0) var<storage, read> skinMatrices: array<mat4x4<f32>>;\n\n// Frame-global lighting (@group(2)): sun color, hemisphere ambient, point lights.\n// Games that want colored lighting provide a compatible uniform buffer; the\n// default bind group supplies a neutral white sun + no point lights so existing\n// consumers see no visual change.\nstruct FrameLighting {\n  sunDir: vec3<f32>,\n  ambientIntensity: f32,\n  sunColor: vec3<f32>,\n  pointLightCount: u32,\n  skyAmbient: vec3<f32>,\n  _pad0: u32,\n  groundAmbient: vec3<f32>,\n  _pad1: u32,\n  pointLights: array<vec4<f32>, 16>,\n};\n@group(2) @binding(0) var<uniform> frameLighting: FrameLighting;\n\n// Bindless material binding model (@group(3)):\n//   binding 0: material SSBO (read-only storage)\n//   bindings 1..8: texture_2d_array pages (rgba8unorm color textures)\n//   binding 9: shared sampler (repeat)\n//   binding 10: shared sampler (clamp)\nstruct BindlessMaterial {\n  baseColor: vec4<f32>,\n  roughness: f32,\n  metallic: f32,\n  emissiveIntensity: f32,\n  hasTexTransform: f32,\n  albedoTex: u32,\n  normalTex: u32,\n  metallicRoughnessTex: u32,\n  aoEmissiveTex: u32,\n  texOffset: vec2<f32>,\n  texScale: vec2<f32>,\n  texRotation: f32,\n  _pad0: f32,\n  _pad1: f32,\n  _pad2: f32,\n};\n\n@group(3) @binding(0) var<storage, read> bindlessMaterials: array<BindlessMaterial>;\n@group(3) @binding(1) var albedoArray0: texture_2d_array<f32>;\n@group(3) @binding(2) var albedoArray1: texture_2d_array<f32>;\n@group(3) @binding(3) var albedoArray2: texture_2d_array<f32>;\n@group(3) @binding(4) var albedoArray3: texture_2d_array<f32>;\n@group(3) @binding(5) var albedoArray4: texture_2d_array<f32>;\n@group(3) @binding(6) var albedoArray5: texture_2d_array<f32>;\n@group(3) @binding(7) var albedoArray6: texture_2d_array<f32>;\n@group(3) @binding(8) var albedoArray7: texture_2d_array<f32>;\n@group(3) @binding(9) var bindlessSamplerRepeat: sampler;\n@group(3) @binding(10) var bindlessSamplerClamp: sampler;\n\nfn unpackArrayIndex(handle: u32) -> u32 { return (handle >> 16u) & 0xFFFFu; }\nfn unpackLayerIndex(handle: u32) -> u32 { return handle & 0xFFFFu; }\n\nfn sampleBindlessArray(arr: u32, uv: vec2<f32>, layer: u32) -> vec4<f32> {\n  // textureSample (auto-LOD) so mipmapped registrations actually filter;\n  // single-mip textures behave identically to textureSampleLevel(..., 0.0).\n  switch (arr) {\n    case 0u: { return textureSample(albedoArray0, bindlessSamplerRepeat, uv, layer); }\n    case 1u: { return textureSample(albedoArray1, bindlessSamplerRepeat, uv, layer); }\n    case 2u: { return textureSample(albedoArray2, bindlessSamplerRepeat, uv, layer); }\n    case 3u: { return textureSample(albedoArray3, bindlessSamplerRepeat, uv, layer); }\n    case 4u: { return textureSample(albedoArray4, bindlessSamplerRepeat, uv, layer); }\n    case 5u: { return textureSample(albedoArray5, bindlessSamplerRepeat, uv, layer); }\n    case 6u: { return textureSample(albedoArray6, bindlessSamplerRepeat, uv, layer); }\n    case 7u: { return textureSample(albedoArray7, bindlessSamplerRepeat, uv, layer); }\n    default: { return vec4<f32>(1.0, 1.0, 1.0, 1.0); }\n  }\n}\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n};\n\n// Skinned vertex input — extends VertexInput with joints (4 bone indices,\n// packed as vec4<u32>) and weights (4 normalized bone weights). Lives in a\n// second vertex buffer slot (buffer index 1).\nstruct SkinnedVertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n  @location(4) joints: vec4<u32>,\n  @location(5) weights: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) worldPos: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n};\n\n// Build a tangent basis from the geometric normal. Uses a reference vector\n// instead of screen-space derivatives (dpdx/dpdy) which can produce NaN on\n// some implementations / degenerate UVs. The tangent direction is arbitrary\n// (determined by the reference vector) but is sufficient for normal mapping\n// on meshes without explicit tangent attributes.\nfn buildTangentBasis(N: vec3<f32>, worldPos: vec4<f32>, uv: vec2<f32>) -> mat3x3<f32> {\n  var refVec = vec3<f32>(0.0, 1.0, 0.0);\n  if (abs(N.y) >= 0.99) {\n    refVec = vec3<f32>(1.0, 0.0, 0.0);\n  }\n  let T = normalize(cross(refVec, N));\n  let B = cross(N, T);\n  return mat3x3<f32>(T, B, N);\n}\n\n// Sample the normal map and perturb the geometric normal. Returns the\n// perturbed world-space normal. If the material has no normal map (normalTex\n// points at the default white texture), the sampled tangent-space normal is\n// (0.5, 0.5, 1.0) → unpacked to (0, 0, 1) → no perturbation.\nfn perturbNormal(N: vec3<f32>, worldPos: vec4<f32>, uv: vec2<f32>, normalTexHandle: u32) -> vec3<f32> {\n  let arr = unpackArrayIndex(normalTexHandle);\n  let layer = unpackLayerIndex(normalTexHandle);\n  let sampled = sampleBindlessArray(arr, uv, layer);\n  let tangentNormal = sampled.xyz * 2.0 - 1.0;\n  let basis = buildTangentBasis(N, worldPos, uv);\n  return normalize(basis * tangentNormal);\n}\n\nfn qrotate(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> {\n  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);\n}\n\n// Accumulate the 4-bone skinning matrix: sum(weights[i] * skinMatrices[joint[i]]).\n// If all weights are zero (vertex has no bone assignment), return identity so\n// the vertex renders at its baked position instead of collapsing to the origin.\nfn skinMatrix(j: vec4<u32>, w: vec4<f32>) -> mat4x4<f32> {\n  let m = skinMatrices[j.x] * w.x\n        + skinMatrices[j.y] * w.y\n        + skinMatrices[j.z] * w.z\n        + skinMatrices[j.w] * w.w;\n  let wsum = w.x + w.y + w.z + w.w;\n  if (wsum < 0.001) {\n    return mat4x4<f32>(\n      vec4(1.0, 0.0, 0.0, 0.0),\n      vec4(0.0, 1.0, 0.0, 0.0),\n      vec4(0.0, 0.0, 1.0, 0.0),\n      vec4(0.0, 0.0, 0.0, 1.0),\n    );\n  }\n  return m;\n}\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let scaled = input.position * uniforms.modelScale;\n  let rotated = qrotate(uniforms.modelRot, scaled);\n  let worldPos = rotated + uniforms.modelPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = normalize(qrotate(uniforms.modelRot, input.normal));\n  output.uv = input.uv;\n  output.color = input.color;\n  return output;\n}\n\n// Skinned vertex entry point. Applies linear blend skinning in model space\n// (skinMatrices already encode bone-world * inverseBind), then the same\n// model transform (scale/rot/pos) as vs_main.\n@vertex\nfn vs_skinned(input: SkinnedVertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let sm = skinMatrix(input.joints, input.weights);\n  let skinnedPos = (sm * vec4<f32>(input.position, 1.0)).xyz;\n  let skinnedNormal = (sm * vec4<f32>(input.normal, 0.0)).xyz;\n\n  let scaled = skinnedPos * uniforms.modelScale;\n  let rotated = qrotate(uniforms.modelRot, scaled);\n  let worldPos = rotated + uniforms.modelPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = normalize(qrotate(uniforms.modelRot, normalize(skinnedNormal)));\n  output.uv = input.uv;\n  output.color = input.color;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let geometricN = normalize(input.normal);\n\n  // Bindless material lookup (needed for normal map handle + albedo).\n  let m = bindlessMaterials[uniforms.materialIndex];\n\n  // Perturb the normal using the material's normal map (if any). Materials\n  // without a normal map use the default flat-normal texture (0.5,0.5,1.0)\n  // → unpacked to (0,0,1) → no perturbation.\n  let N = perturbNormal(geometricN, vec4<f32>(input.worldPos, 1.0), input.uv, m.normalTex);\n\n  // Decode per-prop material overrides (highlight >= 3).\n  var shaderMode = 0u;\n  var texMode = 0u;\n  if (uniforms.highlight >= 3.0) {\n    let combined = u32(uniforms.highlight) - 3u;\n    shaderMode = combined & 3u;\n    texMode = combined >> 2u;\n  }\n\n  // Colored directional sun light — matches the procedural cube/sphere shader.\n  let sunDir = normalize(frameLighting.sunDir);\n  var ndotl = max(dot(N, sunDir), 0.0);\n  // Toon shader override: quantize the sun term into discrete bands.\n  if (shaderMode == 1u) {\n    ndotl = floor(ndotl * 3.0 + 0.5) / 3.0;\n    ndotl = max(ndotl, 0.15);\n  }\n  let sunDiffuse = ndotl * frameLighting.sunColor;\n\n  // Hemisphere ambient: blend sky/ground based on normal.y (same as cube shader).\n  let hemiMix = N.y * 0.5 + 0.5;\n  let hemisphere = mix(frameLighting.groundAmbient, frameLighting.skyAmbient, hemiMix);\n  let ambient = hemisphere * frameLighting.ambientIntensity;\n\n  // Bindless albedo sample: index the material SSBO by materialIndex, then\n  // sample the texture_2d_array page/layer the material points at.\n  let arr = unpackArrayIndex(m.albedoTex);\n  let layer = unpackLayerIndex(m.albedoTex);\n  let texColor = sampleBindlessArray(arr, input.uv, layer);\n\n  // All inputs are sRGB: texture (rgba8unorm), vertex color (white), and\n  // baseColor (parser converts FBX linear DiffuseColor to sRGB). The swapchain\n  // is non-sRGB (bgra8unorm), so output sRGB directly.\n  var baseColor = texColor.rgb * input.color * m.baseColor.rgb;\n\n  // ── Texture override modes ──\n  // Wireframe: darken albedo, UV-grid lines overlaid after lighting.\n  // Checker: two-tone checkerboard over the UVs.\n  var texLine = 0.0;\n  if (texMode == 1u) {\n    let g = fract(input.uv * 6.0);\n    let lx = min(g.x, 1.0 - g.x);\n    let ly = min(g.y, 1.0 - g.y);\n    texLine = 1.0 - smoothstep(0.0, 0.08, min(lx, ly));\n    baseColor = baseColor * 0.15;\n  } else if (texMode == 2u) {\n    let cell = floor(input.uv * 8.0);\n    let check = (cell.x + cell.y) - floor((cell.x + cell.y) * 0.5) * 2.0;\n    baseColor = mix(baseColor * 0.35, baseColor * 1.4 + vec3<f32>(0.08), check);\n  }\n\n  // Channel-inspection modes — bypass lighting entirely for material review.\n  // 3 = perturbed normals (normal-map contribution visible), 4 = unlit albedo\n  // (texture/baseColor only), 5 = geometric normals (no normal map).\n  if (texMode == 3u) { return vec4<f32>(N * 0.5 + vec3<f32>(0.5), 1.0); }\n  if (texMode == 4u) { return vec4<f32>(baseColor, 1.0); }\n  if (texMode == 5u) { return vec4<f32>(geometricN * 0.5 + vec3<f32>(0.5), 1.0); }\n\n  var litColor = baseColor * (ambient + sunDiffuse);\n\n  // Point lights (up to 8). Each light is 2 vec4s: (pos.xyz, radius) + (color.rgb, intensity).\n  let plCount = frameLighting.pointLightCount;\n  for (var i = 0u; i < plCount; i++) {\n    let pl0 = frameLighting.pointLights[i * 2u];\n    let pl1 = frameLighting.pointLights[i * 2u + 1u];\n    let plPos = pl0.xyz;\n    let plRadius = pl0.w;\n    let plColor = pl1.xyz;\n    let plIntensity = pl1.w;\n    let L = plPos - input.worldPos;\n    let dist = length(L);\n    if (dist < plRadius) {\n      let atten = 1.0 / (1.0 + dist * dist / (plRadius * plRadius));\n      let ndotl_pl = max(dot(N, normalize(L)), 0.0);\n      litColor += baseColor * plColor * plIntensity * atten * ndotl_pl;\n    }\n  }\n\n  // Wireframe overlay: paint the UV-grid lines in a bright tint.\n  if (texLine > 0.0) {\n    litColor = mix(litColor, vec3<f32>(0.55, 0.95, 1.0), texLine * 0.9);\n  }\n\n  // Distance fog — anchored to the camera→model distance so it scales with\n  // the subject instead of a fixed 400m absolute (a 200m model viewed from\n  // 500m would otherwise fog to the ambient color entirely). Small models\n  // near the camera keep the original ~400m reach.\n  let modelDist = length(uniforms.cameraPos - uniforms.modelPos);\n  let fogStart = max(modelDist * 1.5, 60.0);\n  let fogEnd = max(modelDist * 4.0, 400.0);\n  let dist = length(uniforms.cameraPos - input.worldPos);\n  let fog = clamp(1.0 - (dist - fogStart) / (fogEnd - fogStart), 0.0, 1.0);\n  var outColor = mix(frameLighting.skyAmbient, litColor, fog);\n\n  // Outline shader override (shaderMode == 3): darken the body and add a\n  // bright fresnel rim so the prop reads with a bold cel edge.\n  if (shaderMode == 3u) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 3.0);\n    outColor = outColor * 0.7 + vec3<f32>(1.0, 0.95, 0.6) * smoothstep(0.35, 0.9, fresnel);\n  }\n\n  // Hologram shader override (shaderMode == 2): fresnel rim + scanline pulse\n  // tinted toward the prop's own base color. Opaque output (the pipeline has\n  // no blend state) but reads as a hologram.\n  if (shaderMode == 2u) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 2.5);\n    let pulse = 0.65 + 0.35 * sin(uniforms.time * 5.0 + input.worldPos.y * 3.0);\n    let scan = 0.5 + 0.5 * sin((input.worldPos.y + uniforms.time * 2.0) * 20.0);\n    let holoBase = baseColor * vec3<f32>(0.3, 0.9, 1.1) + vec3<f32>(0.05, 0.2, 0.25);\n    let holoRim = vec3<f32>(0.7, 1.0, 1.0);\n    var holoCol = mix(holoBase, holoRim, fresnel) * pulse;\n    holoCol = holoCol + holoRim * scan * 0.15 * fresnel;\n    return vec4<f32>(holoCol, 1.0);\n  }\n\n  // Ghost hologram override (highlight == 1): render the prop as a\n  // translucent-looking cyan shell with a fresnel rim and a vertical\n  // scanline pulse so it's visually distinct from normally-grabbed (solid)\n  // props. Opaque output (the pipeline has no blend state) but reads as a\n  // hologram. Hover outline (highlight == 2) is handled by a separate\n  // inverted-hull draw — see vs_outline / fs_outline below.\n  if (uniforms.highlight > 0.5 && uniforms.highlight < 1.5) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 2.5);\n    let pulse = 0.65 + 0.35 * sin(uniforms.time * 5.0 + input.worldPos.y * 3.0);\n    let scan = 0.5 + 0.5 * sin((input.worldPos.y + uniforms.time * 2.0) * 20.0);\n    let ghostBase = vec3<f32>(0.15, 0.75, 0.95);\n    let ghostRim = vec3<f32>(0.7, 1.0, 1.0);\n    var ghostCol = mix(ghostBase, ghostRim, fresnel) * pulse;\n    ghostCol = ghostCol + ghostRim * scan * 0.15 * fresnel;\n    return vec4<f32>(ghostCol, 1.0);\n  }\n\n  return vec4<f32>(outColor, 1.0);\n}\n\n// ── Mask entry point for post-process outline ──\n// Renders the model as solid white to a mask texture.  Uses the same\n// vertex shader as the normal render (vs_main / vs_skinned).\n@fragment\nfn fs_mask() -> @location(0) vec4f {\n  return vec4f(1.0, 1.0, 1.0, 1.0);\n}\n";
+const MODEL_WGSL = "struct Uniforms {\n  viewProj: mat4x4<f32>,\n  cameraPos: vec3<f32>,\n  time: f32,\n  modelPos: vec3<f32>,\n  modelScale: vec3<f32>,\n  modelRot: vec4<f32>,\n  materialIndex: u32,\n  lightDirX: f32,\n  lightDirY: f32,\n  lightDirZ: f32,\n  lightAmbient: f32,\n  lightIntensity: f32,\n  // Per-draw highlight mode: 0 = normal shading, 1 = ghost hologram (cyan,\n  // used for the physgun's no-collision grab), 2 = hover outline (drawn by a\n  // separate inverted-hull pipeline — see vs_outline / fs_outline).\n  // Values >= 3 encode per-prop material overrides (spawn settings):\n  //   combined = u32(highlight) - 3\n  //   shaderMode = combined & 3   (0=Standard 1=Toon 2=Hologram 3=Outline)\n  //   texMode    = combined >> 2  (0=Default 1=Wireframe 2=Checker)\n  highlight: f32,\n  // Inverted-hull outline parameters (used by vs_outline / fs_outline only).\n  outlineWidth: f32,\n  outlineColor: vec3<f32>,\n  // Base index of this draw's bone region inside the shared skinMatrices\n  // storage buffer (group(1)). Written by ModelRenderer from the node's\n  // reserved region — lets multiple skinned models animate independently.\n  // Only read by vs_skinned.\n  boneBase: u32,\n  _padSkin0: u32,\n  _padSkin1: u32,\n  _padSkin2: u32,\n};\n\n@group(0) @binding(0) var<uniform> uniforms: Uniforms;\n\n// Skin matrices for skinned meshes (@group(1)). A dynamic storage buffer of\n// mat4x4<f32>, one per bone. Updated per-frame by the renderer via\n// updateSkinMatrices(). Only bound when drawing skinned meshes.\n@group(1) @binding(0) var<storage, read> skinMatrices: array<mat4x4<f32>>;\n\n// Frame-global lighting (@group(2)): sun color, hemisphere ambient, point lights.\n// Games that want colored lighting provide a compatible uniform buffer; the\n// default bind group supplies a neutral white sun + no point lights so existing\n// consumers see no visual change.\nstruct FrameLighting {\n  sunDir: vec3<f32>,\n  ambientIntensity: f32,\n  sunColor: vec3<f32>,\n  pointLightCount: u32,\n  skyAmbient: vec3<f32>,\n  _pad0: u32,\n  groundAmbient: vec3<f32>,\n  _pad1: u32,\n  pointLights: array<vec4<f32>, 16>,\n};\n@group(2) @binding(0) var<uniform> frameLighting: FrameLighting;\n\n// Bindless material binding model (@group(3)):\n//   binding 0: material SSBO (read-only storage)\n//   bindings 1..8: texture_2d_array pages (rgba8unorm color textures)\n//   binding 9: shared sampler (repeat)\n//   binding 10: shared sampler (clamp)\nstruct BindlessMaterial {\n  baseColor: vec4<f32>,\n  roughness: f32,\n  metallic: f32,\n  emissiveIntensity: f32,\n  hasTexTransform: f32,\n  albedoTex: u32,\n  normalTex: u32,\n  metallicRoughnessTex: u32,\n  aoEmissiveTex: u32,\n  texOffset: vec2<f32>,\n  texScale: vec2<f32>,\n  texRotation: f32,\n  _pad0: f32,\n  _pad1: f32,\n  _pad2: f32,\n};\n\n@group(3) @binding(0) var<storage, read> bindlessMaterials: array<BindlessMaterial>;\n@group(3) @binding(1) var albedoArray0: texture_2d_array<f32>;\n@group(3) @binding(2) var albedoArray1: texture_2d_array<f32>;\n@group(3) @binding(3) var albedoArray2: texture_2d_array<f32>;\n@group(3) @binding(4) var albedoArray3: texture_2d_array<f32>;\n@group(3) @binding(5) var albedoArray4: texture_2d_array<f32>;\n@group(3) @binding(6) var albedoArray5: texture_2d_array<f32>;\n@group(3) @binding(7) var albedoArray6: texture_2d_array<f32>;\n@group(3) @binding(8) var albedoArray7: texture_2d_array<f32>;\n@group(3) @binding(9) var bindlessSamplerRepeat: sampler;\n@group(3) @binding(10) var bindlessSamplerClamp: sampler;\n\nfn unpackArrayIndex(handle: u32) -> u32 { return (handle >> 16u) & 0xFFFFu; }\nfn unpackLayerIndex(handle: u32) -> u32 { return handle & 0xFFFFu; }\n\nfn sampleBindlessArray(arr: u32, uv: vec2<f32>, layer: u32) -> vec4<f32> {\n  // textureSample (auto-LOD) so mipmapped registrations actually filter;\n  // single-mip textures behave identically to textureSampleLevel(..., 0.0).\n  switch (arr) {\n    case 0u: { return textureSample(albedoArray0, bindlessSamplerRepeat, uv, layer); }\n    case 1u: { return textureSample(albedoArray1, bindlessSamplerRepeat, uv, layer); }\n    case 2u: { return textureSample(albedoArray2, bindlessSamplerRepeat, uv, layer); }\n    case 3u: { return textureSample(albedoArray3, bindlessSamplerRepeat, uv, layer); }\n    case 4u: { return textureSample(albedoArray4, bindlessSamplerRepeat, uv, layer); }\n    case 5u: { return textureSample(albedoArray5, bindlessSamplerRepeat, uv, layer); }\n    case 6u: { return textureSample(albedoArray6, bindlessSamplerRepeat, uv, layer); }\n    case 7u: { return textureSample(albedoArray7, bindlessSamplerRepeat, uv, layer); }\n    default: { return vec4<f32>(1.0, 1.0, 1.0, 1.0); }\n  }\n}\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n};\n\n// Skinned vertex input — extends VertexInput with joints (4 bone indices,\n// packed as vec4<u32>) and weights (4 normalized bone weights). Lives in a\n// second vertex buffer slot (buffer index 1).\nstruct SkinnedVertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n  @location(4) joints: vec4<u32>,\n  @location(5) weights: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) worldPos: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n};\n\n// Build a tangent basis from the geometric normal. Uses a reference vector\n// instead of screen-space derivatives (dpdx/dpdy) which can produce NaN on\n// some implementations / degenerate UVs. The tangent direction is arbitrary\n// (determined by the reference vector) but is sufficient for normal mapping\n// on meshes without explicit tangent attributes.\nfn buildTangentBasis(N: vec3<f32>, worldPos: vec4<f32>, uv: vec2<f32>) -> mat3x3<f32> {\n  var refVec = vec3<f32>(0.0, 1.0, 0.0);\n  if (abs(N.y) >= 0.99) {\n    refVec = vec3<f32>(1.0, 0.0, 0.0);\n  }\n  let T = normalize(cross(refVec, N));\n  let B = cross(N, T);\n  return mat3x3<f32>(T, B, N);\n}\n\n// Sample the normal map and perturb the geometric normal. Returns the\n// perturbed world-space normal. If the material has no normal map (normalTex\n// points at the default white texture), the sampled tangent-space normal is\n// (0.5, 0.5, 1.0) → unpacked to (0, 0, 1) → no perturbation.\nfn perturbNormal(N: vec3<f32>, worldPos: vec4<f32>, uv: vec2<f32>, normalTexHandle: u32) -> vec3<f32> {\n  let arr = unpackArrayIndex(normalTexHandle);\n  let layer = unpackLayerIndex(normalTexHandle);\n  let sampled = sampleBindlessArray(arr, uv, layer);\n  let tangentNormal = sampled.xyz * 2.0 - 1.0;\n  let basis = buildTangentBasis(N, worldPos, uv);\n  return normalize(basis * tangentNormal);\n}\n\nfn qrotate(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> {\n  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);\n}\n\n// Accumulate the 4-bone skinning matrix: sum(weights[i] * skinMatrices[joint[i]]).\n// If all weights are zero (vertex has no bone assignment), return identity so\n// the vertex renders at its baked position instead of collapsing to the origin.\nfn skinMatrix(j: vec4<u32>, w: vec4<f32>) -> mat4x4<f32> {\n  let base = uniforms.boneBase;\n  let m = skinMatrices[base + j.x] * w.x\n        + skinMatrices[base + j.y] * w.y\n        + skinMatrices[base + j.z] * w.z\n        + skinMatrices[base + j.w] * w.w;\n  let wsum = w.x + w.y + w.z + w.w;\n  if (wsum < 0.001) {\n    return mat4x4<f32>(\n      vec4(1.0, 0.0, 0.0, 0.0),\n      vec4(0.0, 1.0, 0.0, 0.0),\n      vec4(0.0, 0.0, 1.0, 0.0),\n      vec4(0.0, 0.0, 0.0, 1.0),\n    );\n  }\n  return m;\n}\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let scaled = input.position * uniforms.modelScale;\n  let rotated = qrotate(uniforms.modelRot, scaled);\n  let worldPos = rotated + uniforms.modelPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = normalize(qrotate(uniforms.modelRot, input.normal));\n  output.uv = input.uv;\n  output.color = input.color;\n  return output;\n}\n\n// Skinned vertex entry point. Applies linear blend skinning in model space\n// (skinMatrices already encode bone-world * inverseBind), then the same\n// model transform (scale/rot/pos) as vs_main.\n@vertex\nfn vs_skinned(input: SkinnedVertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let sm = skinMatrix(input.joints, input.weights);\n  let skinnedPos = (sm * vec4<f32>(input.position, 1.0)).xyz;\n  let skinnedNormal = (sm * vec4<f32>(input.normal, 0.0)).xyz;\n\n  let scaled = skinnedPos * uniforms.modelScale;\n  let rotated = qrotate(uniforms.modelRot, scaled);\n  let worldPos = rotated + uniforms.modelPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = normalize(qrotate(uniforms.modelRot, normalize(skinnedNormal)));\n  output.uv = input.uv;\n  output.color = input.color;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let geometricN = normalize(input.normal);\n\n  // Bindless material lookup (needed for normal map handle + albedo).\n  let m = bindlessMaterials[uniforms.materialIndex];\n\n  // Perturb the normal using the material's normal map (if any). Materials\n  // without a normal map use the default flat-normal texture (0.5,0.5,1.0)\n  // → unpacked to (0,0,1) → no perturbation.\n  let N = perturbNormal(geometricN, vec4<f32>(input.worldPos, 1.0), input.uv, m.normalTex);\n\n  // Decode per-prop material overrides (highlight >= 3).\n  var shaderMode = 0u;\n  var texMode = 0u;\n  if (uniforms.highlight >= 3.0) {\n    let combined = u32(uniforms.highlight) - 3u;\n    shaderMode = combined & 3u;\n    texMode = combined >> 2u;\n  }\n\n  // Colored directional sun light — matches the procedural cube/sphere shader.\n  let sunDir = normalize(frameLighting.sunDir);\n  var ndotl = max(dot(N, sunDir), 0.0);\n  // Toon shader override: quantize the sun term into discrete bands.\n  if (shaderMode == 1u) {\n    ndotl = floor(ndotl * 3.0 + 0.5) / 3.0;\n    ndotl = max(ndotl, 0.15);\n  }\n  let sunDiffuse = ndotl * frameLighting.sunColor;\n\n  // Hemisphere ambient: blend sky/ground based on normal.y (same as cube shader).\n  let hemiMix = N.y * 0.5 + 0.5;\n  let hemisphere = mix(frameLighting.groundAmbient, frameLighting.skyAmbient, hemiMix);\n  let ambient = hemisphere * frameLighting.ambientIntensity;\n\n  // Bindless albedo sample: index the material SSBO by materialIndex, then\n  // sample the texture_2d_array page/layer the material points at.\n  let arr = unpackArrayIndex(m.albedoTex);\n  let layer = unpackLayerIndex(m.albedoTex);\n  let texColor = sampleBindlessArray(arr, input.uv, layer);\n\n  // All inputs are sRGB: texture (rgba8unorm), vertex color (white), and\n  // baseColor (parser converts FBX linear DiffuseColor to sRGB). The swapchain\n  // is non-sRGB (bgra8unorm), so output sRGB directly.\n  var baseColor = texColor.rgb * input.color * m.baseColor.rgb;\n\n  // ── Texture override modes ──\n  // Wireframe: darken albedo, UV-grid lines overlaid after lighting.\n  // Checker: two-tone checkerboard over the UVs.\n  var texLine = 0.0;\n  if (texMode == 1u) {\n    let g = fract(input.uv * 6.0);\n    let lx = min(g.x, 1.0 - g.x);\n    let ly = min(g.y, 1.0 - g.y);\n    texLine = 1.0 - smoothstep(0.0, 0.08, min(lx, ly));\n    baseColor = baseColor * 0.15;\n  } else if (texMode == 2u) {\n    let cell = floor(input.uv * 8.0);\n    let check = (cell.x + cell.y) - floor((cell.x + cell.y) * 0.5) * 2.0;\n    baseColor = mix(baseColor * 0.35, baseColor * 1.4 + vec3<f32>(0.08), check);\n  }\n\n  // Channel-inspection modes — bypass lighting entirely for material review.\n  // 3 = perturbed normals (normal-map contribution visible), 4 = unlit albedo\n  // (texture/baseColor only), 5 = geometric normals (no normal map).\n  if (texMode == 3u) { return vec4<f32>(N * 0.5 + vec3<f32>(0.5), 1.0); }\n  if (texMode == 4u) { return vec4<f32>(baseColor, 1.0); }\n  if (texMode == 5u) { return vec4<f32>(geometricN * 0.5 + vec3<f32>(0.5), 1.0); }\n\n  var litColor = baseColor * (ambient + sunDiffuse);\n\n  // Point lights (up to 8). Each light is 2 vec4s: (pos.xyz, radius) + (color.rgb, intensity).\n  let plCount = frameLighting.pointLightCount;\n  for (var i = 0u; i < plCount; i++) {\n    let pl0 = frameLighting.pointLights[i * 2u];\n    let pl1 = frameLighting.pointLights[i * 2u + 1u];\n    let plPos = pl0.xyz;\n    let plRadius = pl0.w;\n    let plColor = pl1.xyz;\n    let plIntensity = pl1.w;\n    let L = plPos - input.worldPos;\n    let dist = length(L);\n    if (dist < plRadius) {\n      let atten = 1.0 / (1.0 + dist * dist / (plRadius * plRadius));\n      let ndotl_pl = max(dot(N, normalize(L)), 0.0);\n      litColor += baseColor * plColor * plIntensity * atten * ndotl_pl;\n    }\n  }\n\n  // Wireframe overlay: paint the UV-grid lines in a bright tint.\n  if (texLine > 0.0) {\n    litColor = mix(litColor, vec3<f32>(0.55, 0.95, 1.0), texLine * 0.9);\n  }\n\n  // Distance fog — anchored to the camera→model distance so it scales with\n  // the subject instead of a fixed 400m absolute (a 200m model viewed from\n  // 500m would otherwise fog to the ambient color entirely). Small models\n  // near the camera keep the original ~400m reach.\n  let modelDist = length(uniforms.cameraPos - uniforms.modelPos);\n  let fogStart = max(modelDist * 1.5, 60.0);\n  let fogEnd = max(modelDist * 4.0, 400.0);\n  let dist = length(uniforms.cameraPos - input.worldPos);\n  let fog = clamp(1.0 - (dist - fogStart) / (fogEnd - fogStart), 0.0, 1.0);\n  var outColor = mix(frameLighting.skyAmbient, litColor, fog);\n\n  // Outline shader override (shaderMode == 3): darken the body and add a\n  // bright fresnel rim so the prop reads with a bold cel edge.\n  if (shaderMode == 3u) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 3.0);\n    outColor = outColor * 0.7 + vec3<f32>(1.0, 0.95, 0.6) * smoothstep(0.35, 0.9, fresnel);\n  }\n\n  // Hologram shader override (shaderMode == 2): fresnel rim + scanline pulse\n  // tinted toward the prop's own base color. Opaque output (the pipeline has\n  // no blend state) but reads as a hologram.\n  if (shaderMode == 2u) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 2.5);\n    let pulse = 0.65 + 0.35 * sin(uniforms.time * 5.0 + input.worldPos.y * 3.0);\n    let scan = 0.5 + 0.5 * sin((input.worldPos.y + uniforms.time * 2.0) * 20.0);\n    let holoBase = baseColor * vec3<f32>(0.3, 0.9, 1.1) + vec3<f32>(0.05, 0.2, 0.25);\n    let holoRim = vec3<f32>(0.7, 1.0, 1.0);\n    var holoCol = mix(holoBase, holoRim, fresnel) * pulse;\n    holoCol = holoCol + holoRim * scan * 0.15 * fresnel;\n    return vec4<f32>(holoCol, 1.0);\n  }\n\n  // Ghost hologram override (highlight == 1): render the prop as a\n  // translucent-looking cyan shell with a fresnel rim and a vertical\n  // scanline pulse so it's visually distinct from normally-grabbed (solid)\n  // props. Opaque output (the pipeline has no blend state) but reads as a\n  // hologram. Hover outline (highlight == 2) is handled by a separate\n  // inverted-hull draw — see vs_outline / fs_outline below.\n  if (uniforms.highlight > 0.5 && uniforms.highlight < 1.5) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 2.5);\n    let pulse = 0.65 + 0.35 * sin(uniforms.time * 5.0 + input.worldPos.y * 3.0);\n    let scan = 0.5 + 0.5 * sin((input.worldPos.y + uniforms.time * 2.0) * 20.0);\n    let ghostBase = vec3<f32>(0.15, 0.75, 0.95);\n    let ghostRim = vec3<f32>(0.7, 1.0, 1.0);\n    var ghostCol = mix(ghostBase, ghostRim, fresnel) * pulse;\n    ghostCol = ghostCol + ghostRim * scan * 0.15 * fresnel;\n    return vec4<f32>(ghostCol, 1.0);\n  }\n\n  return vec4<f32>(outColor, 1.0);\n}\n\n// ── Mask entry point for post-process outline ──\n// Renders the model as solid white to a mask texture.  Uses the same\n// vertex shader as the normal render (vs_main / vs_skinned).\n@fragment\nfn fs_mask() -> @location(0) vec4f {\n  return vec4f(1.0, 1.0, 1.0, 1.0);\n}\n";
 const log = createLogger();
 export class ModelRenderer {
     device;
@@ -50,9 +50,11 @@ export class ModelRenderer {
     reusableUniforms = new Float32Array(64);
     reusableUniformsU32 = new Uint32Array(this.reusableUniforms.buffer);
     textureLoadVersion = new Map();
-    // Skinning: a shared storage buffer of bone matrices (MAX_BONES * mat4),
-    // updated per-frame via updateSkinMatrices. Bound at @group(1) for skinned
-    // draws only.
+    // Skinning: a shared storage buffer of bone matrices (mat4 each), updated
+    // per-frame via updateSkinMatrices/updateSkinMatricesFor. Bound at @group(1)
+    // for skinned draws only. Each skinned nodeId owns a region of the buffer —
+    // the draw's `boneBase` uniform selects it so multiple skinned models can be
+    // animated independently in one frame.
     skinMatrixBuffer = null;
     skinBindGroupLayout = null;
     skinBindGroup = null;
@@ -60,6 +62,16 @@ export class ModelRenderer {
     skinBindGroupSetThisFrame = false;
     /** Current bone capacity (number of mat4s the skin buffer can hold). Grows on demand. */
     boneCapacity = ModelRenderer.INITIAL_BONE_CAPACITY;
+    /** nodeId → reserved bone region (offset+count in bones). */
+    skinRegions = new Map();
+    /** nodeId → bone base index used by the skinning shader for that draw. */
+    skinBaseByNode = new Map();
+    /** Freed bone regions available for reuse (first-fit). */
+    skinFreeList = [];
+    /** Next never-allocated bone index (high-water mark). */
+    nextBoneOffset = 0;
+    /** Legacy caller region — updateSkinMatrices(m) without a nodeId. */
+    static DEFAULT_SKIN_NODE = "__skin_default";
     // Bindless deps
     bindless = null;
     bindlessLayout = null;
@@ -757,6 +769,7 @@ export class ModelRenderer {
         }
     }
     removeModel(nodeId) {
+        this.releaseSkinRegion(nodeId);
         const resources = this.modelResources.get(nodeId);
         if (resources) {
             for (let i = 0; i < resources.length; i++) {
@@ -1004,36 +1017,77 @@ export class ModelRenderer {
         return this.mipmapsEnabled;
     }
     /**
-     * Upload bone skin matrices for the current frame. The `matrices` buffer is
-     * a flat Float32Array of boneCount * 16 floats (column-major mat4s). It is
-     * copied into the shared skin matrix storage buffer. If the buffer is too
-     * small for the current skeleton, it is recreated (grown) automatically.
-     * Call once per frame before render() for skinned models.
+     * Upload bone skin matrices for the current frame into the shared default
+     * region. Kept for single-avatar callers — equivalent to
+     * updateSkinMatricesFor("__skin_default", matrices).
      */
     updateSkinMatrices(matrices) {
+        this.updateSkinMatricesFor(ModelRenderer.DEFAULT_SKIN_NODE, matrices);
+    }
+    /**
+     * Upload bone skin matrices for one nodeId's reserved region. The region is
+     * (re)allocated automatically — freed regions from removeModel() are reused
+     * first-fit. Render() looks up the node's region offset and passes it to the
+     * skinning shader via the `boneBase` uniform, so multiple skinned models
+     * animate independently.
+     */
+    updateSkinMatricesFor(nodeId, matrices) {
         if (!this.skinMatrixBuffer)
             return;
         const requiredBones = matrices.length / 16;
-        if (requiredBones > this.boneCapacity) {
-            // Grow the skin matrix buffer to fit the larger skeleton.
-            // Round up to the next power of 2 to reduce reallocations.
-            const newCapacity = Math.max(requiredBones, this.boneCapacity * 2);
-            this.skinMatrixBuffer.destroy();
-            this.skinMatrixBuffer = this.device.createBuffer({
-                size: newCapacity * 64,
-                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            });
-            this.boneCapacity = newCapacity;
-            // Recreate the bind group with the new buffer
-            if (this.skinBindGroupLayout) {
-                this.skinBindGroup = this.device.createBindGroup({
-                    layout: this.skinBindGroupLayout,
-                    entries: [{ binding: 0, resource: { buffer: this.skinMatrixBuffer } }],
-                });
+        let region = this.skinRegions.get(nodeId);
+        if (!region || region.count < requiredBones) {
+            if (region)
+                this.skinFreeList.push(region);
+            region = this.allocSkinRegion(requiredBones);
+            this.skinRegions.set(nodeId, region);
+        }
+        this.skinBaseByNode.set(nodeId, region.offset);
+        this.device.queue.writeBuffer(this.skinMatrixBuffer, region.offset * 64, matrices);
+    }
+    /** Allocate a bone region for `count` bones — free-list first, then bump
+     *  allocation; grows the shared buffer when the capacity is exceeded. */
+    allocSkinRegion(count) {
+        for (let i = 0; i < this.skinFreeList.length; i++) {
+            const f = this.skinFreeList[i];
+            if (f.count >= count) {
+                this.skinFreeList.splice(i, 1);
+                return { offset: f.offset, count: f.count };
             }
-            this.skinBindGroupSetThisFrame = false; // force re-bind
         }
-        this.device.queue.writeBuffer(this.skinMatrixBuffer, 0, matrices);
+        const needed = this.nextBoneOffset + count;
+        if (needed > this.boneCapacity)
+            this.growSkinBuffer(needed);
+        const region = { offset: this.nextBoneOffset, count };
+        this.nextBoneOffset += count;
+        return region;
+    }
+    /** Recreate the skin matrix buffer at a larger capacity and rebind group(1).
+     *  Region offsets stay valid — callers rewrite their matrices next frame. */
+    growSkinBuffer(minBones) {
+        const newCapacity = Math.max(minBones, this.boneCapacity * 2);
+        this.skinMatrixBuffer?.destroy();
+        this.skinMatrixBuffer = this.device.createBuffer({
+            size: newCapacity * 64,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.boneCapacity = newCapacity;
+        if (this.skinBindGroupLayout) {
+            this.skinBindGroup = this.device.createBindGroup({
+                layout: this.skinBindGroupLayout,
+                entries: [{ binding: 0, resource: { buffer: this.skinMatrixBuffer } }],
+            });
+        }
+        this.skinBindGroupSetThisFrame = false; // force re-bind
+    }
+    /** Release a node's bone region back to the free list. */
+    releaseSkinRegion(nodeId) {
+        const region = this.skinRegions.get(nodeId);
+        if (!region)
+            return;
+        this.skinRegions.delete(nodeId);
+        this.skinBaseByNode.delete(nodeId);
+        this.skinFreeList.push(region);
     }
     render(passEncoder, nodeId, position, rotation, scale, instanceIndex = 0, 
     /** Per-draw highlight: 0 = normal shading, 1 = ghost hologram (cyan),
@@ -1132,6 +1186,12 @@ export class ModelRenderer {
             uniforms[40] = 0.0;
             uniforms[41] = 0.0;
             uniforms[42] = 0.0;
+            // boneBase (u32, slot 44) — index of this node's bone region inside the
+            // shared skinMatrices storage buffer. Only read by vs_skinned.
+            this.reusableUniformsU32[44] =
+                this.skinBaseByNode.get(nodeId)
+                    ?? this.skinBaseByNode.get(ModelRenderer.DEFAULT_SKIN_NODE)
+                    ?? 0;
             this.device.queue.writeBuffer(this.uniformBuffer, uniformOffset, uniforms);
             // Select the skinned pipeline + skin vertex buffer for skinned meshes,
             // otherwise the standard non-skinned pipeline.

package/dist/libraries/entities/src/shaders/model.wgsl

@@ -22,6 +22,14 @@ struct Uniforms {
   // Inverted-hull outline parameters (used by vs_outline / fs_outline only).
   outlineWidth: f32,
   outlineColor: vec3<f32>,
+  // Base index of this draw's bone region inside the shared skinMatrices
+  // storage buffer (group(1)). Written by ModelRenderer from the node's
+  // reserved region — lets multiple skinned models animate independently.
+  // Only read by vs_skinned.
+  boneBase: u32,
+  _padSkin0: u32,
+  _padSkin1: u32,
+  _padSkin2: u32,
 };
 
 @group(0) @binding(0) var<uniform> uniforms: Uniforms;
@@ -165,10 +173,11 @@ fn qrotate(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> {
 // If all weights are zero (vertex has no bone assignment), return identity so
 // the vertex renders at its baked position instead of collapsing to the origin.
 fn skinMatrix(j: vec4<u32>, w: vec4<f32>) -> mat4x4<f32> {
-  let m = skinMatrices[j.x] * w.x
-        + skinMatrices[j.y] * w.y
-        + skinMatrices[j.z] * w.z
-        + skinMatrices[j.w] * w.w;
+  let base = uniforms.boneBase;
+  let m = skinMatrices[base + j.x] * w.x
+        + skinMatrices[base + j.y] * w.y
+        + skinMatrices[base + j.z] * w.z
+        + skinMatrices[base + j.w] * w.w;
   let wsum = w.x + w.y + w.z + w.w;
   if (wsum < 0.001) {
     return mat4x4<f32>(

package/dist/libraries/networking/src/index.js

@@ -14,3 +14,4 @@ export { AuthorityManager } from "./authority.js";
 // Engine library descriptor (declarative GameModule wiring)
 export { NetworkClientTok, NetworkingLib } from "./library.js";
 export { LanDiscovery, MdnsBrowser } from "./discovery.js";
+export { createWebSocketServer } from "./ws-server.js";

package/dist/libraries/networking/src/ws-server.js

@@ -0,0 +1,387 @@
+// ============================================================================
+// ws-server.ts — minimal tri-runtime WebSocket server for host-authoritative
+// LAN/WAN sessions. The networking library ships client transports
+// (WebSocketTransport, WebRTCTransport) but had no listener — this fills the
+// host side so a game instance can accept direct connections without any
+// external service.
+//
+// Runtime selection is capability-based (see platform/runtime.ts):
+//   Bun  → Bun.serve({ fetch, websocket })
+//   Deno → Deno.serve + Deno.upgradeWebSocket
+//   Node → node:http + a hand-rolled RFC6455 handshake/framer (pure JS,
+//          no native deps — also the fallback for any runtime with node:http)
+//
+// Semantics intentionally mirror the browser WebSocket surface: text frames
+// arrive as `string`, binary frames as `Uint8Array`. Ping/pong/close and
+// fragmented-frame reassembly are handled internally. Message cap matches
+// WebSocketTransport's 16 MiB.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+const log = createLogger();
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+const MAX_MESSAGE_SIZE = 16 * 1024 * 1024;
+function makeServerBase(handlers) {
+    const conns = new Set();
+    let nextId = 1;
+    const deliver = (conn, data) => {
+        const size = typeof data === "string" ? data.length : data.byteLength;
+        if (size > MAX_MESSAGE_SIZE) {
+            conn.close(1009, "message too large");
+            return;
+        }
+        try {
+            handlers.onMessage?.(conn, data);
+        }
+        catch (e) {
+            log.error("WsServer", `onMessage threw: ${e}`);
+        }
+    };
+    const drop = (conn, code, reason) => {
+        if (!conns.delete(conn))
+            return;
+        try {
+            handlers.onClose?.(conn, code, reason);
+        }
+        catch (e) {
+            log.error("WsServer", `onClose threw: ${e}`);
+        }
+    };
+    return { conns, nextId: () => nextId++, deliver, drop };
+}
+// ---------------------------------------------------------------------------
+// Bun — Bun.serve with the `websocket` handler map
+// ---------------------------------------------------------------------------
+function startBunServer(opts) {
+    const Bun = globalThis.Bun;
+    const base = makeServerBase(opts);
+    const server = Bun.serve({
+        port: opts.port,
+        hostname: opts.host ?? "0.0.0.0",
+        fetch(req, srv) {
+            const ip = srv.requestIP(req);
+            const conn = {
+                id: base.nextId(),
+                remoteAddress: `${ip?.address ?? "?"}:${ip?.port ?? "?"}`,
+                raw: null,
+                send(data) { if (this.raw)
+                    this.raw.send(data instanceof ArrayBuffer ? new Uint8Array(data) : data); },
+                close(code = 1000, reason = "") { if (this.raw)
+                    this.raw.close(code, reason); },
+            };
+            return srv.upgrade(req, { data: { conn } }) ? undefined : new Response("WebSocket upgrade required", { status: 426 });
+        },
+        websocket: {
+            open(ws) {
+                const conn = ws.data.conn;
+                conn.raw = ws;
+                base.conns.add(conn);
+                try {
+                    opts.onConnection?.(conn);
+                }
+                catch (e) {
+                    log.error("WsServer", `onConnection threw: ${e}`);
+                }
+            },
+            message(ws, msg) {
+                const conn = ws.data.conn;
+                base.deliver(conn, typeof msg === "string" ? msg : new Uint8Array(msg));
+            },
+            close(ws, code, reason) {
+                base.drop(ws.data.conn, code, reason);
+            },
+        },
+    });
+    return Promise.resolve({
+        port: server.port,
+        host: opts.host ?? "0.0.0.0",
+        connections: () => [...base.conns],
+        async close() {
+            [...base.conns].forEach((c) => c.close(1001, "server shutdown"));
+            await server.stop(true);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Deno — Deno.serve + Deno.upgradeWebSocket
+// ---------------------------------------------------------------------------
+function startDenoServer(opts) {
+    const Deno = globalThis.Deno;
+    const base = makeServerBase(opts);
+    const server = Deno.serve({ port: opts.port, hostname: opts.host ?? "0.0.0.0" }, (req, info) => {
+        if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+            return new Response("WebSocket upgrade required", { status: 426 });
+        }
+        const { socket, response } = Deno.upgradeWebSocket(req);
+        const conn = {
+            id: base.nextId(),
+            remoteAddress: info?.remoteAddr ? `${info.remoteAddr.hostname}:${info.remoteAddr.port}` : "?",
+            raw: socket,
+            send(data) { try {
+                socket.send(data);
+            }
+            catch { /* closing */ } },
+            close(code = 1000, reason = "") { try {
+                socket.close(code, reason);
+            }
+            catch { /* already closed */ } },
+        };
+        socket.binaryType = "arraybuffer";
+        socket.onopen = () => {
+            base.conns.add(conn);
+            try {
+                opts.onConnection?.(conn);
+            }
+            catch (e) {
+                log.error("WsServer", `onConnection threw: ${e}`);
+            }
+        };
+        socket.onmessage = (e) => {
+            base.deliver(conn, typeof e.data === "string" ? e.data : new Uint8Array(e.data));
+        };
+        socket.onclose = (e) => base.drop(conn, e.code, e.reason);
+        socket.onerror = () => base.drop(conn, 1006, "socket error");
+        return response;
+    });
+    const bound = server.addr;
+    return Promise.resolve({
+        port: bound.port,
+        host: bound.hostname,
+        connections: () => [...base.conns],
+        async close() {
+            [...base.conns].forEach((c) => c.close(1001, "server shutdown"));
+            await server.shutdown();
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Node (and generic fallback) — node:http + hand-rolled RFC6455
+// ---------------------------------------------------------------------------
+/** Encode one server→client frame. Server frames are never masked. */
+function encodeWsFrame(opcode, payload) {
+    const len = payload.byteLength;
+    let header;
+    if (len < 126) {
+        header = new Uint8Array(2);
+        header[1] = len;
+    }
+    else if (len <= 0xffff) {
+        header = new Uint8Array(4);
+        header[1] = 126;
+        header[2] = len >>> 8;
+        header[3] = len & 0xff;
+    }
+    else {
+        header = new Uint8Array(10);
+        header[1] = 127;
+        const dv = new DataView(header.buffer);
+        dv.setUint32(2, Math.floor(len / 0x100000000));
+        dv.setUint32(6, len >>> 0);
+    }
+    header[0] = 0x80 | (opcode & 0x0f);
+    const out = new Uint8Array(header.length + len);
+    out.set(header, 0);
+    out.set(payload, header.length);
+    return out;
+}
+const OP_CONT = 0x0, OP_TEXT = 0x1, OP_BIN = 0x2, OP_CLOSE = 0x8, OP_PING = 0x9, OP_PONG = 0xa;
+async function startNodeServer(opts) {
+    const http = await import("node:http");
+    const crypto = await import("node:crypto");
+    const base = makeServerBase(opts);
+    const httpServer = http.createServer((_req, res) => {
+        res.writeHead(426, { "Content-Type": "text/plain" });
+        res.end("WebSocket upgrade required");
+    });
+    httpServer.on("upgrade", (req, socket) => {
+        socket.setNoDelay(true);
+        const key = req.headers["sec-websocket-key"];
+        const upgrade = req.headers.upgrade?.toLowerCase();
+        if (upgrade !== "websocket" || typeof key !== "string") {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const accept = crypto.createHash("sha1").update(key + WS_GUID).digest("base64");
+        socket.write("HTTP/1.1 101 Switching Protocols\r\n" +
+            "Upgrade: websocket\r\n" +
+            "Connection: Upgrade\r\n" +
+            `Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
+        let closed = false;
+        const conn = {
+            id: base.nextId(),
+            remoteAddress: `${socket.remoteAddress ?? "?"}:${socket.remotePort ?? "?"}`,
+            raw: socket,
+            send(data) {
+                if (closed || socket.destroyed)
+                    return;
+                if (typeof data === "string") {
+                    socket.write(Buffer.from(encodeWsFrame(OP_TEXT, Buffer.from(data, "utf8"))));
+                }
+                else {
+                    const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+                    socket.write(Buffer.from(encodeWsFrame(OP_BIN, bytes)));
+                }
+            },
+            close(code = 1000, reason = "") {
+                if (closed)
+                    return;
+                closed = true;
+                const payload = new Uint8Array(2 + reason.length);
+                payload[0] = code >>> 8;
+                payload[1] = code & 0xff;
+                payload.set(new TextEncoder().encode(reason), 2);
+                try {
+                    socket.write(Buffer.from(encodeWsFrame(OP_CLOSE, payload)));
+                    socket.end();
+                }
+                catch { /* socket already gone */ }
+            },
+        };
+        // ── Incremental frame parser ──
+        let buf = Buffer.alloc(0);
+        let fragOp = -1;
+        const frags = [];
+        const finishMessage = (op, payload) => {
+            if (payload.byteLength > MAX_MESSAGE_SIZE) {
+                conn.close(1009, "message too large");
+                return;
+            }
+            if (op === OP_TEXT)
+                base.deliver(conn, payload.toString("utf8"));
+            else
+                base.deliver(conn, new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength));
+        };
+        const handleFrame = (fin, op, payload) => {
+            if (op === OP_CLOSE) {
+                const code = payload.byteLength >= 2 ? payload.readUInt16BE(0) : 1000;
+                const reason = payload.byteLength > 2 ? payload.subarray(2).toString("utf8") : "";
+                conn.close(code, reason);
+                base.drop(conn, code, reason);
+                return;
+            }
+            if (op === OP_PING) {
+                if (!closed && !socket.destroyed)
+                    socket.write(Buffer.from(encodeWsFrame(OP_PONG, payload)));
+                return;
+            }
+            if (op === OP_PONG)
+                return;
+            if (op === OP_CONT && fragOp < 0) {
+                conn.close(1002, "unexpected continuation");
+                return;
+            }
+            if ((op === OP_TEXT || op === OP_BIN) && fragOp >= 0) {
+                conn.close(1002, "interleaved frame");
+                return;
+            }
+            if (op !== OP_CONT)
+                fragOp = op;
+            frags.push(payload);
+            if (!fin)
+                return;
+            const full = Buffer.concat(frags);
+            frags.length = 0;
+            const finalOp = fragOp;
+            fragOp = -1;
+            finishMessage(finalOp, full);
+        };
+        socket.on("data", (chunk) => {
+            buf = buf.byteLength ? Buffer.concat([buf, chunk]) : chunk;
+            // Parse as many complete frames as the buffer holds.
+            for (;;) {
+                if (buf.byteLength < 2)
+                    return;
+                const b0 = buf[0], b1 = buf[1];
+                const fin = (b0 & 0x80) !== 0;
+                const op = b0 & 0x0f;
+                const masked = (b1 & 0x80) !== 0;
+                let len = b1 & 0x7f;
+                let off = 2;
+                if (len === 126) {
+                    if (buf.byteLength < off + 2)
+                        return;
+                    len = buf.readUInt16BE(off);
+                    off += 2;
+                }
+                else if (len === 127) {
+                    if (buf.byteLength < off + 8)
+                        return;
+                    const hi = buf.readUInt32BE(off), lo = buf.readUInt32BE(off + 4);
+                    off += 8;
+                    if (hi > 0 || lo > MAX_MESSAGE_SIZE) {
+                        conn.close(1009, "message too large");
+                        return;
+                    }
+                    len = lo;
+                }
+                const maskLen = masked ? 4 : 0;
+                if (buf.byteLength < off + maskLen + len)
+                    return;
+                let payload = buf.subarray(off + maskLen, off + maskLen + len);
+                if (masked) {
+                    const mask = buf.subarray(off, off + 4);
+                    const unmasked = Buffer.allocUnsafe(payload.byteLength);
+                    for (let i = 0; i < payload.byteLength; i++)
+                        unmasked[i] = payload[i] ^ mask[i & 3];
+                    payload = unmasked;
+                }
+                else {
+                    payload = Buffer.from(payload); // detach — subarray aliases buf
+                }
+                buf = buf.subarray(off + maskLen + len);
+                handleFrame(fin, op, payload);
+                if (closed)
+                    return;
+            }
+        });
+        const onSocketEnd = () => base.drop(conn, 1006, "socket closed");
+        socket.on("close", onSocketEnd);
+        socket.on("error", onSocketEnd);
+        base.conns.add(conn);
+        try {
+            opts.onConnection?.(conn);
+        }
+        catch (e) {
+            log.error("WsServer", `onConnection threw: ${e}`);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(opts.port, opts.host ?? "0.0.0.0", () => {
+            httpServer.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const addr = httpServer.address();
+    const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
+    return {
+        port: boundPort,
+        host: opts.host ?? "0.0.0.0",
+        connections: () => [...base.conns],
+        async close() {
+            [...base.conns].forEach((c) => c.close(1001, "server shutdown"));
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+            // httpServer.close waits for open sockets; force-destroy stragglers.
+            [...base.conns].forEach((c) => c.raw.destroy());
+            base.conns.clear();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Start a WebSocket server. Resolves once the socket is bound and listening.
+ * Runtime is picked by capability: Bun.serve → Deno.serve → node:http.
+ */
+export function createWebSocketServer(opts) {
+    const g = globalThis;
+    const bun = g.Bun;
+    if (typeof bun?.serve === "function")
+        return startBunServer(opts);
+    const deno = g.Deno;
+    if (typeof deno?.serve === "function" && typeof deno.upgradeWebSocket === "function") {
+        return startDenoServer(opts);
+    }
+    return startNodeServer(opts);
+}