# Parameter (配置系统)

- Summary: Five 用于控制三维模型渲染表现的核心配置系统，采用树形继承设计。
- Schema: 是所有配置项的容器，通过继承机制管理 Material 和 3DTile 等子配置。
- Concepts: Hierarchy (树形继承), Override (覆盖), Resolution (解析)。
- Examples: 全局配置、局部覆盖、参数重置。

## Schema

> Definition: Parameter

`Parameter` 类是配置的入口。它并不直接包含所有配置字段的定义，而是将它们组织在不同的接口中。

### Parameter Categories (参数分类)

为了便于理解，我们将参数分为两大类：

Category | Description | Link
--- | --- | ---
Material & Appearance | 控制“长什么样”。包括材质、颜色、楼层显示、阴影、点云样式等。 | Material Params
3DTile & Performance | 控制“怎么加载”。包括 LOD (细节层级)、显存配额、网络并发、SSE 阈值等。 | 3DTile Params

### Parameter Class API

#### 1. Getting Values (获取值)

获取参数值不使用 `get()` 方法，而是直接访问属性。

- Direct Access (直接访问): 获取当前 `Parameter` 实例上设置的值。如果未设置，返回 `undefined`。
- Resolve Value (计算最终值): 获取经过树形继承计算后的最终生效值。
  - 如果不传参，则基于默认值计算 (Default -> Current)。
  - 如果传入上游 Parameter，则基于默认值 + 上游 Parameter 计算 (Default -> Upstream -> Current)。

    // 方式 A: 直接访问 (获取当前层级配置)
    const currentVal = parameter.maxMemoryUsage;

    // 方式 B: 计算最终值 (包含继承逻辑)

    // 1. 基础用法：仅继承默认值
    const finalVal = parameter.resolveValue().maxMemoryUsage;

    // 2. 进阶用法：指定继承源 (例如 ViewLayer 继承自 Model)
    const inheritedVal = viewLayerParam.resolveValue(parentParameter).maxMemoryUsage;

#### 2. Methods (方法)

`Parameter` 实例提供了以下核心方法来管理配置：

    class Parameter {
      /**
       * 设置配置项
       * @param key 参数名 (如 'opacity', 'maxMemoryUsage')
       * @param value 参数值
       */
      set(key: string, value: any): void;

      /**
       * 重置配置项（移除当前层级的设置，恢复继承上游的值）
       * @param keys 要重置的参数名列表
       */
      reset(...keys: string[]): void;

      /**
       * 获取经过继承计算后的最终值（每次调用创建新对象）
       * @param upstream 上游 Parameter 对象列表（通常由引擎自动传入）
       */
      resolveValue(...upstream: Parameter[]): ResolvedParameterValue;

      /**
       * 获取经过继承计算后的最终值（复用 target 对象，避免重复创建）
       * 适用于高频调用场景（如逐帧更新），可显著减少 GC 压力。
       * @param target 用于写入结果的已有对象，其属性会被重置为默认值后重新赋值
       * @param upstream 上游 Parameter 对象列表
       */
      static resolveValueTo(
        target: Partial<ResolvedParameterValue>,
        ...upstream: Partial<ParameterValue>[]
      ): ResolvedParameterValue;
    }

> `resolveValue()` 内部已委托给 `resolveValueTo({}, ...)`，两者计算逻辑一致，区别仅在于是否复用对象。

#### 3. Version (版本标识)

`ResolvedParameterValue` 通过 `versionNumber: number` 标识当前配置的版本。引擎内部使用整数哈希（而非字符串拼接）计算版本号，用于高效的脏检查。

    interface ResolvedParameterValue extends ParameterValue {
      /** 整数哈希，输入参数变化时值会改变，用于脏检查 */
      versionNumber: number;
    }

## Concepts

### 树形继承关系 (Hierarchy)

Parameter 遵循 “就近原则” (Override) 的继承逻辑。

1. ViewLayer Parameter: 最具体，优先级最高。通常对应一个具体的 `.gltf` 文件或数据块。
2. Model Parameter: 覆盖该 Model 下的所有 ViewLayer。一个 Model 可能包含多个 ViewLayer (如 Mesh 层和 PointCloud 层)。
3. ModelScene Parameter: 全局默认值，优先级最低。影响整个场景。

    graph TD
      Scene[ModelScene.parameter] -->|Inherit| Model[Model.parameter]
      Model -->|Inherit| Layer1[ViewLayer.parameter]
      Model -->|Inherit| Layer2[ViewLayer.parameter]

> Global Configuration (全局设置): 若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），请直接配置 `five.modelScene.parameter`。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。

> Why modelScene? (生命周期优势): `Model` 实例是跟随 Work 加载生命周期的（需 `five.load(work)` 后才能访问，且切换 Work 会销毁重建）。 相比之下，`ModelScene` 是常驻对象。因此，使用 `modelScene` 进行配置更安全且持久，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。

## Examples

### 1. 基础配置 (Basic Usage)

    // 1. 设置全局最大显存 (影响所有模型)
    five.modelScene.parameter.set('maxMemoryUsage', 512);

    // 2. 设置全局半透明
    five.modelScene.parameter.set('opacity', 0.5);

### 2. 局部覆盖 (Override)

    // 场景中大部分模型不产生阴影
    five.modelScene.parameter.set('castShadow', false);

    // 但让特定的“主角”模型产生阴影
    const heroModel = five.models[0];
    heroModel.parameter.set('castShadow', true);

### 3. 重置配置 (Reset)

    // 假设之前设置了 opacity
    five.modelScene.parameter.set('opacity', 0.5);

    // ... 一段时间后 ...

    // 移除该设置，恢复默认值 (或继承值)
    five.modelScene.parameter.reset('opacity');

### 4. 获取配置 (Get Value)

    // 获取当前对象上的配置（如果未设置，则为 undefined）
    const ownOpacity = five.modelScene.parameter.opacity;

    // 获取最终生效的配置（计算继承链后的值）
    const finalOpacity = five.modelScene.parameter.resolveValue().opacity;

## Related

- Material Parameters: 材质与外观参数详情。
- 3DTile Parameters: 性能与加载参数详情。
- Model: Parameter 的宿主。

    tags: [配置, 参数, 继承, 覆盖, 全局配置, 局部配置, parameter, config, hierarchy, api, set, reset, modelScene]