A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(import): an FBX material takes its alpha from its base colour, and .DoubleSided draws both sides
esengine0baa9cfd025f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 66020ccbc..57f8fa2d5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -29,6 +29,7 @@ published separately; it ships inside the editor.- Web exports pack their small local assets — meshes, materials, KTX2 textures, timelines and animation assets — into a few `packs/*.pack` files, one request each, and the runtime reads each asset out of its pack. A browser holds six connections to a site, so a scene of thousands of small files loaded at the pace of its requests: Bistro's 1505 meshes took 43 s of load time for 0.2 s of upload. Its first frame on a Windows machine went from 15.2 s to 7.3 s, pixel for pixel the same. An export with hot update configured keeps one file per asset, since an update downloads assets one by one; an update that meets a packed asset refuses it by name.- Importing a model converts its DDS textures to PNG — BC1 to BC5 and uncompressed, whether the file sits beside the model or inside an FBX — so a model shipped with DDS art arrives with every map instead of references nothing can load. BC5 normal maps get their Z rebuilt; BC6H and BC7 are named and skipped.- An FBX model's specular map can be read as packed occlusion, roughness and metalness (Specular Map → Packed ORM in its import settings, `--specular-map orm` on the command line), the way scenes authored for Falcor such as Bistro store it. Read as a colour, as before, it has no slot in metal/rough shading and is left out.+- An FBX material takes its alpha from its base colour image, since FBX has no alpha mode: an image that is mostly clear where it is not solid imports as a cutout (alpha test 0.5), one that is mostly in between as blended, and one without a real alpha channel stays opaque. A material whose name ends in `.DoubleSided`, as Lumberyard-era exports such as Bistro mark it, draws both sides. Bistro's trees were leaf cards drawn opaque and one-sided — black squares with a few leaves on them.- A model import says when a map's pixels contradict its slot: an occlusion map that is zero in every texel is left out with a warning, since it would take all ambient light from the surface, and a map that is one colour throughout is noted.- **Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project's settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent's `export_game` build the same one, and the size history records which profile a build used.diff --git a/pipeline/src/assets/fbxImport.ts b/pipeline/src/assets/fbxImport.tsindex 96eb985ee..a72cbf08b 100644--- a/pipeline/src/assets/fbxImport.ts+++ b/pipeline/src/assets/fbxImport.ts@@ -354,7 +354,8 @@ function readMaterial(ctx: TextureContext, source: FbxMaterial, index: number):// FBX has no alpha mode: a material is transparent when it says it is// less than fully opaque, and opaque otherwise.opaque: opacity >= 1,- cullBackfaces: !source.twoSided,+ // Lumberyard-era exports (Bistro) say double-sided in the material's name.+ cullBackfaces: !source.twoSided && !/\.DoubleSided$/.test(source.name),...(baseTexture ? { baseColorTexture: baseTexture } : {}),...(normalTexture ? { normalTexture } : {}),...(emits ? { emissive } : {}),diff --git a/pipeline/src/assets/modelImages.ts b/pipeline/src/assets/modelImages.tsindex 8603e2426..c8c72dbe7 100644--- a/pipeline/src/assets/modelImages.ts+++ b/pipeline/src/assets/modelImages.ts@@ -23,6 +23,26 @@ interface Pixels { width: number; height: number; rgba: Uint8Array }/** Above this many texels a single colour is worth saying: the file costs what a constant would not. */const CONSTANT_NOTICE_TEXELS = 16;+/** A share of see-through texels below this is compression noise, not an alpha channel. */+const ALPHA_USED_SHARE = 0.005;++/**+ * What a base colour's alpha says the surface is. Mostly clear where it is not+ * solid is a cutout (a leaf card); mostly in between is a see-through surface+ * (glass). Clear below 16, solid from 240.+ */+function alphaUse(p: Pixels): 'opaque' | 'cutout' | 'blend' {+ let clear = 0, partial = 0;+ for (let i = 3; i < p.rgba.length; i += 4) {+ const a = p.rgba[i]!;+ if (a < 16) clear++;+ else if (a < 240) partial++;+ }+ const texels = p.width * p.height;+ if ((clear + partial) / texels < ALPHA_USED_SHARE) return 'opaque';+ return clear >= partial ? 'cutout' : 'blend';+}+const isDdsName = (file: string): boolean => /\.dds$/i.test(file);const baseName = (file: string): string => file.split(/[\\/]/).pop() ?? file;@@ -56,7 +76,8 @@ function redIsZero(p: Pixels): boolean {* @param read Resolves an external uri the way the reader's own buffers were.*/export function prepareModelImages(result: ModelImportResult,- read?: (uri: string) => Uint8Array | null): void {+ read?: (uri: string) => Uint8Array | null,+ options: { alphaFromBaseColor?: boolean } = {}): void {const embedded = new Map(result.textures.map(t => [t.name, t]));// Per source file: its pixels and the ref it becomes, or null once it has failed.const seen = new Map<string, { pixels: Pixels | null; ref: ImportedImageRef | null }>();@@ -107,6 +128,13 @@ export function prepareModelImages(result: ModelImportResult,// The sampler settings ride the reference, not the file.material[slot] = ref.settings ? { ...converted, settings: ref.settings } : converted;if (!pixels) continue;+ // A format with no alpha mode (FBX) leaves the base colour's alpha to say it.+ if (slot === 'baseColorTexture' && options.alphaFromBaseColor+ && material.opaque && material.alphaCutoff === undefined) {+ const use = alphaUse(pixels);+ if (use === 'cutout') material.alphaCutoff = 0.5;+ if (use === 'blend') material.opaque = false;+ }if (slot === 'occlusionTexture' && redIsZero(pixels)) {// Occlusion 0 is "no ambient light reaches here": taken literally, the// surface goes black. A map that says it everywhere is a packing mistake.diff --git a/pipeline/src/assets/readModelSource.ts b/pipeline/src/assets/readModelSource.tsindex 39550e675..1857e660d 100644--- a/pipeline/src/assets/readModelSource.ts+++ b/pipeline/src/assets/readModelSource.ts@@ -47,7 +47,8 @@ export interface ModelSourceOptions {export async function readModelSource(bytes: Uint8Array, stem: string,options: ModelSourceOptions = {}): Promise<ModelImportResult> {let result: ModelImportResult;- if (extensionOf(options.filename ?? '') === '.fbx') {+ const fbx = extensionOf(options.filename ?? '') === '.fbx';+ if (fbx) {const { importFbxMeshes } = await import('./fbxImport');result = await importFbxMeshes(bytes, stem, options.filename, options.specularMap);} else {@@ -55,6 +56,6 @@ export async function readModelSource(bytes: Uint8Array, stem: string,result = await importGltfMeshes(bytes, stem, options.externalBuffers);}const { prepareModelImages } = await import('./modelImages');- prepareModelImages(result, options.externalBuffers);+ prepareModelImages(result, options.externalBuffers, { alphaFromBaseColor: fbx });return result;}diff --git a/pipeline/tests/fbx-import.test.ts b/pipeline/tests/fbx-import.test.tsindex 4e013c196..1b1b6281f 100644--- a/pipeline/tests/fbx-import.test.ts+++ b/pipeline/tests/fbx-import.test.ts@@ -127,6 +127,13 @@ describe('fbx materials', () => {expect([orm.metallic, orm.roughness, orm.occlusionStrength]).toEqual([1, 1, 1]);});+ it('draws both sides of a material its name calls .DoubleSided', async () => {+ const plain = (await importFbxMeshes(texturedTriangle(), 'tri', 'tri.fbx')).meshes[0]!.material!;+ const named = (await importFbxMeshes(texturedTriangle({ materialName: 'Leaves.DoubleSided' }), 'tri', 'tri.fbx'))+ .meshes[0]!.material!;+ expect([plain.cullBackfaces, named.cullBackfaces]).toEqual([true, false]);+ });+it('writes an .esmaterial for what a MeshRenderer cannot say', async () => {const { meshes } = await importFbxMeshes(texturedTriangle(), 'tri', 'tri.fbx');const products = materialProducts(meshes, 'tri');diff --git a/pipeline/tests/fixtures/fbxFixtures.d.mts b/pipeline/tests/fixtures/fbxFixtures.d.mtsindex 8ff06dd8e..3872d4aba 100644--- a/pipeline/tests/fixtures/fbxFixtures.d.mts+++ b/pipeline/tests/fixtures/fbxFixtures.d.mts@@ -4,7 +4,7 @@/** A red-tinted triangle under a moved node, sampling an image beside the file;* `specular` adds a second image as its specular map. */-export declare function texturedTriangle(options?: { specular?: string }): Uint8Array;+export declare function texturedTriangle(options?: { specular?: string; materialName?: string }): Uint8Array;/** Two bones and a quad bound to them, the upper bone turning 90° about Z. */export declare function skinnedBar(): Uint8Array;diff --git a/pipeline/tests/fixtures/fbxFixtures.mjs b/pipeline/tests/fixtures/fbxFixtures.mjsindex 4ff18d1d1..24df3fd25 100644--- a/pipeline/tests/fixtures/fbxFixtures.mjs+++ b/pipeline/tests/fixtures/fbxFixtures.mjs@@ -172,7 +172,7 @@ const encode = (text) => new TextEncoder().encode(text);* an image beside the FBX (and `specular` as its specular map). Its node sits at* (1,2,3) to tell geometry from placement; uvs follow FBX, (0,0) bottom left.*/-export function texturedTriangle({ specular } = {}) {+export function texturedTriangle({ specular, materialName = 'Red' } = {}) {const objects = [geometry(1000, 'tri', {vertices: [0, 0, 0, 2, 0, 0, 0, 2, 0],@@ -182,7 +182,7 @@ export function texturedTriangle({ specular } = {}) {materials: [0],}),model(2000, 'Tri', 'Mesh', { translation: [1, 2, 3] }),- material(3000, 'Red', { diffuse: [1, 0, 0], emissive: [0, 0.5, 0] }),+ material(3000, materialName, { diffuse: [1, 0, 0], emissive: [0, 0.5, 0] }),texture(4000, 'Brick', 'textures/brick.png'),...(specular ? [texture(4001, 'Spec', specular)] : []),].join('');diff --git a/pipeline/tests/model-images.test.ts b/pipeline/tests/model-images.test.tsindex de84ff990..c491e78ac 100644--- a/pipeline/tests/model-images.test.ts+++ b/pipeline/tests/model-images.test.ts@@ -71,6 +71,20 @@ describe('preparing a model\'s images', () => {expect(result.warnings).toEqual(['Spec.dds is one colour (0, 188, 0, 255) across 8x8 — a material constant would say the same']);});+ it('reads an FBX base colour\'s alpha as a cutout, a see-through surface, or nothing', () => {+ const run = (alpha: (i: number) => number, alphaFromBaseColor = true) => {+ const result = model({ baseColorTexture: { file: 'leaf.png', external: true } });+ prepareModelImages(result, () => png(i => [90, 120, 40, alpha(i)]), { alphaFromBaseColor });+ const m = result.meshes[0]!.material!;+ return { cutoff: m.alphaCutoff, opaque: m.opaque };+ };+ expect(run(i => (i % 4 === 0 ? 0 : 255))).toEqual({ cutoff: 0.5, opaque: true });+ expect(run(() => 128)).toEqual({ cutoff: undefined, opaque: false });+ expect(run(() => 255)).toEqual({ cutoff: undefined, opaque: true });+ // A glTF says its alpha mode itself; an OPAQUE one ignores the channel.+ expect(run(i => (i % 4 === 0 ? 0 : 255), false)).toEqual({ cutoff: undefined, opaque: true });+ });+it('skips a DDS it cannot read rather than referencing a file nothing loads', () => {const result = model({ normalTexture: { file: 'gone.dds', external: true } }, ['gone.dds']);prepareModelImages(result, () => null);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 043feefd4..62f4cfaf7 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -1240,6 +1240,8 @@ export const NOTED = {{ note: 'A double-sided mesh is lit on the side the camera sees' },'fix(postprocess): an effect before bloom or SSAO takes effect':{ note: 'A post-process effect placed before bloom or SSAO takes effect' },+ 'feat(import): an FBX material takes its alpha from its base colour, and .DoubleSided draws both sides':+ { note: 'An FBX material takes its alpha from its base colour image' },'fix(eht): the generator writes LF on every platform':{ internal: 'The engine header tool is a repository generator; on Windows it rewrote every generated file with CRLF, which only a contributor there ever saw.' },};