esengine/packages/material-system/src/MaterialManager.ts

/**
 * Material manager service.
 * 材质管理器服务。
 *
 * Manages materials and shaders for the rendering system.
 * 管理渲染系统的材质和着色器。
 */

import { Material } from './Material';
import {
    Shader,
    DEFAULT_VERTEX_SHADER,
    DEFAULT_FRAGMENT_SHADER,
    GRAYSCALE_FRAGMENT_SHADER,
    TINT_FRAGMENT_SHADER,
    FLASH_FRAGMENT_SHADER,
    OUTLINE_FRAGMENT_SHADER,
    SHINY_FRAGMENT_SHADER
} from './Shader';
import { BuiltInMaterials, BuiltInShaders, UniformType } from './types';
import type { IAssetManager } from '@esengine/asset-system';
import { AssetType } from '@esengine/asset-system';
import { MaterialLoader, type IMaterialAssetData } from './loaders/MaterialLoader';
import { ShaderLoader, type IShaderAssetData } from './loaders/ShaderLoader';
import { createLogger } from '@esengine/ecs-framework';

/** Logger instance for MaterialManager. | MaterialManager的日志实例。 */
const logger = createLogger('MaterialManager');

/**
 * Engine bridge interface for communicating with Rust engine.
 * 与Rust引擎通信的引擎桥接接口。
 */
export interface IEngineBridge {
    compileShader(vertexSource: string, fragmentSource: string): Promise<number>;
    compileShaderWithId(shaderId: number, vertexSource: string, fragmentSource: string): Promise<void>;
    hasShader(shaderId: number): boolean;
    removeShader(shaderId: number): boolean;

    createMaterial(name: string, shaderId: number, blendMode: number): number;
    createMaterialWithId(materialId: number, name: string, shaderId: number, blendMode: number): void;
    hasMaterial(materialId: number): boolean;
    removeMaterial(materialId: number): boolean;

    setMaterialFloat(materialId: number, name: string, value: number): boolean;
    setMaterialVec2(materialId: number, name: string, x: number, y: number): boolean;
    setMaterialVec3(materialId: number, name: string, x: number, y: number, z: number): boolean;
    setMaterialVec4(materialId: number, name: string, x: number, y: number, z: number, w: number): boolean;
    setMaterialColor(materialId: number, name: string, r: number, g: number, b: number, a: number): boolean;
    setMaterialBlendMode(materialId: number, blendMode: number): boolean;
}

/**
 * Material manager service.
 * 材质管理器服务。
 *
 * Manages materials, shaders, and their GPU resources.
 * 管理材质、着色器及其GPU资源。
 */
export class MaterialManager {
    /** Registered shaders. | 已注册的着色器。 */
    private shaders: Map<number, Shader> = new Map();

    /** Shader name to ID mapping. | 着色器名称到ID的映射。 */
    private shaderNameToId: Map<string, number> = new Map();

    /** Registered materials. | 已注册的材质。 */
    private materials: Map<number, Material> = new Map();

    /** Material name to ID mapping. | 材质名称到ID的映射。 */
    private materialNameToId: Map<string, number> = new Map();

    /** Material path to ID mapping. | 材质路径到ID的映射。 */
    private materialPathToId: Map<string, number> = new Map();

    /** Shader path to ID mapping. | 着色器路径到ID的映射。 */
    private shaderPathToId: Map<string, number> = new Map();

    /** Pending material loads (path -> promise). | 等待加载的材质（路径 -> Promise）。 */
    private pendingMaterialLoads: Map<string, Promise<number>> = new Map();

    /** Pending shader loads (path -> promise). | 等待加载的着色器（路径 -> Promise）。 */
    private pendingShaderLoads: Map<string, Promise<number>> = new Map();

    /** Next shader ID for custom shaders. | 下一个自定义着色器ID。 */
    private nextShaderId: number = 100;

