# Script 组件分析

## 组件职责

`Script.*` 负责：

- 脚本类型注册与脚本实例创建；
- `script_id` 生命周期管理；
- 脚本逐帧更新；
- 脚本对 Transform 的延迟写回。

## 核心存储

`Script.cpp` 的关键结构：

- `entity_scripts`：活跃脚本实例池
- `id_mapping`：`script_id` 索引到实例池下标
- `generations + free_ids`：脚本 ID 代数与复用队列
- `transform_cache`：脚本写变换的缓存数组
- `cache_map`：Transform ID 到缓存下标映射

## 注册机制

脚本工厂注册表：

- 类型：`unordered_map<size_t, script_creator>`
- `register_script(tag, func)` 注册工厂
- `get_script_creator(tag)` 查询工厂

通常由 `REGISTER_SCRIPT` 宏在静态初始化阶段完成注册。

## 创建流程

`script::create(init_info, entity)`：

1. 校验实体有效与工厂函数有效；
2. 分配 `script_id`（复用或新建）；
3. 调用工厂创建脚本实例并压入 `entity_scripts`；
4. 写入 `id_mapping`；
5. 返回 `script::component` 句柄。

## 删除流程

`script::remove(component c)`：

- 校验组件存在；
- 用无序删除移除脚本实例；
- 修正被交换元素的 `id_mapping`；
- 将被删 id 的映射标记为无效。

## 更新与缓存提交流程

`script::update(dt)` 包含两段：

1. 遍历 `entity_scripts` 执行每个脚本的 `update(dt)`；
2. 若 `transform_cache` 非空，统一调用 `transform::update(...)` 提交后清空。

这使脚本阶段不直接写 Transform 主数组，减少帧内重复写。

## 脚本写 Transform 的方式

`entity_script::set_rotation/position/...` 的行为是：

- 先通过 `get_cache_ptr(entity)` 找到该实体缓存槽；
- 设置对应 `flags`；
- 写入新值到 cache；
- 等待帧末统一提交。

## 设计特点

- 句柄安全：`script_id` 采用 generation 机制；
- 批处理友好：Transform 写入集中提交；
- 解耦：脚本逻辑与 Transform 存储细节隔离。

## 三条主线时序图（注册、生命周期、缓存提交）

```mermaid
sequenceDiagram
    autonumber
    participant Macro as REGISTER_SCRIPT
    participant Detail as script::detail
    participant Registry as script_registry
    participant Entity as game_entity::entity
    participant ScriptSys as script::system
    participant Obj as entity_script
    participant Cache as transform_cache
    participant Trans as transform::system

    rect rgb(236, 248, 255)
    Note over Macro,Registry: 主线一：脚本类型注册
    Macro->>Detail: register_script(tag, creator)
    Detail->>Registry: insert(tag, creator)
    Registry-->>Detail: creator 已登记
    end

    rect rgb(239, 252, 240)
    Note over Entity,ScriptSys: 主线二：脚本实例生命周期
    Entity->>ScriptSys: create(init_info, entity)
    ScriptSys->>ScriptSys: 分配或复用 script_id
    ScriptSys->>Registry: get_script_creator(tag)
    Registry-->>ScriptSys: 返回 creator
    ScriptSys->>Obj: creator(entity)
    Obj-->>ScriptSys: 生成脚本实例
    ScriptSys->>ScriptSys: 写入 entity_scripts 与 id_mapping
    ScriptSys-->>Entity: 返回 script::component
    Entity->>ScriptSys: remove(component)
    ScriptSys->>ScriptSys: erase_unordered + 修正 id_mapping
    end

    rect rgb(255, 246, 236)
    Note over Obj,Trans: 主线三：脚本写变换缓存并帧末提交
    ScriptSys->>Obj: update(dt)
    Obj->>Cache: set_position/rotation/scale...
    Cache-->>Obj: flags + value 已缓存
    ScriptSys->>Trans: transform::update(cache, count)
    Trans-->>ScriptSys: 写入完成
    ScriptSys->>Cache: clear()
    end
```