UnityExtension.cs 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347
  1. //------------------------------------------------------------
  2. // Game Framework
  3. // Copyright © 2013-2021 loyalsoft. All rights reserved.
  4. // Homepage: http://www.game7000.com/
  5. // Feedback: http://www.game7000.com/
  6. //------------------------------------------------------------
  7. using System;
  8. using System.Collections.Generic;
  9. using UnityEngine;
  10. /// <summary>
  11. /// 对 Unity 的扩展方法。
  12. /// </summary>
  13. public static class UnityExtension
  14. {
  15. private static readonly List<Transform> s_CachedTransforms = new List<Transform>();
  16. /// <summary>
  17. /// 获取或增加组件。
  18. /// </summary>
  19. /// <typeparam name="T">要获取或增加的组件。</typeparam>
  20. /// <param name="gameObject">目标对象。</param>
  21. /// <returns>获取或增加的组件。</returns>
  22. public static T GetOrAddComponent<T>(this GameObject gameObject) where T : Component
  23. {
  24. T component = gameObject.GetComponent<T>();
  25. if (component == null)
  26. {
  27. component = gameObject.AddComponent<T>();
  28. }
  29. return component;
  30. }
  31. /// <summary>
  32. /// 获取或增加组件。
  33. /// </summary>
  34. /// <param name="gameObject">目标对象。</param>
  35. /// <param name="type">要获取或增加的组件类型。</param>
  36. /// <returns>获取或增加的组件。</returns>
  37. public static Component GetOrAddComponent(this GameObject gameObject, Type type)
  38. {
  39. Component component = gameObject.GetComponent(type);
  40. if (component == null)
  41. {
  42. component = gameObject.AddComponent(type);
  43. }
  44. return component;
  45. }
  46. /// <summary>
  47. /// 获取 GameObject 是否在场景中。
  48. /// </summary>
  49. /// <param name="gameObject">目标对象。</param>
  50. /// <returns>GameObject 是否在场景中。</returns>
  51. /// <remarks>若返回 true,表明此 GameObject 是一个场景中的实例对象;若返回 false,表明此 GameObject 是一个 Prefab。</remarks>
  52. public static bool InScene(this GameObject gameObject)
  53. {
  54. return gameObject.scene.name != null;
  55. }
  56. /// <summary>
  57. /// 递归设置游戏对象的层次。
  58. /// </summary>
  59. /// <param name="gameObject"><see cref="GameObject" /> 对象。</param>
  60. /// <param name="layer">目标层次的编号。</param>
  61. public static void SetLayerRecursively(this GameObject gameObject, int layer)
  62. {
  63. gameObject.GetComponentsInChildren(true, s_CachedTransforms);
  64. for (int i = 0; i < s_CachedTransforms.Count; i++)
  65. {
  66. s_CachedTransforms[i].gameObject.layer = layer;
  67. }
  68. s_CachedTransforms.Clear();
  69. }
  70. /// <summary>
  71. /// 取 <see cref="Vector3" /> 的 (x, y, z) 转换为 <see cref="Vector2" /> 的 (x, z)。
  72. /// </summary>
  73. /// <param name="vector3">要转换的 Vector3。</param>
  74. /// <returns>转换后的 Vector2。</returns>
  75. public static Vector2 ToVector2(this Vector3 vector3)
  76. {
  77. return new Vector2(vector3.x, vector3.z);
  78. }
  79. /// <summary>
  80. /// 取 <see cref="Vector2" /> 的 (x, y) 转换为 <see cref="Vector3" /> 的 (x, 0, y)。
  81. /// </summary>
  82. /// <param name="vector2">要转换的 Vector2。</param>
  83. /// <returns>转换后的 Vector3。</returns>
  84. public static Vector3 ToVector3(this Vector2 vector2)
  85. {
  86. return new Vector3(vector2.x, 0f, vector2.y);
  87. }
  88. /// <summary>
  89. /// 取 <see cref="Vector2" /> 的 (x, y) 和给定参数 y 转换为 <see cref="Vector3" /> 的 (x, 参数 y, y)。
  90. /// </summary>
  91. /// <param name="vector2">要转换的 Vector2。</param>
  92. /// <param name="y">Vector3 的 y 值。</param>
  93. /// <returns>转换后的 Vector3。</returns>
  94. public static Vector3 ToVector3(this Vector2 vector2, float y)
  95. {
  96. return new Vector3(vector2.x, y, vector2.y);
  97. }
  98. #region Transform
  99. /// <summary>
  100. /// 设置绝对位置的 x 坐标。
  101. /// </summary>
  102. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  103. /// <param name="newValue">x 坐标值。</param>
  104. public static void SetPositionX(this Transform transform, float newValue)
  105. {
  106. Vector3 v = transform.position;
  107. v.x = newValue;
  108. transform.position = v;
  109. }
  110. /// <summary>
  111. /// 设置绝对位置的 y 坐标。
  112. /// </summary>
  113. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  114. /// <param name="newValue">y 坐标值。</param>
  115. public static void SetPositionY(this Transform transform, float newValue)
  116. {
  117. Vector3 v = transform.position;
  118. v.y = newValue;
  119. transform.position = v;
  120. }
  121. /// <summary>
  122. /// 设置绝对位置的 z 坐标。
  123. /// </summary>
  124. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  125. /// <param name="newValue">z 坐标值。</param>
  126. public static void SetPositionZ(this Transform transform, float newValue)
  127. {
  128. Vector3 v = transform.position;
  129. v.z = newValue;
  130. transform.position = v;
  131. }
  132. /// <summary>
  133. /// 增加绝对位置的 x 坐标。
  134. /// </summary>
  135. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  136. /// <param name="deltaValue">x 坐标值增量。</param>
  137. public static void AddPositionX(this Transform transform, float deltaValue)
  138. {
  139. Vector3 v = transform.position;
  140. v.x += deltaValue;
  141. transform.position = v;
  142. }
  143. /// <summary>
  144. /// 增加绝对位置的 y 坐标。
  145. /// </summary>
  146. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  147. /// <param name="deltaValue">y 坐标值增量。</param>
  148. public static void AddPositionY(this Transform transform, float deltaValue)
  149. {
  150. Vector3 v = transform.position;
  151. v.y += deltaValue;
  152. transform.position = v;
  153. }
  154. /// <summary>
  155. /// 增加绝对位置的 z 坐标。
  156. /// </summary>
  157. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  158. /// <param name="deltaValue">z 坐标值增量。</param>
  159. public static void AddPositionZ(this Transform transform, float deltaValue)
  160. {
  161. Vector3 v = transform.position;
  162. v.z += deltaValue;
  163. transform.position = v;
  164. }
  165. /// <summary>
  166. /// 设置相对位置的 x 坐标。
  167. /// </summary>
  168. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  169. /// <param name="newValue">x 坐标值。</param>
  170. public static void SetLocalPositionX(this Transform transform, float newValue)
  171. {
  172. Vector3 v = transform.localPosition;
  173. v.x = newValue;
  174. transform.localPosition = v;
  175. }
  176. /// <summary>
  177. /// 设置相对位置的 y 坐标。
  178. /// </summary>
  179. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  180. /// <param name="newValue">y 坐标值。</param>
  181. public static void SetLocalPositionY(this Transform transform, float newValue)
  182. {
  183. Vector3 v = transform.localPosition;
  184. v.y = newValue;
  185. transform.localPosition = v;
  186. }
  187. /// <summary>
  188. /// 设置相对位置的 z 坐标。
  189. /// </summary>
  190. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  191. /// <param name="newValue">z 坐标值。</param>
  192. public static void SetLocalPositionZ(this Transform transform, float newValue)
  193. {
  194. Vector3 v = transform.localPosition;
  195. v.z = newValue;
  196. transform.localPosition = v;
  197. }
  198. /// <summary>
  199. /// 增加相对位置的 x 坐标。
  200. /// </summary>
  201. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  202. /// <param name="deltaValue">x 坐标值。</param>
  203. public static void AddLocalPositionX(this Transform transform, float deltaValue)
  204. {
  205. Vector3 v = transform.localPosition;
  206. v.x += deltaValue;
  207. transform.localPosition = v;
  208. }
  209. /// <summary>
  210. /// 增加相对位置的 y 坐标。
  211. /// </summary>
  212. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  213. /// <param name="deltaValue">y 坐标值。</param>
  214. public static void AddLocalPositionY(this Transform transform, float deltaValue)
  215. {
  216. Vector3 v = transform.localPosition;
  217. v.y += deltaValue;
  218. transform.localPosition = v;
  219. }
  220. /// <summary>
  221. /// 增加相对位置的 z 坐标。
  222. /// </summary>
  223. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  224. /// <param name="deltaValue">z 坐标值。</param>
  225. public static void AddLocalPositionZ(this Transform transform, float deltaValue)
  226. {
  227. Vector3 v = transform.localPosition;
  228. v.z += deltaValue;
  229. transform.localPosition = v;
  230. }
  231. /// <summary>
  232. /// 设置相对尺寸的 x 分量。
  233. /// </summary>
  234. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  235. /// <param name="newValue">x 分量值。</param>
  236. public static void SetLocalScaleX(this Transform transform, float newValue)
  237. {
  238. Vector3 v = transform.localScale;
  239. v.x = newValue;
  240. transform.localScale = v;
  241. }
  242. /// <summary>
  243. /// 设置相对尺寸的 y 分量。
  244. /// </summary>
  245. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  246. /// <param name="newValue">y 分量值。</param>
  247. public static void SetLocalScaleY(this Transform transform, float newValue)
  248. {
  249. Vector3 v = transform.localScale;
  250. v.y = newValue;
  251. transform.localScale = v;
  252. }
  253. /// <summary>
  254. /// 设置相对尺寸的 z 分量。
  255. /// </summary>
  256. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  257. /// <param name="newValue">z 分量值。</param>
  258. public static void SetLocalScaleZ(this Transform transform, float newValue)
  259. {
  260. Vector3 v = transform.localScale;
  261. v.z = newValue;
  262. transform.localScale = v;
  263. }
  264. /// <summary>
  265. /// 增加相对尺寸的 x 分量。
  266. /// </summary>
  267. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  268. /// <param name="deltaValue">x 分量增量。</param>
  269. public static void AddLocalScaleX(this Transform transform, float deltaValue)
  270. {
  271. Vector3 v = transform.localScale;
  272. v.x += deltaValue;
  273. transform.localScale = v;
  274. }
  275. /// <summary>
  276. /// 增加相对尺寸的 y 分量。
  277. /// </summary>
  278. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  279. /// <param name="deltaValue">y 分量增量。</param>
  280. public static void AddLocalScaleY(this Transform transform, float deltaValue)
  281. {
  282. Vector3 v = transform.localScale;
  283. v.y += deltaValue;
  284. transform.localScale = v;
  285. }
  286. /// <summary>
  287. /// 增加相对尺寸的 z 分量。
  288. /// </summary>
  289. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  290. /// <param name="deltaValue">z 分量增量。</param>
  291. public static void AddLocalScaleZ(this Transform transform, float deltaValue)
  292. {
  293. Vector3 v = transform.localScale;
  294. v.z += deltaValue;
  295. transform.localScale = v;
  296. }
  297. /// <summary>
  298. /// 二维空间下使 <see cref="Transform" /> 指向指向目标点的算法,使用世界坐标。
  299. /// </summary>
  300. /// <param name="transform"><see cref="Transform" /> 对象。</param>
  301. /// <param name="lookAtPoint2D">要朝向的二维坐标点。</param>
  302. /// <remarks>假定其 forward 向量为 <see cref="Vector3.up" />。</remarks>
  303. public static void LookAt2D(this Transform transform, Vector2 lookAtPoint2D)
  304. {
  305. Vector3 vector = lookAtPoint2D.ToVector3() - transform.position;
  306. vector.y = 0f;
  307. if (vector.magnitude > 0f)
  308. {
  309. transform.rotation = Quaternion.LookRotation(vector.normalized, Vector3.up);
  310. }
  311. }
  312. #endregion Transform
  313. }