    /** Next material ID for custom materials. | 下一个自定义材质ID。 */
    private nextMaterialId: number = 100;

    /** Engine bridge for GPU operations. | 用于GPU操作的引擎桥接。 */
    private engineBridge: IEngineBridge | null = null;

    /** Asset manager for loading material files. | 用于加载材质文件的资产管理器。 */
    private assetManager: IAssetManager | null = null;

    constructor() {
        // Register built-in shaders and materials.
        // 注册内置着色器和材质。
        this.registerBuiltInAssets();
    }

    /**
     * Set the engine bridge for GPU operations.
     * 设置用于GPU操作的引擎桥接。
     *
     * When set, uploads all built-in shaders to the GPU.
     * 设置后，将所有内置着色器上传到GPU。
     *
     * @param bridge - Engine bridge instance. | 引擎桥接实例。
     */
    setEngineBridge(bridge: IEngineBridge): void {
        this.engineBridge = bridge;

        // Upload all existing shaders to the engine
        // 将所有现有着色器上传到引擎
        this.uploadShadersToEngine();
    }

    /**
     * Upload all registered shaders to the engine.
     * 将所有已注册的着色器上传到引擎。
     *
     * Called automatically when engine bridge is set.
     * 设置引擎桥接时自动调用。
     */
    private uploadShadersToEngine(): void {
        if (!this.engineBridge) return;

        let shadersUploaded = 0;
        let materialsCreated = 0;

        for (const [shaderId, shader] of this.shaders) {
            // Skip if already compiled
            // 跳过已编译的着色器
            if (shader.compiled) continue;

            try {
                // Compile shader
                // 编译着色器
                this.engineBridge.compileShaderWithId(
                    shaderId,
                    shader.vertexSource,
                    shader.fragmentSource
                );
                shader.markCompiled();
                shadersUploaded++;
                logger.debug(`Uploaded shader ${shader.name} (ID: ${shaderId}) to engine`);

                // Create a material for this shader if it doesn't exist in the engine
                // 为此着色器创建材质（如果引擎中不存在）
                // This allows sprites to reference the shader via materialId
                // 这允许精灵通过 materialId 引用着色器
                if (!this.engineBridge.hasMaterial(shaderId)) {
                    // Use shaderId as materialId for built-in shaders (1:1 mapping)
                    // 对于内置着色器，使用 shaderId 作为 materialId（1:1 映射）
                    // BlendMode 1 = Alpha blending
                    this.engineBridge.createMaterialWithId(shaderId, shader.name, shaderId, 1);
                    materialsCreated++;
                    logger.debug(`Created material ${shader.name} (ID: ${shaderId}) for shader`);
                }
            } catch (e) {
                logger.error(`Failed to upload shader ${shader.name} (ID: ${shaderId}):`, e);
            }
        }

        logger.info(`Uploaded ${shadersUploaded} shaders and created ${materialsCreated} materials | 已上传 ${shadersUploaded} 个着色器，创建 ${materialsCreated} 个材质`);
    }

    /**
     * Set the asset manager for loading material files.
     * 设置用于加载材质文件的资产管理器。
     *
     * Also registers Material and Shader loaders with the asset manager.
     * 同时向资产管理器注册材质和着色器加载器。
     *
     * @param manager - Asset manager instance. | 资产管理器实例。
     */
    setAssetManager(manager: IAssetManager): void {
        this.assetManager = manager;

        // Register loaders with asset manager.
        // 向资产管理器注册加载器。
        if (manager.registerLoader) {
            manager.registerLoader(AssetType.Material, new MaterialLoader());
            manager.registerLoader(AssetType.Shader, new ShaderLoader());
            logger.info('Registered Material and Shader loaders');
        }
    }

