@esengine/ecs-framework-math 1.0.3 → 2.8.0

package/bin/Vector2.js

@@ -9,110 +9,110 @@
  */
 export class Vector2 {
     /**
-     * 创建2D向量
-     * @param x X分量，默认为0
-     * @param y Y分量，默认为0
-     */
+   * 创建2D向量
+   * @param x X分量，默认为0
+   * @param y Y分量，默认为0
+   */
     constructor(x = 0, y = 0) {
         this.x = x;
         this.y = y;
     }
     // 基础属性
     /**
-     * 获取向量长度（模）
-     */
+   * 获取向量长度（模）
+   */
     get length() {
         return Math.sqrt(this.x * this.x + this.y * this.y);
     }
     /**
-     * 获取向量长度的平方
-     */
+   * 获取向量长度的平方
+   */
     get lengthSquared() {
         return this.x * this.x + this.y * this.y;
     }
     /**
-     * 获取向量角度（弧度）
-     */
+   * 获取向量角度（弧度）
+   */
     get angle() {
         return Math.atan2(this.y, this.x);
     }
     /**
-     * 检查是否为零向量
-     */
+   * 检查是否为零向量
+   */
     get isZero() {
         return this.x === 0 && this.y === 0;
     }
     /**
-     * 检查是否为单位向量
-     */
+   * 检查是否为单位向量
+   */
     get isUnit() {
         const lenSq = this.lengthSquared;
         return Math.abs(lenSq - 1) < Number.EPSILON;
     }
     // 基础运算
     /**
-     * 设置向量分量
-     * @param x X分量
-     * @param y Y分量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 设置向量分量
+   * @param x X分量
+   * @param y Y分量
+   * @returns 当前向量实例（链式调用）
+   */
     set(x, y) {
         this.x = x;
         this.y = y;
         return this;
     }
     /**
-     * 复制另一个向量的值
-     * @param other 源向量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 复制另一个向量的值
+   * @param other 源向量
+   * @returns 当前向量实例（链式调用）
+   */
     copy(other) {
         this.x = other.x;
         this.y = other.y;
         return this;
     }
     /**
-     * 克隆当前向量
-     * @returns 新的向量实例
-     */
+   * 克隆当前向量
+   * @returns 新的向量实例
+   */
     clone() {
         return new Vector2(this.x, this.y);
     }
     /**
-     * 向量加法
-     * @param other 另一个向量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 向量加法
+   * @param other 另一个向量
+   * @returns 当前向量实例（链式调用）
+   */
     add(other) {
         this.x += other.x;
         this.y += other.y;
         return this;
     }
     /**
-     * 向量减法
-     * @param other 另一个向量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 向量减法
+   * @param other 另一个向量
+   * @returns 当前向量实例（链式调用）
+   */
     subtract(other) {
         this.x -= other.x;
         this.y -= other.y;
         return this;
     }
     /**
-     * 向量数乘
-     * @param scalar 标量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 向量数乘
+   * @param scalar 标量
+   * @returns 当前向量实例（链式调用）
+   */
     multiply(scalar) {
         this.x *= scalar;
         this.y *= scalar;
         return this;
     }
     /**
-     * 向量数除
-     * @param scalar 标量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 向量数除
+   * @param scalar 标量
+   * @returns 当前向量实例（链式调用）
+   */
     divide(scalar) {
         if (scalar === 0) {
             throw new Error('不能除以零');
@@ -122,9 +122,9 @@ export class Vector2 {
         return this;
     }
     /**
-     * 向量取反
-     * @returns 当前向量实例（链式调用）
-     */
+   * 向量取反
+   * @returns 当前向量实例（链式调用）
+   */
     negate() {
         this.x = -this.x;
         this.y = -this.y;
@@ -132,25 +132,25 @@ export class Vector2 {
     }
     // 向量运算
     /**
-     * 计算与另一个向量的点积
-     * @param other 另一个向量
-     * @returns 点积值
-     */
+   * 计算与另一个向量的点积
+   * @param other 另一个向量
+   * @returns 点积值
+   */
     dot(other) {
         return this.x * other.x + this.y * other.y;
     }
     /**
-     * 计算与另一个向量的叉积（2D中返回标量）
-     * @param other 另一个向量
-     * @returns 叉积值
-     */
+   * 计算与另一个向量的叉积（2D中返回标量）
+   * @param other 另一个向量
+   * @returns 叉积值
+   */
     cross(other) {
         return this.x * other.y - this.y * other.x;
     }
     /**
-     * 向量归一化（转换为单位向量）
-     * @returns 当前向量实例（链式调用）
-     */
+   * 向量归一化（转换为单位向量）
+   * @returns 当前向量实例（链式调用）
+   */
     normalize() {
         const len = this.length;
         if (len === 0) {
@@ -159,38 +159,38 @@ export class Vector2 {
         return this.divide(len);
     }
     /**
-     * 获取归一化后的向量（不修改原向量）
-     * @returns 新的单位向量
-     */
+   * 获取归一化后的向量（不修改原向量）
+   * @returns 新的单位向量
+   */
     normalized() {
         return this.clone().normalize();
     }
     // 几何运算
     /**
-     * 计算到另一个向量的距离
-     * @param other 另一个向量
-     * @returns 距离值
-     */
+   * 计算到另一个向量的距离
+   * @param other 另一个向量
+   * @returns 距离值
+   */
     distanceTo(other) {
         const dx = this.x - other.x;
         const dy = this.y - other.y;
         return Math.sqrt(dx * dx + dy * dy);
     }
     /**
-     * 计算到另一个向量的距离平方
-     * @param other 另一个向量
-     * @returns 距离平方值
-     */
+   * 计算到另一个向量的距离平方
+   * @param other 另一个向量
+   * @returns 距离平方值
+   */
     distanceToSquared(other) {
         const dx = this.x - other.x;
         const dy = this.y - other.y;
         return dx * dx + dy * dy;
     }
     /**
-     * 计算与另一个向量的夹角（弧度）
-     * @param other 另一个向量
-     * @returns 夹角（0到π）
-     */
+   * 计算与另一个向量的夹角（弧度）
+   * @param other 另一个向量
+   * @returns 夹角（0到π）
+   */
     angleTo(other) {
         const dot = this.dot(other);
         const lenProduct = this.length * other.length;
@@ -199,10 +199,10 @@ export class Vector2 {
         return Math.acos(Math.max(-1, Math.min(1, dot / lenProduct)));
     }
     /**
-     * 计算向量在另一个向量上的投影
-     * @param onto 投影目标向量
-     * @returns 新的投影向量
-     */
+   * 计算向量在另一个向量上的投影
+   * @param onto 投影目标向量
+   * @returns 新的投影向量
+   */
     projectOnto(onto) {
         const dot = this.dot(onto);
         const lenSq = onto.lengthSquared;
@@ -211,10 +211,10 @@ export class Vector2 {
         return onto.clone().multiply(dot / lenSq);
     }
     /**
-     * 计算向量在另一个向量上的投影长度
-     * @param onto 投影目标向量
-     * @returns 投影长度（带符号）
-     */
+   * 计算向量在另一个向量上的投影长度
+   * @param onto 投影目标向量
+   * @returns 投影长度（带符号）
+   */
     projectOntoLength(onto) {
         const len = onto.length;
         if (len === 0)
@@ -222,49 +222,59 @@ export class Vector2 {
         return this.dot(onto) / len;
     }
     /**
-     * 获取垂直向量（逆时针旋转90度）
+     * 获取垂直向量（顺时针旋转90度）
+     * Get perpendicular vector (clockwise 90 degrees)
      * @returns 新的垂直向量
      */
     perpendicular() {
-        return new Vector2(-this.y, this.x);
+        // Clockwise 90° rotation: (x, y) -> (y, -x)
+        // 顺时针旋转 90°
+        return new Vector2(this.y, -this.x);
     }
     // 变换操作
     /**
-     * 向量旋转
+     * 向量旋转（顺时针为正）
+     * Rotate vector (clockwise positive)
+     *
+     * 使用左手坐标系约定：正角度 = 顺时针旋转
+     * Uses left-hand coordinate system: positive angle = clockwise
+     *
      * @param angle 旋转角度（弧度）
      * @returns 当前向量实例（链式调用）
      */
     rotate(angle) {
         const cos = Math.cos(angle);
         const sin = Math.sin(angle);
-        const x = this.x * cos - this.y * sin;
-        const y = this.x * sin + this.y * cos;
+        // Clockwise rotation: x' = x*cos + y*sin, y' = -x*sin + y*cos
+        // 顺时针旋转公式
+        const x = this.x * cos + this.y * sin;
+        const y = -this.x * sin + this.y * cos;
         this.x = x;
         this.y = y;
         return this;
     }
     /**
-     * 获取旋转后的向量（不修改原向量）
-     * @param angle 旋转角度（弧度）
-     * @returns 新的旋转后向量
-     */
+   * 获取旋转后的向量（不修改原向量）
+   * @param angle 旋转角度（弧度）
+   * @returns 新的旋转后向量
+   */
     rotated(angle) {
         return this.clone().rotate(angle);
     }
     /**
-     * 围绕一个点旋转
-     * @param center 旋转中心点
-     * @param angle 旋转角度（弧度）
-     * @returns 当前向量实例（链式调用）
-     */
+   * 围绕一个点旋转
+   * @param center 旋转中心点
+   * @param angle 旋转角度（弧度）
+   * @returns 当前向量实例（链式调用）
+   */
     rotateAround(center, angle) {
         return this.subtract(center).rotate(angle).add(center);
     }
     /**
-     * 反射向量（关于法线）
-     * @param normal 法线向量（应为单位向量）
-     * @returns 当前向量实例（链式调用）
-     */
+   * 反射向量（关于法线）
+   * @param normal 法线向量（应为单位向量）
+   * @returns 当前向量实例（链式调用）
+   */
     reflect(normal) {
         const dot = this.dot(normal);
         this.x -= 2 * dot * normal.x;
@@ -272,30 +282,30 @@ export class Vector2 {
         return this;
     }
     /**
-     * 获取反射后的向量（不修改原向量）
-     * @param normal 法线向量（应为单位向量）
-     * @returns 新的反射向量
-     */
+   * 获取反射后的向量（不修改原向量）
+   * @param normal 法线向量（应为单位向量）
+   * @returns 新的反射向量
+   */
     reflected(normal) {
         return this.clone().reflect(normal);
     }
     // 插值和限制
     /**
-     * 线性插值
-     * @param target 目标向量
-     * @param t 插值参数（0到1）
-     * @returns 当前向量实例（链式调用）
-     */
+   * 线性插值
+   * @param target 目标向量
+   * @param t 插值参数（0到1）
+   * @returns 当前向量实例（链式调用）
+   */
     lerp(target, t) {
         this.x += (target.x - this.x) * t;
         this.y += (target.y - this.y) * t;
         return this;
     }
     /**
-     * 限制向量长度
-     * @param maxLength 最大长度
-     * @returns 当前向量实例（链式调用）
-     */
+   * 限制向量长度
+   * @param maxLength 最大长度
+   * @returns 当前向量实例（链式调用）
+   */
     clampLength(maxLength) {
         const lenSq = this.lengthSquared;
         if (lenSq > maxLength * maxLength) {
@@ -304,11 +314,11 @@ export class Vector2 {
         return this;
     }
     /**
-     * 限制向量分量
-     * @param min 最小值向量
-     * @param max 最大值向量
-     * @returns 当前向量实例（链式调用）
-     */
+   * 限制向量分量
+   * @param min 最小值向量
+   * @param max 最大值向量
+   * @returns 当前向量实例（链式调用）
+   */
     clamp(min, max) {
         this.x = Math.max(min.x, Math.min(max.x, this.x));
         this.y = Math.max(min.y, Math.min(max.y, this.y));
@@ -316,144 +326,144 @@ export class Vector2 {
     }
     // 比较操作
     /**
-     * 检查两个向量是否相等
-     * @param other 另一个向量
-     * @param epsilon 容差，默认为Number.EPSILON
-     * @returns 是否相等
-     */
+   * 检查两个向量是否相等
+   * @param other 另一个向量
+   * @param epsilon 容差，默认为Number.EPSILON
+   * @returns 是否相等
+   */
     equals(other, epsilon = Number.EPSILON) {
         return Math.abs(this.x - other.x) < epsilon &&
             Math.abs(this.y - other.y) < epsilon;
     }
     /**
-     * 检查两个向量是否完全相等
-     * @param other 另一个向量
-     * @returns 是否完全相等
-     */
+   * 检查两个向量是否完全相等
+   * @param other 另一个向量
+   * @returns 是否完全相等
+   */
     exactEquals(other) {
         return this.x === other.x && this.y === other.y;
     }
     // 静态方法
     /**
-     * 向量加法（静态方法）
-     * @param a 向量a
-     * @param b 向量b
-     * @returns 新的结果向量
-     */
+   * 向量加法（静态方法）
+   * @param a 向量a
+   * @param b 向量b
+   * @returns 新的结果向量
+   */
     static add(a, b) {
         return new Vector2(a.x + b.x, a.y + b.y);
     }
     /**
-     * 向量减法（静态方法）
-     * @param a 向量a
-     * @param b 向量b
-     * @returns 新的结果向量
-     */
+   * 向量减法（静态方法）
+   * @param a 向量a
+   * @param b 向量b
+   * @returns 新的结果向量
+   */
     static subtract(a, b) {
         return new Vector2(a.x - b.x, a.y - b.y);
     }
     /**
-     * 向量数乘（静态方法）
-     * @param vector 向量
-     * @param scalar 标量
-     * @returns 新的结果向量
-     */
+   * 向量数乘（静态方法）
+   * @param vector 向量
+   * @param scalar 标量
+   * @returns 新的结果向量
+   */
     static multiply(vector, scalar) {
         return new Vector2(vector.x * scalar, vector.y * scalar);
     }
     /**
-     * 向量点积（静态方法）
-     * @param a 向量a
-     * @param b 向量b
-     * @returns 点积值
-     */
+   * 向量点积（静态方法）
+   * @param a 向量a
+   * @param b 向量b
+   * @returns 点积值
+   */
     static dot(a, b) {
         return a.x * b.x + a.y * b.y;
     }
     /**
-     * 向量叉积（静态方法）
-     * @param a 向量a
-     * @param b 向量b
-     * @returns 叉积值
-     */
+   * 向量叉积（静态方法）
+   * @param a 向量a
+   * @param b 向量b
+   * @returns 叉积值
+   */
     static cross(a, b) {
         return a.x * b.y - a.y * b.x;
     }
     /**
-     * 计算两点间距离（静态方法）
-     * @param a 点a
-     * @param b 点b
-     * @returns 距离值
-     */
+   * 计算两点间距离（静态方法）
+   * @param a 点a
+   * @param b 点b
+   * @returns 距离值
+   */
     static distance(a, b) {
         const dx = a.x - b.x;
         const dy = a.y - b.y;
         return Math.sqrt(dx * dx + dy * dy);
     }
     /**
-     * 线性插值（静态方法）
-     * @param a 起始向量
-     * @param b 目标向量
-     * @param t 插值参数（0到1）
-     * @returns 新的插值结果向量
-     */
+   * 线性插值（静态方法）
+   * @param a 起始向量
+   * @param b 目标向量
+   * @param t 插值参数（0到1）
+   * @returns 新的插值结果向量
+   */
     static lerp(a, b, t) {
         return new Vector2(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t);
     }
     /**
-     * 从角度创建单位向量（静态方法）
-     * @param angle 角度（弧度）
-     * @returns 新的单位向量
-     */
+   * 从角度创建单位向量（静态方法）
+   * @param angle 角度（弧度）
+   * @returns 新的单位向量
+   */
     static fromAngle(angle) {
         return new Vector2(Math.cos(angle), Math.sin(angle));
     }
     /**
-     * 从极坐标创建向量（静态方法）
-     * @param length 长度
-     * @param angle 角度（弧度）
-     * @returns 新的向量
-     */
+   * 从极坐标创建向量（静态方法）
+   * @param length 长度
+   * @param angle 角度（弧度）
+   * @returns 新的向量
+   */
     static fromPolar(length, angle) {
         return new Vector2(length * Math.cos(angle), length * Math.sin(angle));
     }
     /**
-     * 获取两个向量中的最小分量向量（静态方法）
-     * @param a 向量a
-     * @param b 向量b
-     * @returns 新的最小分量向量
-     */
+   * 获取两个向量中的最小分量向量（静态方法）
+   * @param a 向量a
+   * @param b 向量b
+   * @returns 新的最小分量向量
+   */
     static min(a, b) {
         return new Vector2(Math.min(a.x, b.x), Math.min(a.y, b.y));
     }
     /**
-     * 获取两个向量中的最大分量向量（静态方法）
-     * @param a 向量a
-     * @param b 向量b
-     * @returns 新的最大分量向量
-     */
+   * 获取两个向量中的最大分量向量（静态方法）
+   * @param a 向量a
+   * @param b 向量b
+   * @returns 新的最大分量向量
+   */
     static max(a, b) {
         return new Vector2(Math.max(a.x, b.x), Math.max(a.y, b.y));
     }
     // 字符串转换
     /**
-     * 转换为字符串
-     * @returns 字符串表示
-     */
+   * 转换为字符串
+   * @returns 字符串表示
+   */
     toString() {
         return `Vector2(${this.x.toFixed(3)}, ${this.y.toFixed(3)})`;
     }
     /**
-     * 转换为数组
-     * @returns [x, y] 数组
-     */
+   * 转换为数组
+   * @returns [x, y] 数组
+   */
     toArray() {
         return [this.x, this.y];
     }
     /**
-     * 转换为普通对象
-     * @returns {x, y} 对象
-     */
+   * 转换为普通对象
+   * @returns {x, y} 对象
+   */
     toObject() {
         return { x: this.x, y: this.y };
     }