Add game 'life' api reference (#1569)

docs/SUMMARY.md

@@ -241,6 +241,9 @@
         * [add score](/reference/game/add-score)
         * [score](/reference/game/score)
         * [set score](/reference/game/set-score)
+        * [set life](/reference/game/set-life)
+        * [add life](/reference/game/add-life)
+        * [remove life](/reference/game/remove-life)
         * [start countdown](/reference/game/start-countdown)
         * [game over](/reference/game/game-over)
         * [pause](/reference/game/pause)

docs/lessons/catch-the-egg-game/tutorial.md

@@ -7,7 +7,7 @@ The blocks have been shuffled! Put them back together so that...
 * a basket LED is on the bottom row and can be moved by using the accelerometer `X` data.
 * if the egg LED reaches the last row, reset the egg position to the first row.
 
-```shuffle
+```blocks
 let basketX = 2
 let eggX = 2
 let eggY = 0

docs/reference/game.md

@@ -32,6 +32,14 @@ game.score();
 game.setScore(0);
 ```
 
+## Life
+
+```cards
+game.setLife(0)
+game.addLife(0)
+game.removeLife(0)
+```
+
 ## Game control
 
 ```cards
@@ -47,5 +55,6 @@ game.resume();
 [ifOnEdgeBounce](/reference/game/if-on-edge-bounce), [get](/reference/game/get), [set](/reference/game/set),
 [change](/reference/game/change), [is touching](/reference/game/is-touching) [is touching edge](/reference/game/is-touching-edge),
 [add score](/reference/game/add-score), [score](/reference/game/score), [set score](/reference/game/set-score),
+[set life](/reference/game/set-life), [add life](/reference/game/add-life), [remove life](/reference/game/remove-life),
 [start countdown](/reference/game/start-countdown), [game over](/reference/game/game-over),
 [pause](/reference/game/pause), [resume](/reference/game/resume)

docs/reference/game/add-life.md

@@ -0,0 +1,33 @@
+# add Life
+
+Increase the number of lives remaining by some amount.
+
+```sig
+game.addLife(0)
+```
+
+The life count in the game is increased by the number of lives you say.
+
+## Parameters
+
+* **life**: a [number](/types/number) to remove from the count.
+
+## Example #example
+
+Add `20` more lives to the life count if the player's score reaches `10000` points.
+
+```blocks
+let giveLives = true
+
+if (game.score() > 9999) {
+    if (giveLives) {
+        game.addLife(20)
+        giveLives = false
+    }
+}
+```
+
+## See also #seealso
+
+[set life](/reference/game/set-life),
+[remove life](/reference/game/remove-life)

docs/reference/game/remove-life.md

@@ -0,0 +1,33 @@
+# remove Life
+
+Decrease the number of lives remaining by some amount.
+
+```sig
+game.removeLife(0)
+```
+
+The life count in the game is decreased by the number of lives you say. If the life count reaches `0` when these lives are removed, then the game is over.
+
+## Parameters
+
+* **life**: a [number](/types/number) to remove from the count.
+
+## Example #example
+
+Take away `20` lives count if the player's score reaches `10000` points.
+
+```blocks
+let giveLives = true
+
+if (game.score() > 9999) {
+    if (giveLives) {
+        game.removeLife(20)
+        giveLives = false
+    }
+}
+```
+
+## See also #seealso
+
+[set life](/reference/game/set-life),
+[add life](/reference/game/add-life)

docs/reference/game/set-life.md

@@ -0,0 +1,26 @@
+# set Life
+
+Set the game life count to this amount.
+
+```sig
+game.setLife(0)
+```
+
+Your program has a life counter which you can set to record the number of lives remaining for a player in your game. If you set the life count to `0` or less, the game ends.
+
+## Parameters
+
+* **value**: a [number](/types/number) to set the life count to.
+
+## Example #example
+
+Set the player life count to `9` lives before starting the game.
+
+```blocks
+game.setLife(9)
+```
+
+## See also #seealso
+
+[add life](/reference/game/add-life),
+[remove life](/reference/game/remove-life)

libs/core/game.ts

@@ -168,9 +168,10 @@ namespace game {
 
     /**
      * Sets the current life value
-     * @param value TODO
+     * @param value current life value
      */
-    //% weight=10
+    //% weight=10 help=game/set-life
+    //% blockId=game_set_life block="set life %value" blockGap=8
     export function setLife(value: number): void {
         _life = Math.max(0, value);
         if (_life <= 0) {
@@ -179,10 +180,11 @@ namespace game {
     }
 
     /**
-     * Adds life points to the current life
-     * @param lives TODO
+     * Add life points to the current life amount
+     * @param lives amount of lives to add
      */
-    //% weight=10
+    //% weight=10 help=game/add-life
+    //% blockId=game_add_life block="add life %lives" blockGap=8
     export function addLife(lives: number): void {
         setLife(_life + lives);
     }
@@ -200,11 +202,12 @@ namespace game {
     }
 
     /**
-     * Removes some life
-     * @param life TODO
+     * Remove some life
+     * @param life amount of life to remove
      */
-    //% weight=10
+    //% weight=10 help=game/remove-life
     //% parts="ledmatrix"
+    //% blockId=game_remove_life block="remove life %life" blockGap=8
     export function removeLife(life: number): void {
         setLife(_life - life);
         if (!_paused)