# Спецификация формата файла .3db

## Обзор

Формат файла .3db используется для хранения трехмерных моделей, включая геометрию, текстуры, анимации и другие данные. Этот документ описывает структуру и формат файла .3db на основе реализации декодера в проекте Digglestool.

## Общая структура файла

Файл .3db имеет бинарный формат с порядком байтов little-endian. Файл состоит из нескольких последовательных секций:

1. Заголовок файла
2. Секция материалов
3. Секция мешей
4. Секция объектов
5. Секция анимаций
6. Секция теней
7. Секция кубических карт
8. Секция данных (треугольники, текстурные координаты, точки, яркость)

## Типы данных

### Базовые типы

- **uint8**: 8-битное беззнаковое целое число
- **uint16**: 16-битное беззнаковое целое число
- **uint32**: 32-битное беззнаковое целое число
- **float32**: 32-битное число с плавающей точкой

### Строки

Строки хранятся в следующем формате:
- **uint32**: длина строки в байтах
- **byte[]**: массив байтов, представляющий строку

### Векторы и координаты

- **Vector**: массив из трех float32 значений [X, Y, Z]
- **Coordinate**: массив из двух float32 значений [U, V]

## Детальное описание секций

### 1. Заголовок файла

Заголовок файла содержит:
- **string**: версия базы данных (DBVersion)
- **string**: имя модели (Name)

### 2. Секция материалов

Секция материалов начинается с:
- **uint16**: количество материалов

За этим следуют записи материалов, каждая из которых содержит:
- **string**: имя материала
- **string**: путь к текстуре материала
- **uint32**: неизвестное значение

### 3. Секция мешей

Секция мешей начинается с:
- **uint32**: количество мешей

За этим следуют записи мешей, каждая из которых содержит:
- **Секция связей меша**:
  - **uint16**: количество связей
  - Для каждой связи:
    - **uint16**: индекс материала
    - **uint16**: неизвестное значение
    - **uint16**: индекс массива треугольников
    - **uint16**: индекс массива текстурных координат
    - **uint16**: индекс массива точек
    - **uint16**: индекс массива яркости
- **Vector**: первый вектор (возможно, позиция или ориентация)
- **Vector**: второй вектор (возможно, масштаб или ограничивающий бокс)
- **пропуск 0x80 байт**: неиспользуемые данные
- **uint16**: индекс тени
- **пропуск 0x30 байт**: неиспользуемые данные
- **uint16**: индекс кубической карты

### 4. Секция объектов

Секция объектов начинается с:
- **uint16**: количество пар ключ-значение

За этим следуют пары ключ-значение, каждая из которых содержит:
- **string**: ключ
- **uint16**: количество объектов
- **uint32[]**: массив индексов объектов

### 5. Секция анимаций

Секция анимаций начинается с:
- **uint16**: количество анимаций

За этим следуют записи анимаций, каждая из которых содержит:
- **string**: имя анимации
- **uint16**: количество индексов мешей
- **uint32[]**: массив индексов мешей
- **uint16**: неизвестное значение 1
- **uint16**: неизвестное значение 2
- **uint16**: неизвестное значение 3
- **string**: неизвестная строка
- **Vector**: вектор перемещения
- **Vector**: вектор вращения

### 6. Секция теней

Секция теней начинается с:
- **uint16**: количество теней

За этим следуют данные теней, каждая из которых содержит:
- **пропуск 32*32 байт**: данные изображения тени (предположительно 32x32 пикселя)

### 7. Секция кубических карт

Секция кубических карт начинается с:
- **uint16**: количество кубических карт

За этим следуют записи кубических карт, каждая из которых содержит:
- **uint16**: ширина
- **uint16**: высота
- **uint16**: неизвестное значение 1
- **uint16**: неизвестное значение 2
- **пропуск width*height байт**: данные пикселей

### 8. Секция данных

Секция данных содержит:
- **uint16**: количество массивов треугольников
- **uint16**: количество массивов текстурных координат
- **uint16**: количество массивов точек
- **uint16**: количество массивов яркости
- **uint32**: неизвестное количество

Затем следуют размеры массивов:
- **uint16[]**: размеры массивов треугольников
- **uint16[]**: размеры массивов текстурных координат
- **uint16[]**: размеры массивов точек
- **uint16[]**: размеры массивов яркости

Затем следует пропуск неизвестных данных:
- **пропуск 20*unknownCount байт**: неизвестные данные

Затем следуют данные массивов:
- **Массивы треугольников**: для каждого массива:
  - **uint16[]**: индексы вершин треугольников
- **Массивы текстурных координат**: для каждого массива:
  - **Coordinate[]**: текстурные координаты (U, V)
- **Массивы точек**: для каждого массива:
  - **Vector[]**: точки (X, Y, Z), хранятся как нормализованные uint16 значения
- **Массивы яркости**: для каждого массива:
  - **uint8[]**: значения яркости

## Структуры данных

### Material (Материал)
```
type Material struct {
    Name, Path string
    Unknown    uint32
}
```

### Mesh (Меш)
```
type Mesh struct {
    Links   []MeshLink
    Vector1 *Vector
    Vector2 *Vector
    Shadow  uint16
    CMap    uint16
}
```

### MeshLink (Связь меша)
```
type MeshLink struct {
    Material           uint16
    Triangles          uint16
    TextureCoordinates uint16
    Points             uint16
    Brightness         uint16
    Unknown            uint16
}
```

### Animation (Анимация)
```
type Animation struct {
    Name                        string
    MeshIndexes                 []uint32
    Unknown, Unknown1, Unknown2 uint16
    Unknown3                    string
    MoveVector                  *Vector
    RotationVector              *Vector
}
```

### Vector (Вектор)
```
type Vector [3]float32
```

### Coordinate (Координата)
```
type Coordinate [2]float32
```

## Примечания по реализации

1. Все строки хранятся с предшествующей длиной (uint32).
2. Векторы точек хранятся как нормализованные значения в диапазоне [0, 1], которые затем преобразуются в координаты модели.
3. Некоторые поля помечены как "неизвестные", так как их точное назначение не определено в текущей реализации.
4. Файл использует порядок байтов little-endian для всех числовых значений.