    private registerBuiltInAssets(): void {
        // Built-in shaders
        const builtInShaders = [
            { id: BuiltInShaders.DefaultSprite, name: 'DefaultSprite', vertex: DEFAULT_VERTEX_SHADER, fragment: DEFAULT_FRAGMENT_SHADER },
            { id: BuiltInShaders.Grayscale, name: 'Grayscale', vertex: DEFAULT_VERTEX_SHADER, fragment: GRAYSCALE_FRAGMENT_SHADER },
            { id: BuiltInShaders.Tint, name: 'Tint', vertex: DEFAULT_VERTEX_SHADER, fragment: TINT_FRAGMENT_SHADER },
            { id: BuiltInShaders.Flash, name: 'Flash', vertex: DEFAULT_VERTEX_SHADER, fragment: FLASH_FRAGMENT_SHADER },
            { id: BuiltInShaders.Outline, name: 'Outline', vertex: DEFAULT_VERTEX_SHADER, fragment: OUTLINE_FRAGMENT_SHADER },
            { id: BuiltInShaders.Shiny, name: 'Shiny', vertex: DEFAULT_VERTEX_SHADER, fragment: SHINY_FRAGMENT_SHADER },
        ];

        for (const { id, name, vertex, fragment } of builtInShaders) {
            const shader = new Shader(name, vertex, fragment);
            shader.id = id;
            this.shaders.set(id, shader);
            this.shaderNameToId.set(name, id);
        }

        // Built-in materials
        const builtInMaterials = [
            { id: BuiltInMaterials.Default, material: Material.sprite() },
            { id: BuiltInMaterials.Additive, material: Material.additive() },
            { id: BuiltInMaterials.Multiply, material: Material.multiply() },
            { id: BuiltInMaterials.Unlit, material: Material.unlit() },
        ];

        for (const { id, material } of builtInMaterials) {
            material.id = id;
            this.materials.set(id, material);
            this.materialNameToId.set(material.name, id);
        }
    }

    // ============= Shader Management =============
    // ============= 着色器管理 =============

    /**
     * Register a shader.
     * 注册着色器。
     *
     * # Arguments | 参数
     * * `shader` - Shader instance to register. | 要注册的着色器实例。
     *
     * # Returns | 返回
     * Shader ID for referencing this shader. | 用于引用此着色器的ID。
     */
    async registerShader(shader: Shader): Promise<number> {
        const shaderId = this.nextShaderId++;
        shader.id = shaderId;

        // Compile on GPU if engine bridge is available
        if (this.engineBridge) {
            await this.engineBridge.compileShaderWithId(
                shaderId,
                shader.vertexSource,
                shader.fragmentSource
            );
            shader.markCompiled();
        }

        this.shaders.set(shaderId, shader);
        this.shaderNameToId.set(shader.name, shaderId);

        return shaderId;
    }

    /**
     * Get a shader by ID.
     * 按ID获取着色器。
     *
     * # Arguments | 参数
     * * `shaderId` - Shader ID to look up. | 要查找的着色器ID。
     *
     * # Returns | 返回
     * Shader instance or undefined if not found. | 着色器实例，未找到则返回 undefined。
     */
    getShader(shaderId: number): Shader | undefined {
        return this.shaders.get(shaderId);
    }

    /**
     * Get a shader by name.
     * 按名称获取着色器。
     *
     * # Arguments | 参数
     * * `name` - Shader name to look up. | 要查找的着色器名称。
     *
     * # Returns | 返回
     * Shader instance or undefined if not found. | 着色器实例，未找到则返回 undefined。
     */
    getShaderByName(name: string): Shader | undefined {
        const id = this.shaderNameToId.get(name);
        return id !== undefined ? this.shaders.get(id) : undefined;
    }

    /**
     * Check if a shader exists.
     * 检查着色器是否存在。
     *
     * # Arguments | 参数
     * * `shaderId` - Shader ID to check. | 要检查的着色器ID。
     */
    hasShader(shaderId: number): boolean {
        return this.shaders.has(shaderId);
    }

