scoreboard_remove(obj, key) will remove the key from the objective. Fixes #255

docs/scarpet/Full.md

@@ -2217,11 +2217,15 @@ It returns a `map` with a report indicating how many chunks were affected, and h
 
 These functions help scan larger areas of blocks without using generic loop functions, like nested `loop`.
 
-### `scan(cx, cy, cz, dx, dy, dz, px?, py?, pz?, expr)`
+### `scan(cx, cy, cz, dx, dy, dz, px?, py?, pz?, expr)`, `scan(center, range, lower_range?, expr)`
 
-Evaluates expression over area of blocks defined by its center (`cx, cy, cz`), expanded in all directions 
-by `dx, dy, dz` blocks, or optionally in negative with `d` coords, and `p` coords in positive values. `expr` 
-receives `_x, _y, _z` as coords of current analyzed block and `_`, which represents the block itself.
+Evaluates expression over area of blocks defined by its center `center = (cx, cy, cz)`, expanded in all directions 
+by `range = (dx, dy, dz)` blocks, or optionally in negative with `range` coords, and `upper_range` coords in 
+positive values.
+`center` can be defined either as a three coordinates, list of three coords, or block value.
+`range` and `lower_range` can have the same representations, just if its a block, it computes the distance to the center
+as range instead of taking the values as is.
+`expr` receives `_x, _y, _z` as coords of current analyzed block and `_`, which represents the block itself.
 
 Returns number of successful evaluations of `expr` (with `true` boolean result) unless called in void context, 
 which would cause the expression not be evaluated for their boolean value.
@@ -2951,9 +2955,12 @@ scoreboard_add('counter')
 scoreboard_add('lvl','level')
 </pre>
 
-### `scoreboard_remove(objective)`
+### `scoreboard_remove(objective)` `scoreboard_remove(objective, key)`
 
-Removes an objective. Returns `true` if objective has existed and has been removed.
+Removes an entire objective, or an entry in the scoreboard associated with the key. 
+Returns `true` if objective has existed and has been removed, or previous
+value of the scoreboard if players score is removed. Returns `null` if objective didn't exist, or a key was missing
+for the objective.
 
 ### `scoreboard_display(place, objective)`
 

docs/scarpet/api/Scoreboard.md

@@ -17,9 +17,12 @@ scoreboard_add('counter')
 scoreboard_add('lvl','level')
 </pre>
 
-### `scoreboard_remove(objective)`
+### `scoreboard_remove(objective)` `scoreboard_remove(objective, key)`
 
-Removes an objective. Returns `true` if objective has existed and has been removed.
+Removes an entire objective, or an entry in the scoreboard associated with the key. 
+Returns `true` if objective has existed and has been removed, or previous
+value of the scoreboard if players score is removed. Returns `null` if objective didn't exist, or a key was missing
+for the objective.
 
 ### `scoreboard_display(place, objective)`
 

src/main/java/carpet/script/CarpetExpression.java

@@ -1296,6 +1296,26 @@ public class CarpetExpression
 
     }
 
+    private static String getScoreboardKeyFromValue(Value keyValue)
+    {
+        if (keyValue instanceof EntityValue)
+        {
+            Entity e = ((EntityValue) keyValue).getEntity();
+            if (e instanceof PlayerEntity)
+            {
+                return e.getName().getString();
+            }
+            else
+            {
+                return e.getUuidAsString();
+            }
+        }
+        else
+        {
+            return keyValue.getString();
+        }
+    }
+
     private void API_Scoreboard()
     {
         // scoreboard(player,'objective')
@@ -1317,24 +1337,7 @@ public class CarpetExpression
                 Value ret = ListValue.wrap(scoreboard.getAllPlayerScores(objective).stream().map(s -> new StringValue(s.getPlayerName())).collect(Collectors.toList()));
                 return (_c, _t) -> ret;
             }
-            String key;
-            Value keyValue = lv.get(1).evalValue(c);
-            if (keyValue instanceof EntityValue)
-            {
-                Entity e = ((EntityValue) keyValue).getEntity();
-                if (e instanceof PlayerEntity)
-                {
-                    key = e.getDisplayName().getString();
-                }
-                else
-                {
-                    key = e.getUuidAsString();
-                }
-            }
-            else
-            {
-                key = keyValue.getString();
-            }
+            String key = getScoreboardKeyFromValue(lv.get(1).evalValue(c));
             if (!scoreboard.playerHasObjective(key, objective) && lv.size()==2)
                 return LazyValue.NULL;
             ScoreboardPlayerScore scoreboardPlayerScore = scoreboard.getPlayerScore(key, objective);
@@ -1346,15 +1349,24 @@ public class CarpetExpression
             return (_c, _t) -> retval;
         });
 
-        this.expr.addLazyFunction("scoreboard_remove", 1, (c, t, lv)-> {
+        this.expr.addLazyFunction("scoreboard_remove", -1, (c, t, lv)-> {
             CarpetContext cc = (CarpetContext)c;
             Scoreboard scoreboard =  cc.s.getMinecraftServer().getScoreboard();
             String objectiveName = lv.get(0).evalValue(c).getString();
             ScoreboardObjective objective = scoreboard.getObjective(objectiveName);
             if (objective == null)
                 return LazyValue.FALSE;
-            scoreboard.removeObjective(objective);
-            return LazyValue.TRUE;
+            if (lv.size() == 0)
+            {
+                scoreboard.removeObjective(objective);
+                return LazyValue.TRUE;
+            }
+            String key = getScoreboardKeyFromValue(lv.get(1).evalValue(c));
+            if (!scoreboard.playerHasObjective(key, objective)) return LazyValue.NULL;
+            ScoreboardPlayerScore scoreboardPlayerScore = scoreboard.getPlayerScore(key, objective);
+            Value previous = new NumericValue(scoreboardPlayerScore.getScore());
+            scoreboard.resetPlayerScore(key, objective);
+            return (c_, t_) -> previous;
         });
 
         // objective_add('lvl','level')