@metav_xly/decal-loader

基于 Three.js 的贴花加载器，支持纹理管理和贴花配置加载。

功能特性

• 🎨 纹理管理: 统一管理漫反射和法线贴图
• 📦 贴花加载: 支持从配置文件批量加载贴花
• 🔧 材质定制: 支持自定义材质构造函数
• 📝 日志系统: 内置模块化日志管理
• 🎯 TypeScript: 完整的类型定义支持

安装

npm install @metav_xly/decal-loader
# 或
pnpm add @metav_xly/decal-loader
# 或
yarn add @metav_xly/decal-loader

快速开始

import * as THREE from 'three'
import { DecalLoader, TextureManager } from '@metav_xly/decal-loader'

// 1. 配置纹理
const textureConfigs = [
  {
    label: 'metal',
    diffuseUrl: '/textures/metal_diffuse.jpg',
    normalUrl: '/textures/metal_normal.jpg'
  },
  {
    label: 'wood',
    diffuseUrl: '/textures/wood_diffuse.jpg',
    normalUrl: '/textures/wood_normal.jpg'
  }
]

// 2. 创建贴花加载器
const decalLoader = new DecalLoader(textureConfigs)

// 3. 等待纹理加载完成
await decalLoader.textureManager.loadTextures()

// 4. 加载贴花配置
const config = {
  version: '1.0.0',
  decals: [
    {
      id: 1,
      position: { x: 0, y: 0, z: 1 },
      orientation: { x: 0, y: 0, z: 0 },
      scale: 2,
      textureType: 'metal',
      normalScale: 1.0,
      targetName: 'mesh'
    }
  ]
}

const decalMeshes = decalLoader.loadConfig(config, targetMesh)

API 文档

DecalLoader

贴花加载器主类，负责从配置文件加载贴花。

构造函数

constructor(
  textureConfigs: TextureConfig[],
  materialConstructor?: MaterialConstructor
)

• textureConfigs: 纹理配置数组
• materialConstructor: 可选的自定义材质构造函数

方法

loadConfig(config, targetMesh)

从配置对象加载贴花到目标网格。

loadConfig(config: DecalConfig, targetMesh: THREE.Object3D): THREE.Mesh[]

• config: 贴花配置对象
• targetMesh: 目标网格对象
• 返回: 创建的贴花网格数组

validateConfig(config)

验证配置对象的有效性。

validateConfig(config: any): config is DecalConfig

TextureManager

纹理管理器，负责纹理加载和材质创建。

构造函数

constructor(
  textureConfigs: TextureConfig[],
  materialConstructor?: MaterialConstructor
)

方法

loadTextures()

异步加载所有配置的纹理。

async loadTextures(): Promise<void>

isReady()

检查纹理是否已加载完成。

isReady(): boolean

getMaterial(index)

获取指定索引的材质。

getMaterial(index: number): THREE.Material | null

cloneMaterial(index)

克隆指定索引的材质。

cloneMaterial(index: number): THREE.Material | null

Logger

模块化日志管理器。

使用方法

import { createModuleLogger, LogLevel } from '@metav_xly/decal-loader'

// 创建模块日志器
const logger = createModuleLogger('MyModule')

// 使用日志
logger.debug('调试信息')
logger.info('普通信息')
logger.warn('警告信息')
logger.error('错误信息')

// 设置日志级别
import { logger as globalLogger } from '@metav_xly/decal-loader'
globalLogger.setLogLevel(LogLevel.WARN)

类型定义

TextureConfig

interface TextureConfig {
  label: string          // 纹理标签
  diffuseUrl?: string   // 漫反射贴图 URL
  normalUrl?: string    // 法线贴图 URL
}

DecalData

interface DecalData {
  id: number
  position: { x: number; y: number; z: number }
  orientation: { x: number; y: number; z: number }
  scale: number
  textureType: string
  normalScale?: number
  targetName: string
}

DecalConfig

interface DecalConfig {
  version: string
  decals: DecalData[]
}

MaterialConstructor

type MaterialConstructor = (
  textureSet: TextureSet,
  index: number
) => THREE.Material

高级用法

自定义材质构造函数

const customMaterialConstructor = (textureSet, index) => {
  const material = new THREE.MeshStandardMaterial({
    map: textureSet.diffuse,
    normalMap: textureSet.normal,
    metalness: 0.5,
    roughness: 0.3
  })
  return material
}

const decalLoader = new DecalLoader(
  textureConfigs,
  customMaterialConstructor
)

批量加载贴花

// 从 JSON 文件加载配置
fetch('/decals/config.json')
  .then(response => response.json())
  .then(config => {
    if (decalLoader.validateConfig(config)) {
      const decalMeshes = decalLoader.loadConfig(config, targetMesh)
      console.log(`成功加载 ${decalMeshes.length} 个贴花`)
    }
  })

动态纹理管理

const textureManager = new TextureManager(textureConfigs)

// 等待纹理加载
await textureManager.loadTextures()

// 检查加载状态
if (textureManager.isReady()) {
  // 获取材质
  const material = textureManager.getMaterial(0)
  
  // 克隆材质用于不同的贴花
  const clonedMaterial = textureManager.cloneMaterial(0)
}

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

1.0.0

• 初始版本发布
• 支持基础的贴花加载功能
• 集成纹理管理器
• 提供完整的 TypeScript 类型定义