    /**
     * Remove a shader.
     * 移除着色器。
     *
     * # Arguments | 参数
     * * `shaderId` - Shader ID to remove. | 要移除的着色器ID。
     *
     * # Returns | 返回
     * True if shader was removed, false if not found or is built-in. | 移除成功返回 true，未找到或是内置着色器返回 false。
     */
    removeShader(shaderId: number): boolean {
        if (shaderId < 100) {
            logger.warn('Cannot remove built-in shader:', shaderId);
            return false;
        }

        const shader = this.shaders.get(shaderId);
        if (shader) {
            this.shaderNameToId.delete(shader.name);
            this.shaders.delete(shaderId);

            if (this.engineBridge) {
                this.engineBridge.removeShader(shaderId);
            }

            return true;
        }

        return false;
    }

    // ============= Path-based Shader Loading =============
    // ============= 基于路径的着色器加载 =============

    /**
     * Get shader ID by file path.
     * 通过文件路径获取着色器ID。
     *
     * Returns 0 (default shader) if not loaded.
     * 如果未加载则返回0（默认着色器）。
     *
     * # Arguments | 参数
     * * `path` - Shader file path (.shader). | 着色器文件路径（.shader）。
     *
     * # Returns | 返回
     * Shader ID or 0 if not found. | 着色器ID，未找到则返回0。
     */
    getShaderIdByPath(path: string): number {
        if (!path) return 0;
        return this.shaderPathToId.get(path) ?? 0;
    }

    /**
     * Check if a shader is loaded from a path.
     * 检查着色器是否已从路径加载。
     *
     * # Arguments | 参数
     * * `path` - Shader file path to check. | 要检查的着色器文件路径。
     */
    hasShaderByPath(path: string): boolean {
        return this.shaderPathToId.has(path);
    }

    /**
     * Load a shader from a .shader file path.
     * 从 .shader 文件路径加载着色器。
     *
     * Uses asset-system for file loading and caches the result.
     * 使用 asset-system 进行文件加载并缓存结果。
     *
     * # Arguments | 参数
     * * `path` - Shader file path. | 着色器文件路径。
     *
     * # Returns | 返回
     * Shader ID (0 if load failed). | 着色器ID（加载失败返回0）。
     */
    async loadShaderFromPath(path: string): Promise<number> {
        // Return cached ID if already loaded.
        // 如果已加载则返回缓存的ID。
        const existingId = this.shaderPathToId.get(path);
        if (existingId !== undefined) {
            return existingId;
        }

        // Return pending promise if already loading.
        // 如果正在加载则返回等待中的 Promise。
        const pendingLoad = this.pendingShaderLoads.get(path);
        if (pendingLoad) {
            return pendingLoad;
        }

        // Create loading promise.
        // 创建加载 Promise。
        const loadPromise = this.doLoadShaderFromPath(path);
        this.pendingShaderLoads.set(path, loadPromise);

        try {
            const shaderId = await loadPromise;
            return shaderId;
        } finally {
            this.pendingShaderLoads.delete(path);
        }
    }

    /**
     * Internal method to load shader from path.
     * 内部方法，从路径加载着色器。
     *
     * # Arguments | 参数
     * * `path` - Shader file path. | 着色器文件路径。
     *
     * # Returns | 返回
     * Shader ID, or 0 if load failed. | 着色器ID，加载失败返回0。
     */
    private async doLoadShaderFromPath(path: string): Promise<number> {
        if (!this.assetManager) {
            logger.warn('No asset manager set, cannot load shader from path:', path);
            return 0;
        }

        try {
            // Use asset-system to load shader file.
            // 使用 asset-system 加载着色器文件。
            const result = await this.assetManager.loadAssetByPath<IShaderAssetData>(path);

            // Get shader from asset data.
            // 从资产数据获取着色器。
            const shader = result.asset.shader;
            if (!shader) {
                logger.error('Shader asset is null for path:', path);
                return 0;
            }

            // Register the shader.
            // 注册着色器。
            const shaderId = await this.registerShader(shader);

            // Cache path -> ID mapping.
            // 缓存路径到ID的映射。
            this.shaderPathToId.set(path, shaderId);

            return shaderId;
        } catch (error) {
            logger.error('Failed to load shader from path:', path, error);
            return 0;
        }
    }

