add angleToTarget

straker · Jan 8, 2020 · 1668c0f · 1668c0f
1 parent 599aeb7
commit 1668c0f
Show file tree

Hide file tree

Showing 16 changed files with 186 additions and 36 deletions.
diff --git a/docs/api/helpers.html b/docs/api/helpers.html
@@ -106,6 +106,11 @@ <h2 id="toc"><a href="#toc" class="section-link">Table of Contents<span aria-hid
             <li>
               <h3 id="methods">Methods</h3>
               <ul aria-labelledby="methods">
+                <li>
+                  <a href="api/helpers#angleToTarget">
+                    <span>angleToTarget(&#8203;source, target)</span>
+                  </a>
+                </li>
                 <li>
                   <a href="api/helpers#clamp">
                     <span>clamp(&#8203;min, max, value)</span>
@@ -142,6 +147,35 @@ <h3 id="methods">Methods</h3>
         </section>
 
 
+        <section>
+          <h2 id="angleToTarget">
+            <a href="api/helpers#angleToTarget" class="section-link">
+              <span>angleToTarget(&#8203;source, target)</span>
+              <span aria-hidden="true">#</span>
+            </a>
+          </h2>
+
+          <p>Return the angle (in radians) from one point to another point.</p>
+          <h3 id="title-angleToTarget"><span class="visually-hidden">angleToTarget</span> Parameters</span></h3>
+          <dl aria-labelledby="title-angleToTarget">
+            <dt>
+              <code>source</code>
+
+            </dt>
+            <dd><p>Object. The source point.</p>
+          </dd>
+            <dt>
+              <code>target</code>
+
+            </dt>
+            <dd><p>Object. The target point.</p>
+          </dd>
+          </dl>
+
+          <h3><span class="visually-hidden">angleToTarget</span> Return value</h3>
+          <p><p>angle (in radians)from the source point to the target point.</p>
+          </p>
+        </section>
         <section>
           <h2 id="clamp">
             <a href="api/helpers#clamp" class="section-link">

diff --git a/docs/api/vector.html b/docs/api/vector.html
@@ -199,7 +199,7 @@ <h2 id="add">
             </a>
           </h2>
 
-          <p>Calculate the addition of the current vector with the passed in vector.</p>
+          <p>Calculate the addition of the current vector with the given vector.</p>
           <h3 id="title-add"><span class="visually-hidden">add</span> Parameters</span></h3>
           <dl aria-labelledby="title-add">
             <dt>
@@ -222,7 +222,7 @@ <h2 id="angle">
             </a>
           </h2>
 
-          <p>Calculate the angle (in radians) between the current vector and the passed in vector. Requires the Vector <a href="/api/vector#dot">dot</a> and <a href="/api/vector#length">length</a> functions.</p>
+          <p>Calculate the angle (in radians) between the current vector and the given vector. Requires the Vector <a href="/api/vector#dot">dot</a> and <a href="/api/vector#length">length</a> functions.</p>
           <h3 id="title-angle"><span class="visually-hidden">angle</span> Parameters</span></h3>
           <dl aria-labelledby="title-angle">
             <dt>
@@ -336,7 +336,7 @@ <h2 id="distance">
             </a>
           </h2>
 
-          <p>Calculate the distance between the current vector and the passed in vector.</p>
+          <p>Calculate the distance between the current vector and the given vector.</p>
           <h3 id="title-distance"><span class="visually-hidden">distance</span> Parameters</span></h3>
           <dl aria-labelledby="title-distance">
             <dt>
@@ -359,7 +359,7 @@ <h2 id="dot">
             </a>
           </h2>
 
-          <p>Calculate the dot product of the current vector with the passed in vector.</p>
+          <p>Calculate the dot product of the current vector with the given vector.</p>
           <h3 id="title-dot"><span class="visually-hidden">dot</span> Parameters</span></h3>
           <dl aria-labelledby="title-dot">
             <dt>
@@ -433,7 +433,7 @@ <h2 id="subtract">
             </a>
           </h2>
 
-          <p>Calculate the subtraction of the current vector with the passed in vector.</p>
+          <p>Calculate the subtraction of the current vector with the given vector.</p>
           <h3 id="title-subtract"><span class="visually-hidden">subtract</span> Parameters</span></h3>
           <dl aria-labelledby="title-subtract">
             <dt>

diff --git a/docs/assets/js/kontra.js b/docs/assets/js/kontra.js
diff --git a/kontra.d.ts b/kontra.d.ts
@@ -154,6 +154,7 @@ declare namespace kontra {
   var GameLoop: GameLoopConstructor
   function degToRad(deg: number): number;
   function radToDeg(rad: number): number;
+  function angleToTarget(source: {x: number, y: number}, target: {x: number, y: number}): number;
   function randInt(min: number, max: number): number;
   function lerp(start: number, end: number, percent: number): number;
   function inverseLerp(start: number, end: number, value: number): number;

diff --git a/kontra.js b/kontra.js
@@ -794,7 +794,7 @@ class Vector {
   }
 
   /**
-   * Calculate the addition of the current vector with the passed in vector.
+   * Calculate the addition of the current vector with the given vector.
    * @memberof Vector
    * @function add
    *
@@ -812,7 +812,7 @@ class Vector {
 
   // @ifdef VECTOR_SUBTRACT
   /**
-   * Calculate the subtraction of the current vector with the passed in vector.
+   * Calculate the subtraction of the current vector with the given vector.
    * @memberof Vector
    * @function subtract
    *
@@ -868,7 +868,7 @@ class Vector {
 
   // @ifdef VECTOR_DOT
   /**
-   * Calculate the dot product of the current vector with the passed in vector.
+   * Calculate the dot product of the current vector with the given vector.
    * @memberof Vector
    * @function dot
    *
@@ -896,7 +896,7 @@ class Vector {
 
   // @ifdef VECTOR_DISTANCE
   /**
-   * Calculate the distance between the current vector and the passed in vector.
+   * Calculate the distance between the current vector and the given vector.
    * @memberof Vector
    * @function distance
    *
@@ -913,7 +913,7 @@ class Vector {
   // @ifdef VECTOR_DOT
   // @ifdef VECTOR_LENGTH
   /**
-   * Calculate the angle (in radians) between the current vector and the passed in vector. Requires the Vector [dot](/api/vector#dot) and [length](/api/vector#length) functions.
+   * Calculate the angle (in radians) between the current vector and the given vector. Requires the Vector [dot](/api/vector#dot) and [length](/api/vector#length) functions.
    * @memberof Vector
    * @function angle
    *
@@ -2685,6 +2685,24 @@ function radToDeg(rad) {
   return rad * 180 / Math.PI;
 }
 
+/**
+ * Return the angle (in radians) from one point to another point.
+ * @function angleToTarget
+ *
+ * @param {{x: Number, y: Number}} source - The source point.
+ * @param {{x: Number, y: Number}} target - The target point.
+ *
+ * @returns {Number} angle (in radians)from the source point to the target point.
+ */
+function angleToTarget(source, target) {
+
+  // atan2 returns the counter-clockwise angle in respect to the x-axis, but
+  // the canvas rotation system is based on the y-axis (rotation of 0 = up).
+  // so we need to add a quarter rotation to return a counter-clockwise
+  // rotation in respect to the y-axis
+  return Math.atan2(target.y - source.y, target.x - source.x) + Math.PI / 2;
+}
+
 /**
  * Return a random integer between a minimum (inclusive) and maximum (inclusive) integer.
  * @see https://stackoverflow.com/a/1527820/2124254
@@ -4934,6 +4952,7 @@ let kontra = {
 
   degToRad,
   radToDeg,
+  angleToTarget,
   randInt,
   lerp,
   inverseLerp,

diff --git a/kontra.min.js b/kontra.min.js
diff --git a/kontra.min.mjs b/kontra.min.mjs
diff --git a/kontra.mjs b/kontra.mjs
@@ -791,7 +791,7 @@ class Vector {
   }
 
   /**
-   * Calculate the addition of the current vector with the passed in vector.
+   * Calculate the addition of the current vector with the given vector.
    * @memberof Vector
    * @function add
    *
@@ -809,7 +809,7 @@ class Vector {
 
   // @ifdef VECTOR_SUBTRACT
   /**
-   * Calculate the subtraction of the current vector with the passed in vector.
+   * Calculate the subtraction of the current vector with the given vector.
    * @memberof Vector
    * @function subtract
    *
@@ -865,7 +865,7 @@ class Vector {
 
   // @ifdef VECTOR_DOT
   /**
-   * Calculate the dot product of the current vector with the passed in vector.
+   * Calculate the dot product of the current vector with the given vector.
    * @memberof Vector
    * @function dot
    *
@@ -893,7 +893,7 @@ class Vector {
 
   // @ifdef VECTOR_DISTANCE
   /**
-   * Calculate the distance between the current vector and the passed in vector.
+   * Calculate the distance between the current vector and the given vector.
    * @memberof Vector
    * @function distance
    *
@@ -910,7 +910,7 @@ class Vector {
   // @ifdef VECTOR_DOT
   // @ifdef VECTOR_LENGTH
   /**
-   * Calculate the angle (in radians) between the current vector and the passed in vector. Requires the Vector [dot](/api/vector#dot) and [length](/api/vector#length) functions.
+   * Calculate the angle (in radians) between the current vector and the given vector. Requires the Vector [dot](/api/vector#dot) and [length](/api/vector#length) functions.
    * @memberof Vector
    * @function angle
    *
@@ -2682,6 +2682,24 @@ function radToDeg(rad) {
   return rad * 180 / Math.PI;
 }
 
+/**
+ * Return the angle (in radians) from one point to another point.
+ * @function angleToTarget
+ *
+ * @param {{x: Number, y: Number}} source - The source point.
+ * @param {{x: Number, y: Number}} target - The target point.
+ *
+ * @returns {Number} angle (in radians)from the source point to the target point.
+ */
+function angleToTarget(source, target) {
+
+  // atan2 returns the counter-clockwise angle in respect to the x-axis, but
+  // the canvas rotation system is based on the y-axis (rotation of 0 = up).
+  // so we need to add a quarter rotation to return a counter-clockwise
+  // rotation in respect to the y-axis
+  return Math.atan2(target.y - source.y, target.x - source.x) + Math.PI / 2;
+}
+
 /**
  * Return a random integer between a minimum (inclusive) and maximum (inclusive) integer.
  * @see https://stackoverflow.com/a/1527820/2124254
@@ -4931,6 +4949,7 @@ let kontra = {
 
   degToRad,
   radToDeg,
+  angleToTarget,
   randInt,
   lerp,
   inverseLerp,
@@ -4969,5 +4988,5 @@ let kontra = {
   Vector: Vector$1
 };
 
-export { Animation$1 as Animation, imageAssets, audioAssets, dataAssets, setImagePath, setAudioPath, setDataPath, loadImage, loadAudio, loadData, load, Button$1 as Button, collides, init, getCanvas, getContext, on, off, emit, GameLoop, GameObject$1 as GameObject, degToRad, radToDeg, randInt, lerp, inverseLerp, clamp, keyMap, initKeys, bindKeys, unbindKeys, keyPressed, registerPlugin, unregisterPlugin, extendObject, initPointer, pointer, track, untrack, pointerOver, onPointerDown, onPointerUp, pointerPressed, Pool$1 as Pool, Quadtree$1 as Quadtree, Scene$1 as Scene, Sprite$1 as Sprite, SpriteSheet$1 as SpriteSheet, setStoreItem, getStoreItem, Text$1 as Text, TileEngine, Vector$1 as Vector };
+export { Animation$1 as Animation, imageAssets, audioAssets, dataAssets, setImagePath, setAudioPath, setDataPath, loadImage, loadAudio, loadData, load, Button$1 as Button, collides, init, getCanvas, getContext, on, off, emit, GameLoop, GameObject$1 as GameObject, degToRad, radToDeg, angleToTarget, randInt, lerp, inverseLerp, clamp, keyMap, initKeys, bindKeys, unbindKeys, keyPressed, registerPlugin, unregisterPlugin, extendObject, initPointer, pointer, track, untrack, pointerOver, onPointerDown, onPointerUp, pointerPressed, Pool$1 as Pool, Quadtree$1 as Quadtree, Scene$1 as Scene, Sprite$1 as Sprite, SpriteSheet$1 as SpriteSheet, setStoreItem, getStoreItem, Text$1 as Text, TileEngine, Vector$1 as Vector };
 export default kontra;
diff --git a/src/helpers.js b/src/helpers.js
@@ -32,6 +32,24 @@ export function radToDeg(rad) {
   return rad * 180 / Math.PI;
 }
 
+/**
+ * Return the angle (in radians) from one point to another point.
+ * @function angleToTarget
+ *
+ * @param {{x: Number, y: Number}} source - The source point.
+ * @param {{x: Number, y: Number}} target - The target point.
+ *
+ * @returns {Number} angle (in radians)from the source point to the target point.
+ */
+export function angleToTarget(source, target) {
+
+  // atan2 returns the counter-clockwise angle in respect to the x-axis, but
+  // the canvas rotation system is based on the y-axis (rotation of 0 = up).
+  // so we need to add a quarter rotation to return a counter-clockwise
+  // rotation in respect to the y-axis
+  return Math.atan2(target.y - source.y, target.x - source.x) + Math.PI / 2;
+}
+
 /**
  * Return a random integer between a minimum (inclusive) and maximum (inclusive) integer.
  * @see https://stackoverflow.com/a/1527820/2124254

diff --git a/src/kontra.defaults.js b/src/kontra.defaults.js
@@ -20,6 +20,7 @@ import GameObject from './gameObject.js'
 import {
   radToDeg,
   degToRad,
+  angleToTarget,
   randInt,
   lerp,
   inverseLerp,
@@ -78,6 +79,7 @@ let kontra = {
 
   degToRad,
   radToDeg,
+  angleToTarget,
   randInt,
   lerp,
   inverseLerp,

diff --git a/src/kontra.js b/src/kontra.js
@@ -20,6 +20,7 @@ export { default as GameObject } from './gameObject.js'
 export {
   degToRad,
   radToDeg,
+  angleToTarget,
   randInt,
   lerp,
   inverseLerp,

diff --git a/src/vector.js b/src/vector.js
@@ -31,7 +31,7 @@ class Vector {
   }
 
   /**
-   * Calculate the addition of the current vector with the passed in vector.
+   * Calculate the addition of the current vector with the given vector.
    * @memberof Vector
    * @function add
    *
@@ -49,7 +49,7 @@ class Vector {
 
   // @ifdef VECTOR_SUBTRACT
   /**
-   * Calculate the subtraction of the current vector with the passed in vector.
+   * Calculate the subtraction of the current vector with the given vector.
    * @memberof Vector
    * @function subtract
    *
@@ -105,7 +105,7 @@ class Vector {
 
   // @ifdef VECTOR_DOT
   /**
-   * Calculate the dot product of the current vector with the passed in vector.
+   * Calculate the dot product of the current vector with the given vector.
    * @memberof Vector
    * @function dot
    *
@@ -133,7 +133,7 @@ class Vector {
 
   // @ifdef VECTOR_DISTANCE
   /**
-   * Calculate the distance between the current vector and the passed in vector.
+   * Calculate the distance between the current vector and the given vector.
    * @memberof Vector
    * @function distance
    *
@@ -150,7 +150,7 @@ class Vector {
   // @ifdef VECTOR_DOT
   // @ifdef VECTOR_LENGTH
   /**
-   * Calculate the angle (in radians) between the current vector and the passed in vector. Requires the Vector [dot](/api/vector#dot) and [length](/api/vector#length) functions.
+   * Calculate the angle (in radians) between the current vector and the given vector. Requires the Vector [dot](/api/vector#dot) and [length](/api/vector#length) functions.
    * @memberof Vector
    * @function angle
    *

diff --git a/test/typings/helpers.ts b/test/typings/helpers.ts
@@ -1,8 +1,14 @@
 import * as kontra from '../../kontra.js';
 
-let degrees: number = kontra.degToRad(22.35);
-let radians: number = kontra.radToDeg(0.39);
-let int: number = kontra.randInt(10, 20);
-let value: number = kontra.lerp(10, 20, 0.5);
-let percent: number = kontra.inverseLerp(10, 20, 15);
+let degToRad: number = kontra.degToRad(22.35);
+let radToDeg: number = kontra.radToDeg(0.39);
+
+let sourceSprite = kontra.Sprite({x: 0, y: 0});
+let targetSprite = kontra.Sprite({x: 10, y: 10});
+let angleToTargetXY: number = kontra.angleToTarget({x: 0, y: 0}, {x: 10, y: 10});
+let angleToTargetSprite = kontra.angleToTarget(sourceSprite, targetSprite);
+
+let randInt: number = kontra.randInt(10, 20);
+let lerp: number = kontra.lerp(10, 20, 0.5);
+let inverseLerp: number = kontra.inverseLerp(10, 20, 15);
 let clamp: number = kontra.clamp(10, 20, 30);