feat: increment (#6)

Co-authored-by: pauloddr <pauloddr@users.noreply.github.com>

README.md

@@ -1,6 +1,6 @@
 # @dimensionalpocket/game-meter
 
-![build](https://github.com/dimensionalpocket/game-meter-js/actions/workflows/node.js.yml/badge.svg) [![Total alerts](https://img.shields.io/lgtm/alerts/g/dimensionalpocket/game-meter-js.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/dimensionalpocket/game-meter-js/alerts/) [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/dimensionalpocket/game-meter-js.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/dimensionalpocket/game-meter-js/context:javascript)
+[![build](https://github.com/dimensionalpocket/game-meter-js/actions/workflows/node.js.yml/badge.svg)](https://github.com/dimensionalpocket/game-meter-js/actions/workflows/node.js.yml) [![Total alerts](https://img.shields.io/lgtm/alerts/g/dimensionalpocket/game-meter-js.svg)](https://lgtm.com/projects/g/dimensionalpocket/game-meter-js/alerts/) [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/dimensionalpocket/game-meter-js.svg)](https://lgtm.com/projects/g/dimensionalpocket/game-meter-js/context:javascript)
 
 A Meter class for Javascript games.
 
@@ -45,8 +45,8 @@ Most methods take an optional `timestamp` argument which is used to regenerate t
 * `set(amount)` - sets the meter to an absolute amount. Will be clamped based on minimum/maximum.
 * `setRegeneration(amount, [timestamp])` - changes regeneration amount.
 * `setTickDuration(duration, [timestamp])` - sets the tick duration. Default is 1 ms (the same as no tick).
-* `increment(amount, [timestamp])` - adds/subtracts from the current amount.
-* `current([timestamp])` - returns the current meter amount, after regeneration.
+* `increment(amount, [timestamp])` - adds to (or subtracts from) the current amount.
+* `current([timestamp])` - returns the current meter amount after regeneration.
 * `regenerate([timestamp])` - regenerates the meter based on time passed after last update.
 
 ## Properties

src/GameMeter.js

@@ -67,6 +67,23 @@ export class GameMeter {
     return this.amount
   }
 
+  /**
+   * Increments or decrements the meter. Returns the changed amount.
+   * @param {number} amount - Amount to increment. Can be negative.
+   * @param {number} [timestamp]
+   * @return {number}
+   */
+  increment (amount, timestamp = Date.now()) {
+    this.regenerate(timestamp)
+
+    var oldAmount = this.amount
+    var newAmount = this.clamp(oldAmount + amount)
+
+    this.amount = newAmount
+
+    return newAmount - oldAmount
+  }
+
   /**
    * Sets a new regeneration amount for this meter.
    * @param {number} regeneration - Amount per second to regenerate. Can also be zero or negative.
@@ -133,24 +150,24 @@ export class GameMeter {
     // so that the new timestamp increase is a multiple of the tick duration.
     this._timestamp = timestamp - (delta % tick)
 
-    var oldCurrent = this.amount
+    var oldAmount = this.amount
 
     // Skip if meter is already filled or depleted.
     if (
-      (regeneration > 0 && oldCurrent >= this.maximum) ||
-      (regeneration < 0 && oldCurrent <= this.minimum)
+      (regeneration > 0 && oldAmount >= this.maximum) ||
+      (regeneration < 0 && oldAmount <= this.minimum)
     ) return 0
 
     // Gain is based on how many ticks passed.
     // Expression in brackets is "regeneration per tick".
     var gain = (regeneration * tick / 1000) * ticks
 
-    var newCurrent = this.clamp(oldCurrent + gain)
+    var newAmount = this.clamp(oldAmount + gain)
 
-    this.amount = newCurrent
+    this.amount = newAmount
 
     // Returns the gain after clamping.
-    return newCurrent - oldCurrent
+    return newAmount - oldAmount
   }
 
   /**

test/GameMeter.js

@@ -92,6 +92,26 @@ describe('GameMeter', function () {
     })
   })
 
+  describe('#increment', function () {
+    before(function () {
+      this.meter1 = new GameMeter({ maximum: 100.0, current: 50.0, regeneration: 1.0, timestamp: 1000 })
+      this.meter2 = new GameMeter({ maximum: 100.0, current: 95.0, regeneration: 1.0 })
+      this.clock.tick(1000)
+      this.result1 = this.meter1.increment(10.0, 2000)
+      this.result2 = this.meter2.increment(10.0)
+    })
+
+    it('regenerates and increments', function () {
+      expect(this.meter1.amount).to.eq(51.0 + 10.0)
+      expect(this.meter2.amount).to.eq(100.0) // maxed out
+    })
+
+    it('returns the incremented amount', function () {
+      expect(this.result1).to.eq(10.0)
+      expect(this.result2).to.eq(4.0) // increment before maxing out
+    })
+  })
+
   describe('#setRegeneration', function () {
     context('when previous regeneration is zero', function () {
       before(function () {