@driftengine/core 3.61.4 → 3.63.0

package/CHANGELOG.json

@@ -1,4 +1,26 @@
 [
+  {
+    "version": "3.63.0",
+    "date": "2026-09-14",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "A sprite sheet can carry a mip chain. Type baked into an atlas and drawn small was losing strokes, so a t read as an l and the same letter read differently in different words.",
+        "text": "**`mipmap` on `SpriteTextureOptions`, false by default.** A sprite sheet is usually pixel art, where a chain is memory nothing samples and a blur nobody asked for, so nothing changes for a sheet that does not ask. A glyph page is the sheet where that default is wrong, and the comment on `filter` said as much without offering a way out: it assumed a sheet that is not pixel art \"is normally drawn near its authored size, where the two filters differ by very little\".\n\nA consumer bakes one page per weight at 96 px and draws body copy at 11 to 13, which is about a **7x** minification. `linear` reads four texels out of a footprint covering dozens, so a `t` crossbar two texels tall lands on roughly a quarter of a pixel and survives or not depending on where the sample falls. A player reported it as `Step-In Uppercut` reading `Slep-In Uppercul` — and because the sample point moves with the glyph's position, the same letter survived in one word and not the next, which made the line look unevenly spaced as well as misread.\n\nNeither workaround was worth having: baking nearer the drawn size blurs the headings, because one atlas cannot serve the 8x range between body copy and a display size, and a second atlas for small text doubles the pages and the uploads and moves a sampling decision into the game where it has to be re-tuned whenever a size changes.\n\n**Measured rather than asserted.** `demo/dev/glyphMip.ts` draws one glyph twelve times at deliberately different subpixel offsets, through a plain sampler and through a chain, because the reported symptom is not missing ink but *inconsistent* ink — a build that samples well by luck passes an ink threshold and fails this. The copies' ink has a standard deviation of **0.0130** plain and **0.0020** mipmapped: **6.6x less** disagreement, and the two backends land on the same number to four decimal places. `scripts/glyph-mip-check.mjs` is that measurement as a gate, and it reddens with four failures when the chain is disabled.\n\nWith `filter: 'linear'` this is trilinear; with `filter: 'nearest'` the levels are still blended, because that is minification and `filter` is about magnification, which is the split `SurfaceTexture` already makes. Padding cells against bleed stays the caller's problem, since how much depends on how far down the sheet is ever sampled.\n\n**WebGPU has no `generateMipmap`**, so `generateMipChain` and `mipLevelCount` are public now: the per-level blit that `SurfaceTexture` has always carried is a free function rather than a private method, and `ui2d` calls it. Writing the blit a second time there would have been a second shader to keep in step, and the copy that quietly disagrees about the colour space is the one that ships. It is the first runtime import `ui2d` takes from the engine and it was measured before it was taken: bundled alone, **11,777 against 11,163 gzipped bytes**, so 614 for the blit and its shader."
+      }
+    ]
+  },
+  {
+    "version": "3.62.0",
+    "date": "2026-09-13",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "An Android build can ask for the permissions it needs. Without this an APK could not open a socket at all, and there was no way for a game to say otherwise short of vendoring three directories.",
+        "text": "**The Android manifest template declares one activity and no permissions, and that default is right**: a permission is visible in a store listing, and a packager that granted the network to every game it ever built would be asking on behalf of games that never use it. The difficulty was that a consumer had no way to depart from it. The template is copied wholesale, none of the eight `-Pdrift*` properties Gradle takes reaches the manifest, there is no `manifestPlaceholders` and no source-set overlay, and `--resources` moves the desktop shell and the iOS spec along with the Gradle project — so changing one line of one manifest meant vendoring all three.\n\nSo an online game shipped an APK whose process is not permitted to open a socket. Every connection failed, the game reported that it could not connect, and the relay logged nothing at all because no packet left the phone: the same silence at both ends, indistinguishable from a wrong address. Measured on the built artifact, `aapt2 dump permissions` printed the package name and nothing else.\n\n```json\n\"android\": { \"permissions\": [\"INTERNET\"], \"cleartextTraffic\": false }\n```\n\n`\"INTERNET\"` and `\"android.permission.INTERNET\"` are both accepted; a name that would break out of the XML attribute it is written into is refused at parse time. The elements are written into the copied Gradle project before Gradle runs, which is where the icon is already written, so nothing in the engine's own tree is touched by a consumer's build. `doctor` prints what was asked for beside the signing mode, and says `none — the APK cannot open a socket` when nothing was.\n\n**`cleartextTraffic` is the second half, and it is the one only the engine could answer.** The game is served from `https://appassets.androidplatform.net`, which is a secure context, and a WebView defaults to `MIXED_CONTENT_NEVER_ALLOW` — stricter than a browser tab, where the same insecure WebSocket connects with a deprecation warning rather than being refused, measured on Chrome 151 against a LAN address. Setting it true writes `android:usesCleartextTraffic=\"true\"` **and** is what `MainActivity` reads back through `NetworkSecurityPolicy` to allow mixed content in the WebView. One switch drives both, so the platform and the renderer cannot disagree about it, and a network security config a consumer adds later is picked up without the Java learning about it. A relay on a LAN cannot hold a certificate, which is the case it exists for; a public relay should be `wss://` and this should stay false.\n\nVerified on real APKs with `aapt2`: unchanged, the dump is the package name alone; asking, it carries both permissions and the cleartext flag. Held by twenty-nine cases, and seven mutations each redden at least one."
+      }
+    ]
+  },
   {
     "version": "3.61.4",
     "date": "2026-09-13",

package/dist/index.d.ts

@@ -64,6 +64,7 @@ export { createVisitResult, visitVisible } from './scene/visit.ts';
 export type { VisitResult } from './scene/visit.ts';
 export type { PassContext, PassDefinition, PassDevice, PassHandle, PrepareContext, } from './render/pass.ts';
 export type { PassAttachmentOptions, PassTarget } from './render/passTarget.ts';
+export { generateMipChain, mipLevelCount, type MipPipelines, } from './render/backend/webgpu/surfaceTexturePass.ts';
 export { createPassAttachment } from './render/passTarget.ts';
 export type { FrameResource } from './render/frame/index.ts';
 export type { OcclusionOptions } from './render/occlusion.ts';

package/dist/index.js

@@ -67,6 +67,17 @@ export { apparentSize, lodForBounds } from './render/lod.js';
 export { SceneNode } from './scene/node.js';
 export { MAX_JOINTS, MAX_MORPH_TARGETS, SKIN_PALETTE_TEXTURE_UNIT, morphTexelIndex, paletteTextureWidth, } from './render/skinPalette.js';
 export { createVisitResult, visitVisible } from './scene/visit.js';
+/*
+ * The mip chain a pass has to build for itself on WebGPU, and the level count it needs to ask for.
+ *
+ * **Public because `gl.generateMipmap` has no WebGPU equivalent and every contributed pass that
+ * uploads a texture meets that the moment its texture is ever minified.** `ui2d` met it with a
+ * glyph atlas baked at 96 px and drawn at 11; writing the blit a second time there would have been
+ * a second WGSL shader to keep in step with this one, and the copy that quietly disagrees about
+ * the colour space is the one that would ship. `MipPipelines` is an interface rather than the
+ * renderer's cache so a pass can hand over a `Map` and nothing more.
+ */
+export { generateMipChain, mipLevelCount, } from './render/backend/webgpu/surfaceTexturePass.js';
 export { createPassAttachment } from './render/passTarget.js';
 export { OcclusionBuffer } from './render/occlusion.js';
 /*

package/dist/render/backend/webgpu/surfaceTexturePass.d.ts

@@ -2,6 +2,34 @@ import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /** How many levels an image of this size has, counting the one it arrives with. */
 export declare function mipLevelCount(width: number, height: number): number;
+/**
+ * Somewhere to keep one pipeline per format. `PipelineCache` satisfies it; so does a `Map`.
+ *
+ * Taken as an interface rather than as the class, because the other caller of the chain below is
+ * `@driftengine/ui2d`, which builds its own pipeline from the device and has no cache of the
+ * renderer's to hand.
+ */
+export interface MipPipelines {
+    get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+}
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export declare function generateMipChain(device: GPUDevice, pipelines: MipPipelines, texture: GPUTexture, format: GPUTextureFormat, levels: number): void;
 /** An image uploaded once and bound per material. */
 export declare class GpuSurfaceTexture {
     private readonly device;
@@ -33,9 +61,4 @@ export declare class GpuSurfaceTexture {
      * an attachment and a resource at once — rejected, and rejected silently enough to matter.
      */
     private generateMips;
-    /**
-     * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting
-     * a linear chain through a pipeline declared for the other one is a gamma error per level.
-     */
-    private mipPipeline;
 }

package/dist/render/backend/webgpu/surfaceTexturePass.js

@@ -48,6 +48,75 @@ fn fragmentMain(in: Varying) -> @location(0) vec4<f32> {
 export function mipLevelCount(width, height) {
     return Math.floor(Math.log2(Math.max(width, height))) + 1;
 }
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export function generateMipChain(device, pipelines, texture, format, levels) {
+    if (levels < 2)
+        return;
+    const pipeline = mipBlitPipeline(device, pipelines, format);
+    const sampler = device.createSampler({
+        label: 'mip.sampler',
+        magFilter: 'linear',
+        minFilter: 'linear',
+    });
+    const encoder = device.createCommandEncoder({ label: 'mip.chain' });
+    for (let level = 1; level < levels; level++) {
+        const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
+        const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
+        const pass = encoder.beginRenderPass({
+            label: `mip.level${level}`,
+            colorAttachments: [
+                { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+            ],
+        });
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: source },
+                { binding: 1, resource: sampler },
+            ],
+        }));
+        pass.draw(3);
+        pass.end();
+    }
+    device.queue.submit([encoder.finish()]);
+}
+/**
+ * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting a
+ * linear chain through a pipeline declared for the other one is a gamma error per level.
+ */
+function mipBlitPipeline(device, pipelines, format) {
+    return pipelines.get(`surface.mip:${format}`, () => ({
+        label: `surface.mip:${format}`,
+        layout: 'auto',
+        vertex: {
+            module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+            entryPoint: 'vertexMain',
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+            entryPoint: 'fragmentMain',
+            targets: [{ format }],
+        },
+        primitive: { topology: 'triangle-list' },
+    }));
+}
 function sourceSize(source) {
     const candidate = source;
     const width = candidate.videoWidth ?? candidate.width ?? 0;
@@ -176,53 +245,6 @@ export class GpuSurfaceTexture {
      * an attachment and a resource at once — rejected, and rejected silently enough to matter.
      */
     generateMips(texture) {
-        const pipeline = this.mipPipeline();
-        const sampler = this.device.createSampler({
-            label: 'surface.mipSampler',
-            magFilter: 'linear',
-            minFilter: 'linear',
-        });
-        const encoder = this.device.createCommandEncoder({ label: 'surface.mips' });
-        for (let level = 1; level < this.levels; level++) {
-            const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
-            const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
-            const pass = encoder.beginRenderPass({
-                label: `surface.mip${level}`,
-                colorAttachments: [
-                    { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
-                ],
-            });
-            pass.setPipeline(pipeline);
-            pass.setBindGroup(0, this.device.createBindGroup({
-                layout: pipeline.getBindGroupLayout(0),
-                entries: [
-                    { binding: 0, resource: source },
-                    { binding: 1, resource: sampler },
-                ],
-            }));
-            pass.draw(3);
-            pass.end();
-        }
-        this.device.queue.submit([encoder.finish()]);
-    }
-    /**
-     * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting
-     * a linear chain through a pipeline declared for the other one is a gamma error per level.
-     */
-    mipPipeline() {
-        return this.pipelines.get(`surface.mip:${this.format}`, () => ({
-            label: `surface.mip:${this.format}`,
-            layout: 'auto',
-            vertex: {
-                module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
-                entryPoint: 'vertexMain',
-            },
-            fragment: {
-                module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
-                entryPoint: 'fragmentMain',
-                targets: [{ format: this.format }],
-            },
-            primitive: { topology: 'triangle-list' },
-        }));
+        generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "3.61.4",
+  "version": "3.63.0",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "3.61.4",
-    "@driftengine/physics": "3.61.4",
+    "@driftengine/drft": "3.63.0",
+    "@driftengine/physics": "3.63.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",

package/src/index.ts

@@ -158,6 +158,21 @@ export type {
  * write to the frame stays refused while a write to a pass-owned target does not is written out.
  */
 export type { PassAttachmentOptions, PassTarget } from './render/passTarget.ts';
+/*
+ * The mip chain a pass has to build for itself on WebGPU, and the level count it needs to ask for.
+ *
+ * **Public because `gl.generateMipmap` has no WebGPU equivalent and every contributed pass that
+ * uploads a texture meets that the moment its texture is ever minified.** `ui2d` met it with a
+ * glyph atlas baked at 96 px and drawn at 11; writing the blit a second time there would have been
+ * a second WGSL shader to keep in step with this one, and the copy that quietly disagrees about
+ * the colour space is the one that would ship. `MipPipelines` is an interface rather than the
+ * renderer's cache so a pass can hand over a `Map` and nothing more.
+ */
+export {
+  generateMipChain,
+  mipLevelCount,
+  type MipPipelines,
+} from './render/backend/webgpu/surfaceTexturePass.ts';
 export { createPassAttachment } from './render/passTarget.ts';
 export type { FrameResource } from './render/frame/index.ts';
 /*

package/src/render/backend/webgpu/surfaceTexturePass.ts

@@ -55,6 +55,100 @@ export function mipLevelCount(width: number, height: number): number {
   return Math.floor(Math.log2(Math.max(width, height))) + 1;
 }
 
+/**
+ * Somewhere to keep one pipeline per format. `PipelineCache` satisfies it; so does a `Map`.
+ *
+ * Taken as an interface rather than as the class, because the other caller of the chain below is
+ * `@driftengine/ui2d`, which builds its own pipeline from the device and has no cache of the
+ * renderer's to hand.
+ */
+export interface MipPipelines {
+  get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+}
+
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export function generateMipChain(
+  device: GPUDevice,
+  pipelines: MipPipelines,
+  texture: GPUTexture,
+  format: GPUTextureFormat,
+  levels: number,
+): void {
+  if (levels < 2) return;
+  const pipeline = mipBlitPipeline(device, pipelines, format);
+  const sampler = device.createSampler({
+    label: 'mip.sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+  });
+  const encoder = device.createCommandEncoder({ label: 'mip.chain' });
+  for (let level = 1; level < levels; level++) {
+    const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
+    const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
+    const pass = encoder.beginRenderPass({
+      label: `mip.level${level}`,
+      colorAttachments: [
+        { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+      ],
+    });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(
+      0,
+      device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: source },
+          { binding: 1, resource: sampler },
+        ],
+      }),
+    );
+    pass.draw(3);
+    pass.end();
+  }
+  device.queue.submit([encoder.finish()]);
+}
+
+/**
+ * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting a
+ * linear chain through a pipeline declared for the other one is a gamma error per level.
+ */
+function mipBlitPipeline(
+  device: GPUDevice,
+  pipelines: MipPipelines,
+  format: GPUTextureFormat,
+): GPURenderPipeline {
+  return pipelines.get(`surface.mip:${format}`, () => ({
+    label: `surface.mip:${format}`,
+    layout: 'auto' as const,
+    vertex: {
+      module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+      entryPoint: 'vertexMain',
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+      entryPoint: 'fragmentMain',
+      targets: [{ format }],
+    },
+    primitive: { topology: 'triangle-list' as const },
+  }));
+}
+
 function sourceSize(source: TexImageSource): { width: number; height: number } {
   const candidate = source as {
     width?: number;
@@ -201,57 +295,6 @@ export class GpuSurfaceTexture {
    * an attachment and a resource at once — rejected, and rejected silently enough to matter.
    */
   private generateMips(texture: GPUTexture): void {
-    const pipeline = this.mipPipeline();
-    const sampler = this.device.createSampler({
-      label: 'surface.mipSampler',
-      magFilter: 'linear',
-      minFilter: 'linear',
-    });
-    const encoder = this.device.createCommandEncoder({ label: 'surface.mips' });
-    for (let level = 1; level < this.levels; level++) {
-      const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
-      const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
-      const pass = encoder.beginRenderPass({
-        label: `surface.mip${level}`,
-        colorAttachments: [
-          { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
-        ],
-      });
-      pass.setPipeline(pipeline);
-      pass.setBindGroup(
-        0,
-        this.device.createBindGroup({
-          layout: pipeline.getBindGroupLayout(0),
-          entries: [
-            { binding: 0, resource: source },
-            { binding: 1, resource: sampler },
-          ],
-        }),
-      );
-      pass.draw(3);
-      pass.end();
-    }
-    this.device.queue.submit([encoder.finish()]);
-  }
-
-  /**
-   * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting
-   * a linear chain through a pipeline declared for the other one is a gamma error per level.
-   */
-  private mipPipeline(): GPURenderPipeline {
-    return this.pipelines.get(`surface.mip:${this.format}`, () => ({
-      label: `surface.mip:${this.format}`,
-      layout: 'auto' as const,
-      vertex: {
-        module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
-        entryPoint: 'vertexMain',
-      },
-      fragment: {
-        module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
-        entryPoint: 'fragmentMain',
-        targets: [{ format: this.format }],
-      },
-      primitive: { topology: 'triangle-list' as const },
-    }));
+    generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
   }
 }