    /**
     * Unload a shader loaded from a path.
     * 卸载从路径加载的着色器。
     *
     * # Arguments | 参数
     * * `path` - Shader file path to unload. | 要卸载的着色器文件路径。
     *
     * # Returns | 返回
     * True if unloaded successfully. | 卸载成功返回 true。
     */
    unloadShaderByPath(path: string): boolean {
        const shaderId = this.shaderPathToId.get(path);
        if (shaderId === undefined) {
            return false;
        }

        this.shaderPathToId.delete(path);
        return this.removeShader(shaderId);
    }

    // ============= Material Management =============
    // ============= 材质管理 =============

    /**
     * Register a material.
     * 注册材质。
     *
     * # Arguments | 参数
     * * `material` - Material instance to register. | 要注册的材质实例。
     *
     * # Returns | 返回
     * Material ID for referencing this material. | 用于引用此材质的ID。
     */
    registerMaterial(material: Material): number {
        const materialId = this.nextMaterialId++;
        material.id = materialId;

        // Create on GPU if engine bridge is available
        if (this.engineBridge) {
            this.engineBridge.createMaterialWithId(
                materialId,
                material.name,
                material.shaderId,
                material.blendMode
            );
            this.syncMaterialUniforms(material);
        }

        this.materials.set(materialId, material);
        this.materialNameToId.set(material.name, materialId);

        return materialId;
    }

    /**
     * Get a material by ID.
     * 按ID获取材质。
     *
     * # Arguments | 参数
     * * `materialId` - Material ID to look up. | 要查找的材质ID。
     *
     * # Returns | 返回
     * Material instance or undefined if not found. | 材质实例，未找到则返回 undefined。
     */
    getMaterial(materialId: number): Material | undefined {
        return this.materials.get(materialId);
    }

    /**
     * Get a material by name.
     * 按名称获取材质。
     *
     * # Arguments | 参数
     * * `name` - Material name to look up. | 要查找的材质名称。
     *
     * # Returns | 返回
     * Material instance or undefined if not found. | 材质实例，未找到则返回 undefined。
     */
    getMaterialByName(name: string): Material | undefined {
        const id = this.materialNameToId.get(name);
        return id !== undefined ? this.materials.get(id) : undefined;
    }

    /**
     * Check if a material exists.
     * 检查材质是否存在。
     *
     * # Arguments | 参数
     * * `materialId` - Material ID to check. | 要检查的材质ID。
     */
    hasMaterial(materialId: number): boolean {
        return this.materials.has(materialId);
    }

    /**
     * Remove a material.
     * 移除材质。
     *
     * # Arguments | 参数
     * * `materialId` - Material ID to remove. | 要移除的材质ID。
     *
     * # Returns | 返回
     * True if material was removed, false if not found or is built-in. | 移除成功返回 true，未找到或是内置材质返回 false。
     */
    removeMaterial(materialId: number): boolean {
        if (materialId < 100) {
            logger.warn('Cannot remove built-in material:', materialId);
            return false;
        }

        const material = this.materials.get(materialId);
        if (material) {
            this.materialNameToId.delete(material.name);
            this.materials.delete(materialId);

            if (this.engineBridge) {
                this.engineBridge.removeMaterial(materialId);
            }

            return true;
        }

        return false;
    }

