@metav_xly/decal-loader/README.md

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

# @metav_xly/decal-loader

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

## 功能特性

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

## 安装

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

## 快速开始

```typescript
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

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

#### 构造函数

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

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

#### 方法

##### loadConfig(config, targetMesh)

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

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

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

##### validateConfig(config)

验证配置对象的有效性。

```typescript
validateConfig(config: any): config is DecalConfig
```

### TextureManager

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

#### 构造函数

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

#### 方法

##### loadTextures()

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

```typescript
async loadTextures(): Promise<void>
```

##### isReady()

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

```typescript
isReady(): boolean
```

##### getMaterial(index)

获取指定索引的材质。

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

##### cloneMaterial(index)

克隆指定索引的材质。

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

### Logger

模块化日志管理器。

#### 使用方法

```typescript
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

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

### DecalData

```typescript
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

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

### MaterialConstructor

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

## 高级用法

### 自定义材质构造函数

```typescript
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
)
```

### 批量加载贴花

```typescript
// 从 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} 个贴花`)
    }
  })
```

### 动态纹理管理

```typescript
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 类型定义