Skip to content

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.

39.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import {
    Material,
    ShaderSources,
    isTextureRef,
    initMaterialAPI,
    shutdownMaterialAPI,
    CullMode,
} from '../src/render/material';
import type {
    MaterialHandle,
    ShaderHandle,
    TextureRef,
    MaterialAssetData,
} from '../src/render/material';
import type { ESEngineModule } from '../src/wasm';
import { BlendMode } from '../src/render/blend';
import { initResourceManager, shutdownResourceManager } from '../src/wasm/resourceManager';

// =============================================================================
// Mock WASM module for Material API
// =============================================================================

function createMaterialMockModule() {
    const resourceManager = {
        createShader: vi.fn().mockReturnValue(1),
        releaseShader: vi.fn(),
    };

    const mock = {
        getResourceManager: vi.fn(() => resourceManager),
        resourceManager,
        // The engine-side material store push (replaces the old pull callback + cache).
        material_compileEsshader: vi.fn().mockReturnValue(7),
        material_define: vi.fn(),
        material_setUniform: vi.fn(),
        material_setTexture: vi.fn(),
        material_undefine: vi.fn(),
    };

    return mock;
}

type MockModule = ReturnType<typeof createMaterialMockModule>;

// Render-state flags the SDK packs for material_define: depthTest (bit 0),
// depthWrite (bit 1), CullMode (bits 2-3).
function flags(depthTest: boolean, depthWrite: boolean, cull: CullMode): number {
    return (depthTest ? 0x1 : 0) | (depthWrite ? 0x2 : 0) | ((cull & 0x3) << 2);
}

// =============================================================================
// Tests
// =============================================================================

