Common3DTool

概述（Overview）

Common3DTool 是一个专注于 Unity 3D 物体常用操作 的静态工具类，位于 PFGameFramework.Library 命名空间。

主要功能包括：

• 物体高亮（Outline / Highlighter 组件支持）
• 物体显示/隐藏（单个、列表、按名称、MeshRenderer 过滤）
• 材质切换、渐变、淡入淡出（DOTween 支持）
• 异步动画等待（Tween 完成、序列播放）
• 碰撞体批量开关
• 物体顺序获取（链式排列、传动链等场景）
• 物体克隆（保留层级、命名规范化）
• 子物体顺序移动动画

适用于交互实验、教学引导、物体状态管理、材质动画、3D 物体序列展示等场景。

---

方法一览（API Index）

方法名	类型	异步	返回类型	主要功能	典型用途
SetOutLine	static	否	void	开启/关闭 EPOOutline 高亮效果	交互物体强调
SetHighlighter	static	否	void	开启/关闭 HighlightingSystem 高亮（带 tween）	旧版高亮方案
ShowOrHideItem	static	否	void	按名称显示/隐藏列表中的单个物体	步骤控制显隐
GetGo	static	否	GameObject	按名称从列表中获取物体	快速查找
ShowOrHideGoList	static	否	void	批量显示/隐藏物体列表	组显隐
ShowOrHide / ShowOrHideMesh	static	否	void	按 MeshRenderer 列表批量显隐	复杂模型部件控制
FadeOut / FadeIn	static	否	void	物体材质透明度淡出/淡入	渐隐/渐显效果
StartMaterialTransition	static	否	void	材质颜色在一段时间内渐变到目标材质	材质过渡动画
StartMaterialTransitionAsync	static	是	UniTask	异步材质颜色渐变（支持取消）	可中断的材质过渡
SwitchToMaterial / ChangeMaterial	static	否	void	立即切换到指定材质	状态材质切换
MoveChildrenSequentially	static	是	UniTask	子物体依次从底部升起（序列动画）	物体逐个出现效果
TweenAsync / TweenListAsync	static	是	UniTask	等待单个/多个 DOTween 动画完成	同步多段动画
SetColliderOnOff	static	否	void	递归开启/关闭物体及子物体所有 Collider	拖拽时避免干扰
GetAllObjectInOrder	static	否	List	根据空间距离顺序排列物体（链式/环环相扣）	传动链、顺序加载
CloneObj	static	否	GameObject	克隆物体（保留层级、变换、命名规范化）	动态生成副本

---

方法详情

高亮控制

SetOutLine

/// <summary>
/// 使用 EPOOutline 组件控制物体外发光高亮
/// </summary>
public static void SetOutLine(this GameObject obj, bool isOutLine)

SetHighlighter

/// <summary>
/// 使用 HighlightingSystem 的 Highlighter 组件控制高亮（支持 tween 动画）
/// </summary>
public static void SetHighlighter(this GameObject go, bool isOpen)

---

显示/隐藏控制

ShowOrHideItem / GetGo

/// <summary>
/// 从列表中按名称显示/隐藏单个物体
/// </summary>
public static void ShowOrHideItem(this IEnumerable<GameObject> gos, string name, bool isShow)

/// <summary>
/// 从列表中按名称获取物体
/// </summary>
public static GameObject GetGo(this IEnumerable<GameObject> gos, string goName)

ShowOrHideGoList / ShowOrHideMesh

/// <summary>
/// 批量显隐物体列表
/// </summary>
public static void ShowOrHideGoList(this List<GameObject> list, bool show)

/// <summary>
/// 批量显隐 MeshRenderer 列表
/// </summary>
public static void ShowOrHideMesh(List<MeshRenderer> mesh, bool isShow)

---

材质与淡入淡出

FadeOut / FadeIn

/// <summary>
/// 物体材质透明度渐变为 0（隐藏）
/// </summary>
public static void FadeOut(this GameObject target)

/// <summary>
/// 物体材质透明度渐变为 1（显示）
/// </summary>
public static void FadeIn(this GameObject target)

StartMaterialTransitionAsync（推荐）

/// <summary>
/// 异步材质颜色渐变，支持取消（使用 UniTask 每帧更新）
/// </summary>
public static async UniTask StartMaterialTransitionAsync(this GameObject obj, Material material1, Material material2, float transitionTime, CancellationToken token)

优点：支持中途取消，过渡更平滑。

---

动画等待与序列

MoveChildrenSequentially

/// <summary>
/// 子物体依次从下方升起（常用于逐个展示效果）
/// </summary>
public static async UniTask MoveChildrenSequentially(Transform target, CancellationToken ctk)

TweenAsync / TweenListAsync

/// <summary>
/// 等待一个或多个 DOTween Tween 完成
/// </summary>
public static async UniTask TweenAsync(Tween one, Tween two, CancellationToken ctk)
public static async UniTask TweenListAsync(List<Tween> list, CancellationToken ctk)

---

碰撞体与克隆

SetColliderOnOff

/// <summary>
/// 递归开启/关闭物体及其所有子物体的 Collider
/// </summary>
public static void SetColliderOnOff(GameObject objRoot, bool onOff)

典型场景：拖拽物体时关闭碰撞，避免射线被拦截。

CloneObj

/// <summary>
/// 克隆物体，保留变换、层级，并规范化命名（克隆体-原名）
/// </summary>
public static GameObject CloneObj(this GameObject obj)

---

物体排序

GetAllObjectInOrder

/// <summary>
/// 根据空间距离顺序排列物体（适合链条、环扣、顺序路径）
/// </summary>
public static List<GameObject> GetAllObjectInOrder(List<GameObject> allObjects, GameObject first)

用途：构建传动链、流水线、逐个加载序列。

---