# mods/ — 内容包投放目录（素材包 / 光影包 / Mod）

> 这是**主投放点**：把你下载好的 **素材包（材质包）**、**光影包**、以及功能 **Mod** 直接放进本目录，
> 客户端 / 服务器启动时统一扫描、按 `manifest.json` 的 `type` 字段自动分派。
> 完整格式见 [`../文档/设计.md`](../文档/设计.md) §1.3（内容包统一格式）。

## 怎么放

1. 把下载的包解压成 `<包名>/` 文件夹，**或直接放 `.zip` 压缩包**；
2. 包根目录必须含 `manifest.json`；
3. 启动游戏即可（开发模式支持热重载）。

## 三种包类型（manifest 里写 `type`）

| type | 用途 | 包内结构 |
| --- | --- | --- |
| `resource` | 素材包：覆盖默认纹理 / 模型 / 语言 / 音效 | `assets/...` |
| `shader` | 光影包：覆盖着色器管线 | `shaders/`（命名与内置一致，见 渲染.md §9） |
| `mod` | 功能 Mod：脚本 + 数据 + 注册内容 | `scripts/` `data/` `assets/<ns>/` |

> 素材包也支持**原生 Minecraft 格式**（`pack.mcmeta` + `assets/<ns>/...`，无需 manifest.json），
> 解压或 zip 直接放入即可自动识别；默认素材包示例见 [`../resourcepacks/`](../resourcepacks/README.md)。

## 素材包示例（`mods/MyPack/manifest.json`）

```json
{
  "type": "resource",
  "id": "my_texture_pack",
  "name": "My Texture Pack",
  "version": "1.0.0",
  "api_version": 1,
  "priority": 0,
  "resource_namespace": "minecraft",
  "description": "覆盖默认材质"
}
```

## 光影包示例（`mods/MyShaders/manifest.json`）

```json
{
  "type": "shader",
  "id": "my_shader_pack",
  "name": "My Shader Pack",
  "version": "1.0.0",
  "api_version": 1,
  "shaders": {
    "chunk": "shaders/chunk.vert,shaders/chunk.frag",
    "water": "shaders/water.vert,shaders/water.frag"
  }
}
```

## 没放任何包会怎样（默认回退）

- **没放素材包** → 使用随客户端嵌入的**初版默认材质**（`assets/`，go:embed）。
- **没放光影包** → 使用**系统默认光影**（内置 Forward 光照管线，见 `../文档/场景/渲染.md` §9）。
- 所以「不下载光影包」完全没问题，游戏自带一套能跑的光影系统。

## 规则

- 同类型资源冲突：`priority` 大的优先；相同则后加载者覆盖并告警。
- 素材包与光影包互不覆盖：素材包管纹理、光影包管着色阶段，可同时生效。
- `resourcepacks/`（[../resourcepacks/README.md](../resourcepacks/README.md)）为兼容目录，素材包也可放那里。