    /**
     * Sync material uniforms to GPU.
     * 同步材质 uniform 到GPU。
     *
     * # Arguments | 参数
     * * `material` - Material to sync. | 要同步的材质。
     */
    syncMaterialUniforms(material: Material): void {
        if (!this.engineBridge || material.id < 0) return;

        for (const [name, uniform] of material.getUniforms()) {
            switch (uniform.type) {
                case UniformType.Float:
                    this.engineBridge.setMaterialFloat(material.id, name, uniform.value as number);
                    break;
                case UniformType.Vec2: {
                    const v2 = uniform.value as number[];
                    this.engineBridge.setMaterialVec2(material.id, name, v2[0], v2[1]);
                    break;
                }
                case UniformType.Vec3: {
                    const v3 = uniform.value as number[];
                    this.engineBridge.setMaterialVec3(material.id, name, v3[0], v3[1], v3[2]);
                    break;
                }
                case UniformType.Vec4: {
                    const v4 = uniform.value as number[];
                    this.engineBridge.setMaterialVec4(material.id, name, v4[0], v4[1], v4[2], v4[3]);
                    break;
                }
                case UniformType.Color: {
                    const c = uniform.value as number[];
                    this.engineBridge.setMaterialColor(material.id, name, c[0], c[1], c[2], c[3]);
                    break;
                }
            }
        }

        material.markClean();
    }

    /**
     * Update all dirty materials.
     * 更新所有脏材质。
     *
     * Syncs all materials that have been modified since last sync.
     * 同步所有自上次同步以来被修改过的材质。
     */
    syncDirtyMaterials(): void {
        for (const material of this.materials.values()) {
            if (material.dirty) {
                this.syncMaterialUniforms(material);
            }
        }
    }

    // ============= Path-based Material Loading =============
    // ============= 基于路径的材质加载 =============

    /**
     * Get material ID by file path.
     * 通过文件路径获取材质ID。
     *
     * Returns 0 (default material) if not loaded.
     * 如果未加载则返回0（默认材质）。
     *
     * # Arguments | 参数
     * * `path` - Material file path (.mat). | 材质文件路径（.mat）。
     *
     * # Returns | 返回
     * Material ID or 0 if not found. | 材质ID，未找到则返回0。
     */
    getMaterialIdByPath(path: string): number {
        if (!path) return 0;
        return this.materialPathToId.get(path) ?? 0;
    }

    /**
     * Check if a material is loaded from a path.
     * 检查材质是否已从路径加载。
     *
     * # Arguments | 参数
     * * `path` - Material file path to check. | 要检查的材质文件路径。
     */
    hasMaterialByPath(path: string): boolean {
        return this.materialPathToId.has(path);
    }

    /**
     * Load a material from a .mat file path.
     * 从 .mat 文件路径加载材质。
     *
     * Uses asset-system for file loading and caches the result.
     * 使用 asset-system 进行文件加载并缓存结果。
     *
     * # Arguments | 参数
     * * `path` - Material file path. | 材质文件路径。
     *
     * # Returns | 返回
     * Material ID (0 if load failed). | 材质ID（加载失败返回0）。
     */
    async loadMaterialFromPath(path: string): Promise<number> {
        // Return cached ID if already loaded
        const existingId = this.materialPathToId.get(path);
        if (existingId !== undefined) {
            return existingId;
        }

        // Return pending promise if already loading
        const pendingLoad = this.pendingMaterialLoads.get(path);
        if (pendingLoad) {
            return pendingLoad;
        }

        // Create loading promise
        const loadPromise = this.doLoadMaterialFromPath(path);
        this.pendingMaterialLoads.set(path, loadPromise);

        try {
            const materialId = await loadPromise;
            return materialId;
        } finally {
            this.pendingMaterialLoads.delete(path);
        }
    }