describe('Material API', () => {
    let mock: MockModule;

    beforeEach(() => {
        mock = createMaterialMockModule();
        initResourceManager(mock.resourceManager as any);
        initMaterialAPI(mock as unknown as ESEngineModule);
    });

    afterEach(() => {
        shutdownMaterialAPI();
        shutdownResourceManager();
    });

    describe('complete material state projection', () => {
        it('removes local overrides and keeps inheriting subsequent parent changes', () => {
            const parent = Material.create({shader:1,uniforms:{u_value:3},blendMode:BlendMode.Additive});
            const child = Material.createInstance(parent);
            Material.applyState(child,{uniforms:{u_value:9},blendMode:BlendMode.Multiply});
            Material.applyState(child,{});
            expect(Material.getUniform(child,'u_value')).toBe(3);
            expect(Material.getBlendMode(child)).toBe(BlendMode.Additive);
            expect(Material.get(child)!.uniforms.size).toBe(0);
            expect(Material.get(child)!.overrides.size).toBe(0);
            Material.setUniform(parent,'u_value',7);
            expect(Material.getUniform(child,'u_value')).toBe(7);
        });
        it('clears removed GPU values only where no inherited override replaces them', () => {
            const parent = Material.create({shader:1,uniforms:{u_value:3}});
            const inheriting = Material.createInstance(parent), overriding = Material.createInstance(parent);
            Material.setUniform(overriding,'u_value',9);mock.material_undefine.mockClear();
            Material.applyState(parent,{});
            expect(mock.material_undefine.mock.calls.map(call=>call[0])).toEqual([parent,inheriting]);
            expect(Material.getUniform(overriding,'u_value')).toBe(9);
            expect(Material.getUniform(inheriting,'u_value')).toBeUndefined();
        });
        it('flushes one complete snapshot per affected material instead of once per field', () => {
            const parent=Material.create({shader:1}),child=Material.createInstance(parent);
            mock.material_define.mockClear();mock.material_setUniform.mockClear();
            const uniforms=Object.fromEntries(Array.from({length:8},(_,i)=>[`p${i}`,i]));
            Material.applyState(parent,{uniforms,blendMode:BlendMode.Additive,depthTest:true,depthWrite:false,cull:CullMode.Back,depthBias:2});
            expect(mock.material_define).toHaveBeenCalledTimes(2);
            expect(mock.material_setUniform).toHaveBeenCalledTimes(16);
            expect(mock.material_define).toHaveBeenCalledWith(child,1,BlendMode.Additive,flags(true,false,CullMode.Back),2);
        });
    });

    // =========================================================================
    // shutdownMaterialAPI
    // =========================================================================

    describe('shutdownMaterialAPI', () => {
        it('should clear materials map', () => {
            const mat = Material.create({ shader: 1 as ShaderHandle });
            shutdownMaterialAPI();
            expect(Material.isValid(mat)).toBe(false);
        });

        it('should reset nextMaterialId to 1', () => {
            Material.create({ shader: 1 as ShaderHandle });
            Material.create({ shader: 1 as ShaderHandle });
            shutdownMaterialAPI();

            // Re-init to verify ID reset
            mock = createMaterialMockModule();
            initMaterialAPI(mock as unknown as ESEngineModule);
            const handle = Material.create({ shader: 1 as ShaderHandle });
            expect(handle).toBe(1);
        });

        it('should handle double shutdown gracefully', () => {
            shutdownMaterialAPI();
            expect(() => shutdownMaterialAPI()).not.toThrow();
        });
    });

    // =========================================================================
    // Shader create/release
    // =========================================================================

    describe('Material.createShader', () => {
        it('should proxy to resourceManager.createShader', () => {
            const handle = Material.createShader('vert', 'frag');
            expect(handle).toBe(1);
            expect(mock.resourceManager.createShader).toHaveBeenCalledWith('vert', 'frag');
        });
    });

    describe('Material.releaseShader', () => {
        it('should proxy to resourceManager.releaseShader for valid handle', () => {
            Material.releaseShader(5 as ShaderHandle);
            expect(mock.resourceManager.releaseShader).toHaveBeenCalledWith(5);
        });

        it('should skip release for handle <= 0', () => {
            Material.releaseShader(0 as ShaderHandle);
            Material.releaseShader(-1 as ShaderHandle);
            expect(mock.resourceManager.releaseShader).not.toHaveBeenCalled();
        });
    });

    // =========================================================================
    // Material CRUD
    // =========================================================================

    describe('Material.create', () => {
        it('should return incrementing handles starting from 1', () => {
            // Handle 1 was already consumed by some tests; re-init
            shutdownMaterialAPI();
            mock = createMaterialMockModule();
            initMaterialAPI(mock as unknown as ESEngineModule);

            const h1 = Material.create({ shader: 1 as ShaderHandle });
            const h2 = Material.create({ shader: 1 as ShaderHandle });
            const h3 = Material.create({ shader: 1 as ShaderHandle });
            expect(h1).toBe(1);
            expect(h2).toBe(2);
            expect(h3).toBe(3);
        });

        it('should store material with default values', () => {
            const h = Material.create({ shader: 42 as ShaderHandle });
            const data = Material.get(h);
            expect(data).toBeDefined();
            expect(data!.shader).toBe(42);
            expect(data!.blendMode).toBe(BlendMode.Normal);
            expect(data!.depthTest).toBe(false);
            expect(data!.depthWrite).toBe(true);
            expect(data!.cull).toBe(CullMode.None);
            expect(data!.uniforms.size).toBe(0);
        });

        it('should push the resolved render state to the engine store', () => {
            const h = Material.create({
                shader: 42 as ShaderHandle,
                blendMode: BlendMode.Additive,
                depthTest: true,
                cull: CullMode.Back,
            });
            expect(mock.material_define).toHaveBeenCalledWith(
                h, 42, BlendMode.Additive, flags(true, true, CullMode.Back), 0,
            );
        });

        it('should accept optional uniforms', () => {
            const h = Material.create({
                shader: 1 as ShaderHandle,
                uniforms: { u_time: 0.5, u_color: { x: 1, y: 0, z: 0, w: 1 } },
            });
            const data = Material.get(h);
            expect(data!.uniforms.size).toBe(2);
            expect(data!.uniforms.get('u_time')).toBe(0.5);
        });

        it('should accept custom blendMode and depthTest', () => {
            const h = Material.create({
                shader: 1 as ShaderHandle,
                blendMode: BlendMode.Additive,
                depthTest: true,
            });
            const data = Material.get(h);
            expect(data!.blendMode).toBe(BlendMode.Additive);
            expect(data!.depthTest).toBe(true);
        });
    });

    describe('Material.get', () => {
        it('should return material data for valid handle', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            expect(Material.get(h)).toBeDefined();
        });

        it('should return undefined for invalid handle', () => {
            expect(Material.get(999 as MaterialHandle)).toBeUndefined();
        });
    });

    describe('Material.isValid', () => {
        it('should return true for existing material', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            expect(Material.isValid(h)).toBe(true);
        });

        it('should return false for non-existing material', () => {
            expect(Material.isValid(999 as MaterialHandle)).toBe(false);
        });

        it('should return false after release', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            Material.release(h);
            expect(Material.isValid(h)).toBe(false);
        });
    });

    describe('Material.release', () => {
        it('should delete material and undefine it in the engine store', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            Material.release(h);
            expect(Material.isValid(h)).toBe(false);
            expect(mock.material_undefine).toHaveBeenCalledWith(h);
        });
    });

    describe('Material.releaseAll', () => {
        it('should clear all materials and undefine each in the engine store', () => {
            const h1 = Material.create({ shader: 1 as ShaderHandle });
            const h2 = Material.create({ shader: 1 as ShaderHandle });
            Material.releaseAll();
            expect(Material.isValid(h1)).toBe(false);
            expect(Material.isValid(h2)).toBe(false);
            expect(mock.material_undefine).toHaveBeenCalledWith(h1);
            expect(mock.material_undefine).toHaveBeenCalledWith(h2);
        });
    });

    // =========================================================================
    // Uniform management
    // =========================================================================

    describe('Uniform management', () => {
        it('should set and get uniform value', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            Material.setUniform(h, 'u_time', 3.14);
            expect(Material.getUniform(h, 'u_time')).toBe(3.14);
        });

        it('should return undefined for non-existing uniform', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            expect(Material.getUniform(h, 'nonexistent')).toBeUndefined();
        });

        it('should return undefined for invalid material handle', () => {
            expect(Material.getUniform(999 as MaterialHandle, 'u_val')).toBeUndefined();
        });

        it('should not throw when setting uniform on invalid handle', () => {
            expect(() => Material.setUniform(999 as MaterialHandle, 'u_val', 1.0)).not.toThrow();
        });
    });

    describe('Material.getUniforms', () => {
        it('should return a copy of uniforms map', () => {
            const h = Material.create({
                shader: 1 as ShaderHandle,
                uniforms: { u_a: 1, u_b: 2 },
            });
            const uniformsCopy = Material.getUniforms(h);
            expect(uniformsCopy.size).toBe(2);
            expect(uniformsCopy.get('u_a')).toBe(1);

            // Modifying copy should not affect original
            uniformsCopy.set('u_c', 3);
            expect(Material.getUniforms(h).size).toBe(2);
        });

        it('should return empty map for invalid handle', () => {
            const uniforms = Material.getUniforms(999 as MaterialHandle);
            expect(uniforms.size).toBe(0);
        });
    });

    // =========================================================================
    // BlendMode / DepthTest / DepthWrite / Cull / Shader
    // =========================================================================

    describe('BlendMode', () => {
        it('should set and get blend mode', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            Material.setBlendMode(h, BlendMode.Multiply);
            expect(Material.getBlendMode(h)).toBe(BlendMode.Multiply);
        });

        it('should push the new state on setBlendMode', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_define.mockClear();
            Material.setBlendMode(h, BlendMode.Additive);
            expect(mock.material_define).toHaveBeenCalledWith(
                h, 1, BlendMode.Additive, flags(false, true, CullMode.None), 0,
            );
        });

        it('should return Normal for invalid handle', () => {
            expect(Material.getBlendMode(999 as MaterialHandle)).toBe(BlendMode.Normal);
        });
    });

    describe('DepthTest / DepthWrite / Cull', () => {
        it('should set depth test and push state', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_define.mockClear();
            Material.setDepthTest(h, true);
            expect(Material.get(h)!.depthTest).toBe(true);
            expect(mock.material_define).toHaveBeenCalledWith(
                h, 1, BlendMode.Normal, flags(true, true, CullMode.None), 0,
            );
        });

        it('should set depth write and push state', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_define.mockClear();
            Material.setDepthWrite(h, false);
            expect(Material.get(h)!.depthWrite).toBe(false);
            expect(mock.material_define).toHaveBeenCalledWith(
                h, 1, BlendMode.Normal, flags(false, false, CullMode.None), 0,
            );
        });

        it('carries a depth bias through to the engine, as its own value', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_define.mockClear();
            Material.setDepthBias(h, -8);
            // Its own argument and not a bit in `flags`: a value packed into a
            // word of switches is how the two sides come to disagree about it.
            expect(mock.material_define).toHaveBeenCalledWith(
                h, 1, BlendMode.Normal, flags(false, true, CullMode.None), -8,
            );
            expect(Material.get(h)?.depthBias).toBe(-8);
        });

        it('rounds a bias to whole depth-buffer units', () => {
            const h = Material.create({ shader: 1 as ShaderHandle, depthBias: -2.6 });
            expect(Material.get(h)?.depthBias).toBe(-2.6);
            Material.setDepthBias(h, -2.6);
            expect(Material.get(h)?.depthBias).toBe(-3);
        });

        it('lets an instance override its parent bias, and inherit it otherwise', () => {
            const base = Material.create({ shader: 1 as ShaderHandle, depthBias: -4 });
            const inherits = Material.createInstance(base);
            const overrides = Material.createInstance(base);
            mock.material_define.mockClear();
            Material.setDepthBias(overrides, -16);

            expect(mock.material_define).toHaveBeenCalledWith(
                overrides, 1, BlendMode.Normal, flags(false, true, CullMode.None), -16,
            );
            mock.material_define.mockClear();
            Material.setDepthBias(base, -9);
            // The non-overriding child follows its parent; the overriding one does not.
            expect(mock.material_define).toHaveBeenCalledWith(
                inherits, 1, BlendMode.Normal, flags(false, true, CullMode.None), -9,
            );
            expect(mock.material_define).toHaveBeenCalledWith(
                overrides, 1, BlendMode.Normal, flags(false, true, CullMode.None), -16,
            );
        });

        it('should set cull mode and push state', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_define.mockClear();
            Material.setCull(h, CullMode.Front);
            expect(Material.get(h)!.cull).toBe(CullMode.Front);
            expect(mock.material_define).toHaveBeenCalledWith(
                h, 1, BlendMode.Normal, flags(false, true, CullMode.Front), 0,
            );
        });
    });

    describe('Material.getShader', () => {
        it('should return shader handle', () => {
            const h = Material.create({ shader: 42 as ShaderHandle });
            expect(Material.getShader(h)).toBe(42);
        });

        it('should return 0 for invalid handle', () => {
            expect(Material.getShader(999 as MaterialHandle)).toBe(0);
        });
    });

    // =========================================================================
    // createFromAsset
    // =========================================================================

    describe('Material.createFromAsset', () => {
        const baseAsset = (extra: Partial<MaterialAssetData>): MaterialAssetData => ({
            version: '1.0',
            type: 'material',
            shader: 'test.shader',
            blendMode: BlendMode.Normal,
            depthTest: false,
            properties: {},
            ...extra,
        });

        it('should parse number properties', () => {
            const h = Material.createFromAsset(baseAsset({ properties: { u_intensity: 0.75 } }), 10 as ShaderHandle);
            expect(Material.getUniform(h, 'u_intensity')).toBe(0.75);
        });

        it('should parse Color (with "a" key) as Vec4', () => {
            const h = Material.createFromAsset(
                baseAsset({ properties: { u_color: { r: 1, g: 0.5, b: 0.25, a: 1 } } }), 10 as ShaderHandle);
            const val = Material.getUniform(h, 'u_color') as { x: number; y: number; z: number; w: number };
            expect(val).toEqual({ x: 1, y: 0.5, z: 0.25, w: 1 });
        });

        it('should parse Vec4 (with "w" key)', () => {
            const h = Material.createFromAsset(
                baseAsset({ properties: { u_rect: { x: 0, y: 1, z: 2, w: 3 } } }), 10 as ShaderHandle);
            const val = Material.getUniform(h, 'u_rect') as { x: number; y: number; z: number; w: number };
            expect(val).toEqual({ x: 0, y: 1, z: 2, w: 3 });
        });

        it('should parse Vec3 (with "z" key)', () => {
            const h = Material.createFromAsset(
                baseAsset({ properties: { u_pos: { x: 1, y: 2, z: 3 } } }), 10 as ShaderHandle);
            const val = Material.getUniform(h, 'u_pos') as { x: number; y: number; z: number };
            expect(val).toEqual({ x: 1, y: 2, z: 3 });
        });

        it('should parse Vec2 (with "y" key)', () => {
            const h = Material.createFromAsset(
                baseAsset({ properties: { u_offset: { x: 5, y: 10 } } }), 10 as ShaderHandle);
            const val = Material.getUniform(h, 'u_offset') as { x: number; y: number };
            expect(val).toEqual({ x: 5, y: 10 });
        });

        it('should use blendMode, depthTest, depthWrite and cull from asset data', () => {
            const h = Material.createFromAsset(
                baseAsset({ blendMode: BlendMode.Screen, depthTest: true, depthWrite: false, cull: CullMode.Back }),
                10 as ShaderHandle);
            expect(Material.getBlendMode(h)).toBe(BlendMode.Screen);
            const data = Material.get(h)!;
            expect(data.depthTest).toBe(true);
            expect(data.depthWrite).toBe(false);
            expect(data.cull).toBe(CullMode.Back);
        });

        it('should default depthWrite/cull when absent from asset data', () => {
            const h = Material.createFromAsset(baseAsset({}), 10 as ShaderHandle);
            const data = Material.get(h)!;
            expect(data.depthWrite).toBe(true);
            expect(data.cull).toBe(CullMode.None);
        });

        it('should use provided shaderHandle', () => {
            const h = Material.createFromAsset(baseAsset({}), 77 as ShaderHandle);
            expect(Material.getShader(h)).toBe(77);
        });
    });

    // =========================================================================
    // createInstance
    // =========================================================================

    describe('Material.createInstance', () => {
        it('should inherit shader, uniforms, blendMode, depthTest from the parent', () => {
            const src = Material.create({
                shader: 42 as ShaderHandle,
                uniforms: { u_time: 1.5 },
                blendMode: BlendMode.Additive,
                depthTest: true,
            });
            const inst = Material.createInstance(src);

            expect(Material.getShader(inst)).toBe(42);
            expect(Material.getUniform(inst, 'u_time')).toBe(1.5);
            expect(Material.getBlendMode(inst)).toBe(BlendMode.Additive);
        });

        it('should push the flattened (inherited) instance to the engine store', () => {
            const src = Material.create({ shader: 5 as ShaderHandle, blendMode: BlendMode.Multiply });
            mock.material_define.mockClear();
            const inst = Material.createInstance(src);
            expect(mock.material_define).toHaveBeenCalledWith(
                inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None), 0,
            );
        });

        it('an instance override does not affect the parent', () => {
            const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });
            const inst = Material.createInstance(src);

            Material.setUniform(inst, 'u_val', 20);
            expect(Material.getUniform(src, 'u_val')).toBe(10);
            expect(Material.getUniform(inst, 'u_val')).toBe(20);
        });

        it('a parent edit PROPAGATES to a non-overriding instance', () => {
            const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });
            const inst = Material.createInstance(src);

            Material.setUniform(src, 'u_val', 99);
            expect(Material.getUniform(inst, 'u_val')).toBe(99);  // inherited the change
        });

        it('an overridden param shields the instance from parent edits', () => {
            const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });
            const inst = Material.createInstance(src);
            Material.setUniform(inst, 'u_val', 20);  // override

            Material.setUniform(src, 'u_val', 99);
            expect(Material.getUniform(inst, 'u_val')).toBe(20);  // override wins
        });

        it('an instance can override render state independently of the parent', () => {
            const src = Material.create({ shader: 1 as ShaderHandle, blendMode: BlendMode.Normal });
            const inst = Material.createInstance(src);
            Material.setBlendMode(inst, BlendMode.Additive);

            expect(Material.getBlendMode(inst)).toBe(BlendMode.Additive);
            expect(Material.getBlendMode(src)).toBe(BlendMode.Normal);
        });

        it('a parent edit re-pushes the instance to the engine (propagation)', () => {
            const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });
            const inst = Material.createInstance(src);
            mock.material_setUniform.mockClear();
            Material.setUniform(src, 'u_val', 99);
            // Both the parent and the inheriting instance are re-pushed with the new value.
            expect(mock.material_setUniform).toHaveBeenCalledWith(src, 'u_val', 1, 99, 0, 0, 0);
            expect(mock.material_setUniform).toHaveBeenCalledWith(inst, 'u_val', 1, 99, 0, 0, 0);
        });

        it('should throw for invalid source', () => {
            expect(() => Material.createInstance(999 as MaterialHandle)).toThrow(
                'Invalid source material: 999',
            );
        });

        it('should return a new handle different from source', () => {
            const src = Material.create({ shader: 1 as ShaderHandle });
            const inst = Material.createInstance(src);
            expect(inst).not.toBe(src);
            expect(inst).toBeGreaterThan(src);
        });
    });

    // =========================================================================
    // Material instance serialization (diff)
    // =========================================================================

    describe('Material instance serialization', () => {
        it('serializes an instance as a diff (instanceOf + only overrides)', () => {
            const src = Material.create({
                shader: 9 as ShaderHandle,
                uniforms: { u_a: 1, u_b: 2 },
                blendMode: BlendMode.Normal,
            });
            const inst = Material.createInstance(src);
            Material.setUniform(inst, 'u_a', 5);          // override one param
            Material.setBlendMode(inst, BlendMode.Additive);  // override render state

            const asset = Material.toAssetData(inst, '', 'parent.esmaterial')!;
            expect(asset.instanceOf).toBe('parent.esmaterial');
            expect(asset.properties).toEqual({ u_a: 5 });  // only the overridden param
            expect(asset.blendMode).toBe(BlendMode.Additive);
            expect(asset.depthTest).toBeUndefined();        // not overridden -> omitted
        });

        it('round-trips an instance via createFromAsset(parentHandle)', () => {
            const src = Material.create({ shader: 3 as ShaderHandle, uniforms: { u_a: 1 } });
            const asset: MaterialAssetData = {
                version: '1.0', type: 'material', shader: '', instanceOf: 'p.esmaterial',
                properties: { u_a: 7 },
            };
            const inst = Material.createFromAsset(asset, 0, src);
            expect(Material.getShader(inst)).toBe(3);        // inherited shader
            expect(Material.getUniform(inst, 'u_a')).toBe(7); // overridden value
        });

        it('a base material still serializes its full state', () => {
            const h = Material.create({ shader: 1 as ShaderHandle, blendMode: BlendMode.Multiply });
            const asset = Material.toAssetData(h, 'x.esshader')!;
            expect(asset.instanceOf).toBeUndefined();
            expect(asset.blendMode).toBe(BlendMode.Multiply);
        });
    });

    // =========================================================================
    // toAssetData
    // =========================================================================

    describe('Material.toAssetData', () => {
        it('should serialize to MaterialAssetData', () => {
            const h = Material.create({
                shader: 1 as ShaderHandle,
                uniforms: { u_time: 0.5 },
                blendMode: BlendMode.Multiply,
                depthTest: true,
            });
            const asset = Material.toAssetData(h, 'shaders/custom.shader');
            expect(asset).toEqual({
                version: '1.0',
                type: 'material',
                shader: 'shaders/custom.shader',
                blendMode: BlendMode.Multiply,
                depthTest: true,
                depthWrite: true,
                cull: CullMode.None,
                depthBias: 0,
                properties: { u_time: 0.5 },
            });
        });

        it('should return null for invalid material', () => {
            expect(Material.toAssetData(999 as MaterialHandle, 'path')).toBeNull();
        });

        it('should include all uniforms in properties', () => {
            const h = Material.create({
                shader: 1 as ShaderHandle,
                uniforms: {
                    u_a: 1,
                    u_b: { x: 1, y: 2 },
                    u_c: { x: 1, y: 2, z: 3 },
                },
            });
            const asset = Material.toAssetData(h, 'test.shader')!;
            expect(Object.keys(asset.properties)).toHaveLength(3);
            expect(asset.properties['u_a']).toBe(1);
            expect(asset.properties['u_b']).toEqual({ x: 1, y: 2 });
            expect(asset.properties['u_c']).toEqual({ x: 1, y: 2, z: 3 });
        });
    });

    // =========================================================================
    // tex() and isTextureRef
    // =========================================================================

    describe('Material.tex', () => {
        it('should return TextureRef with __textureRef flag', () => {
            const ref = Material.tex(42);
            expect(ref.__textureRef).toBe(true);
            expect(ref.textureId).toBe(42);
            expect(ref.slot).toBeUndefined();
        });

        it('should accept optional slot', () => {
            const ref = Material.tex(10, 3);
            expect(ref.textureId).toBe(10);
            expect(ref.slot).toBe(3);
        });
    });

    describe('isTextureRef', () => {
        it('should return true for TextureRef objects', () => {
            expect(isTextureRef(Material.tex(1))).toBe(true);
            expect(isTextureRef({ __textureRef: true, textureId: 5 } as TextureRef)).toBe(true);
        });

        it('should return false for numbers', () => {
            expect(isTextureRef(42)).toBe(false);
        });

        it('should return false for Vec2', () => {
            expect(isTextureRef({ x: 1, y: 2 })).toBe(false);
        });

        it('should return false for Vec3', () => {
            expect(isTextureRef({ x: 1, y: 2, z: 3 })).toBe(false);
        });

        it('should return false for Vec4', () => {
            expect(isTextureRef({ x: 1, y: 2, z: 3, w: 4 })).toBe(false);
        });

        it('should return false for arrays', () => {
            expect(isTextureRef([1, 2, 3])).toBe(false);
        });
    });

    // =========================================================================
    // Material parameter push (P1: reflection-driven MaterialConstants UBO)
    // =========================================================================

    describe('material parameter push', () => {
        it('compileShader proxies to module.material_compileEsshader (no switches => empty features)', () => {
            const h = Material.compileShader('#pragma shader "x"');
            expect(h).toBe(7);
            expect(mock.material_compileEsshader).toHaveBeenCalledWith('#pragma shader "x"', '');
        });

        it('compileShader passes enabled switches as a CSV feature set', () => {
            mock.material_compileEsshader.mockClear();
            Material.compileShader('src', ['USE_A', 'USE_B']);
            expect(mock.material_compileEsshader).toHaveBeenCalledWith('src', 'USE_A,USE_B');
        });

        it('stores static switches and round-trips them through toAssetData', () => {
            const h = Material.create({ shader: 1 as ShaderHandle, switches: { USE_GREEN: true } });
            expect(Material.getSwitch(h, 'USE_GREEN')).toBe(true);
            expect(Material.getSwitch(h, 'USE_NOPE')).toBe(false);
            const asset = Material.toAssetData(h, 'x.esshader')!;
            expect(asset.switches).toEqual({ USE_GREEN: true });
        });

        it('pushes uniform values to the engine on create', () => {
            const h = Material.create({
                shader: 1 as ShaderHandle,
                uniforms: { u_tint: { x: 1, y: 0, z: 0, w: 1 } },
            });
            expect(mock.material_setUniform).toHaveBeenCalledWith(h, 'u_tint', 4, 1, 0, 0, 1);
        });

        it('pushes the value on setUniform', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_setUniform.mockClear();
            Material.setUniform(h, 'u_strength', 2.5);
            expect(mock.material_setUniform).toHaveBeenCalledWith(h, 'u_strength', 1, 2.5, 0, 0, 0);
        });

        it('routes texture refs to material_setTexture (not the std140 uniform path)', () => {
            const h = Material.create({ shader: 1 as ShaderHandle });
            mock.material_setUniform.mockClear();
            mock.material_setTexture.mockClear();
            Material.setUniform(h, 'u_tex', Material.tex(5));
            expect(mock.material_setUniform).not.toHaveBeenCalled();
            expect(mock.material_setTexture).toHaveBeenCalledWith(h, 'u_tex', 5);
        });
    });

    // =========================================================================
    // ShaderSources constants
    // =========================================================================

    describe('ShaderSources', () => {
        it('should have SPRITE_VERTEX containing vertex shader markers', () => {
            expect(ShaderSources.SPRITE_VERTEX).toContain('#version 300 es');
            expect(ShaderSources.SPRITE_VERTEX).toContain('a_position');
            expect(ShaderSources.SPRITE_VERTEX).toContain('gl_Position');
        });

        it('should have SPRITE_FRAGMENT containing fragment shader markers', () => {
            expect(ShaderSources.SPRITE_FRAGMENT).toContain('#version 300 es');
            expect(ShaderSources.SPRITE_FRAGMENT).toContain('u_texture');
            expect(ShaderSources.SPRITE_FRAGMENT).toContain('fragColor');
        });

        it('should have COLOR_VERTEX containing vertex shader markers', () => {
            expect(ShaderSources.COLOR_VERTEX).toContain('#version 300 es');
            expect(ShaderSources.COLOR_VERTEX).toContain('a_position');
            expect(ShaderSources.COLOR_VERTEX).toContain('gl_Position');
        });

        it('should have COLOR_FRAGMENT containing fragment shader markers', () => {
            expect(ShaderSources.COLOR_FRAGMENT).toContain('#version 300 es');
            expect(ShaderSources.COLOR_FRAGMENT).toContain('v_color');
            expect(ShaderSources.COLOR_FRAGMENT).toContain('fragColor');
        });

        it('should have COLOR_FRAGMENT without texture sampler', () => {
            expect(ShaderSources.COLOR_FRAGMENT).not.toContain('u_texture');
        });
    });

    // =========================================================================
    // Uninitialized guard
    // =========================================================================

    // =========================================================================
    // A param name the shader does not declare
    // =========================================================================

    describe('writing a param the shader has no such name for', () => {
        // The engine drops it: MaterialStore keys the std140 layout by the reflected
        // name, so a value under any other name has nowhere to land. Silence made a
        // typo look like a broken shader — `u_amount` on a shader whose slider is
        // `u_progress` is a call that succeeds and an effect that never happens.
        const SRC = '#pragma domain Unlit2D\n#pragma param u_progress float default(0)\n'
            + '#pragma param u_edgeColor color default(1,0.5,0,1)\n';

        it('names what the shader DOES declare', () => {
            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
            const shader = Material.compileShader(SRC);
            const mat = Material.create({ shader });

            Material.setUniform(mat, 'u_amount', 0.5);

            expect(warn).toHaveBeenCalledTimes(1);
            const said = String(warn.mock.calls[0][0]);
            expect(said).toContain('u_amount');
            expect(said).toContain('u_progress');
            expect(said).toContain('u_edgeColor');
            warn.mockRestore();
        });

        it('says nothing about a name the shader declares', () => {
            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
            const mat = Material.create({ shader: Material.compileShader(SRC) });
            Material.setUniform(mat, 'u_progress', 0.5);
            expect(warn).not.toHaveBeenCalled();
            warn.mockRestore();
        });

        it('complains once, not once per frame', () => {
            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
            const mat = Material.create({ shader: Material.compileShader(SRC) });
            for (let i = 0; i < 60; i++) Material.setUniform(mat, 'u_amount', i);
            expect(warn).toHaveBeenCalledTimes(1);
            warn.mockRestore();
        });

        it('checks the properties a material file arrives with, not only later writes', () => {
            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
            const shader = Material.compileShader(SRC);
            Material.createFromAsset(
                { version: '1.0', type: 'material', shader: 'x.esshader', properties: { u_amount: 0 } } as MaterialAssetData,
                shader,
            );
            expect(warn).toHaveBeenCalledTimes(1);
            warn.mockRestore();
        });

        it('stays quiet for a shader built from raw GLSL — it declares no vocabulary', () => {
            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
            const mat = Material.create({ shader: Material.createShader('v', 'f') });
            Material.setUniform(mat, 'anything', 1);
            expect(warn).not.toHaveBeenCalled();
            warn.mockRestore();
        });

        it('judges an instance by the shader it inherits', () => {
            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
            const base = Material.create({ shader: Material.compileShader(SRC) });
            const instance = Material.createInstance(base);
            Material.setUniform(instance, 'u_progress', 1); // declared — inherited from the base
            expect(warn).not.toHaveBeenCalled();
            Material.setUniform(instance, 'u_amount', 1);
            expect(warn).toHaveBeenCalledTimes(1);
            warn.mockRestore();
        });
    });

    describe('uninitialized guard', () => {
        it('should throw when createShader called without init', () => {
            shutdownMaterialAPI();
            shutdownResourceManager();
            expect(() => Material.createShader('v', 'f')).toThrow(
                'ResourceManager not initialized',
            );
        });

        it('should throw when releaseShader called without init for valid handle', () => {
            shutdownMaterialAPI();
            shutdownResourceManager();
            expect(() => Material.releaseShader(1 as ShaderHandle)).toThrow(
                'ResourceManager not initialized',
            );
        });
    });
});