    /**
     * Internal method to load material from path.
     * 内部方法，从路径加载材质。
     *
     * @param path - Material file path. | 材质文件路径。
     * @returns Material ID, or 0 if load failed. | 材质ID，加载失败返回0。
     */
    private async doLoadMaterialFromPath(path: string): Promise<number> {
        if (!this.assetManager) {
            logger.warn('No asset manager set, cannot load material from path:', path);
            return 0;
        }

        try {
            // Use asset-system to load material file.
            // 使用 asset-system 加载材质文件。
            const result = await this.assetManager.loadAssetByPath<IMaterialAssetData>(path);

            // Get material from asset data.
            // 从资产数据获取材质。
            const material = result.asset.material;
            if (!material) {
                logger.error('Material asset is null for path:', path);
                return 0;
            }

            // Register the material.
            // 注册材质。
            const materialId = this.registerMaterial(material);

            // Cache path -> ID mapping.
            // 缓存路径到ID的映射。
            this.materialPathToId.set(path, materialId);

            return materialId;
        } catch (error) {
            logger.error('Failed to load material from path:', path, error);
            return 0;
        }
    }

    /**
     * Preload multiple materials from paths.
     * 从路径预加载多个材质。
     *
     * Loads all materials in parallel for better performance.
     * 并行加载所有材质以获得更好的性能。
     *
     * # Arguments | 参数
     * * `paths` - Array of material file paths. | 材质文件路径数组。
     *
     * # Returns | 返回
     * Map of path to material ID. | 路径到材质ID的映射。
     */
    async preloadMaterials(paths: string[]): Promise<Map<string, number>> {
        const results = new Map<string, number>();

        await Promise.all(
            paths.map(async (path) => {
                const id = await this.loadMaterialFromPath(path);
                results.set(path, id);
            })
        );

        return results;
    }

    /**
     * Unload a material loaded from a path.
     * 卸载从路径加载的材质。
     *
     * # Arguments | 参数
     * * `path` - Material file path to unload. | 要卸载的材质文件路径。
     *
     * # Returns | 返回
     * True if unloaded successfully. | 卸载成功返回 true。
     */
    unloadMaterialByPath(path: string): boolean {
        const materialId = this.materialPathToId.get(path);
        if (materialId === undefined) {
            return false;
        }

        this.materialPathToId.delete(path);
        return this.removeMaterial(materialId);
    }

    // ============= Convenience Methods =============
    // ============= 便捷方法 =============

    /**
     * Create a sprite material with optional tint.
     * 创建带有可选着色的精灵材质。
     *
     * # Arguments | 参数
     * * `name` - Material name. | 材质名称。
     * * `tintR` - Red tint (0-1). | 红色着色（0-1）。
     * * `tintG` - Green tint (0-1). | 绿色着色（0-1）。
     * * `tintB` - Blue tint (0-1). | 蓝色着色（0-1）。
     *
     * # Returns | 返回
     * New Material instance. | 新的材质实例。
     */
    createSpriteMaterial(name: string, tintR: number = 1, tintG: number = 1, tintB: number = 1): Material {
        const material = new Material(name, BuiltInShaders.DefaultSprite);
        material.setColor('u_tint', tintR, tintG, tintB, 1.0);
        return material;
    }

    /**
     * Get all shader IDs.
     * 获取所有着色器ID。
     *
     * # Returns | 返回
     * Array of all registered shader IDs. | 所有已注册着色器ID的数组。
     */
    getShaderIds(): number[] {
        return Array.from(this.shaders.keys());
    }

    /**
     * Get all material IDs.
     * 获取所有材质ID。
     *
     * # Returns | 返回
     * Array of all registered material IDs. | 所有已注册材质ID的数组。
     */
    getMaterialIds(): number[] {
        return Array.from(this.materials.keys());
    }
}

// Singleton instance.
// 单例实例。
let materialManagerInstance: MaterialManager | null = null;

/**
 * Get the global MaterialManager instance.
 * 获取全局 MaterialManager 实例。
 *
 * Creates a new instance if one doesn't exist.
 * 如果实例不存在则创建新实例。
 *
 * # Returns | 返回
 * The global MaterialManager instance. | 全局 MaterialManager 实例。
 */
export function getMaterialManager(): MaterialManager {
    if (!materialManagerInstance) {
        materialManagerInstance = new MaterialManager();
    }
    return materialManagerInstance;
}