Merge branch 'master' into display-title-additions

docs/scarpet/api/Auxiliary.md

@@ -4,29 +4,40 @@ Collection of other methods that control smaller, yet still important aspects of
 
 ## Sounds
 
-### `sound(name, pos, volume?, pitch?, mixer?)`
+### `sound()`, `sound(name, pos, volume?, pitch?, mixer?)`
 
 Plays a specific sound `name`, at block or position `pos`, with optional `volume` and modified `pitch`, and under
 optional `mixer`. Default values for `volume`, `pitch` and `mixer` are `1.0`, `1.0`, and `master`. 
 Valid mixer options are `master`, `music`, `record`, `weather`, `block`, `hostile`,`neutral`, `player`, `ambient`
 and `voice`. `pos` can be either a block, triple of coords, or a list of thee numbers. Uses the same options as a
  corresponding `playsound` command.
+ 
+Used with no arguments, return the list of available sound names.
+ 
+Throws `unknown_sound` if sound doesn't exist.
 
 ## Particles
 
-### `particle(name, pos, count?. spread?, speed?, player?)`
+### `particle()`, `particle(name, pos, count?. spread?, speed?, player?)`
 
 Renders a cloud of particles `name` centered around `pos` position, by default `count` 10 of them, default `speed` 
 of 0, and to all players nearby, but these options can be changed via optional arguments. Follow vanilla `/particle` 
 command on details on those options. Valid particle names are 
 for example `'angry_villager', 'item diamond', 'block stone', 'dust 0.8 0.1 0.1 4'`.
 
+Used with no arguments, return the list of available particle names. Note that some of the names do not correspond to a valid
+particle that can be fed to `particle(...)` function due to a fact that some particles need more configuration
+to be valid, like `dust`, `block` etc. Should be used as a reference only.
+
+Throws `unknown_particle` if particle doesn't exist.
+
 ### `particle_line(name, pos, pos2, density?, player?)`
 
 Renders a line of particles from point `pos` to `pos2` with supplied density (defaults to 1), which indicates how far 
 apart you would want particles to appear, so `0.1` means one every 10cm. If a player (or player name) is supplied, only
 that player will receive particles.
 
+Throws `unknown_particle` if particle doesn't exist.
 
 ### `particle_box(name, pos, pos2, density?, player?)`
 ### `particle_rect` (deprecated)
@@ -34,6 +45,8 @@ that player will receive particles.
 Renders a cuboid of particles between points `pos` and `pos2` with supplied density. If a player (or player name) is 
 supplied, only that player will receive particles.
 
+Throws `unknown_particle` if particle doesn't exist.
+
 ## Markers
 
 ### `draw_shape(shape, duration, key?, value?, ... )`, 
@@ -67,7 +80,7 @@ Optional shared shape attributes:
  in the form of `0xRRGGBBAA`, with the default of `-1`, so white opaque, or `0xFFFFFFFF`.
  * `player` - name or player entity to send the shape to. If specified, the shapes will appear only for the specified
  player, otherwise it will be send to all players in the dimension.
- * `line` - line thickness, defaults to 2.0pt
+ * `line` - (Deprecated) line thickness, defaults to 2.0pt. Not supported in 1.17's 3.2 core GL renderer.
  * `fill` - color for the faces, defaults to no fill. Use `color` attribute format
  * `follow` - entity, or player name. Shape will follow an entity instead of being static.
    Follow attribute requires all positional arguments to be relative to the entity and disallow
@@ -101,7 +114,7 @@ Available shapes:
      * `align` - text alignment with regards to `pos`. Default is `center` (displayed text is
      centered with respect to `pos`), `left` (`pos` indicates beginning of text), and `right` (`pos`
      indicates the end of text).
-     * `tilt` - additional rotation of the text on the canvas
+     * `tilt`, `lean`, `turn` - additional rotations of the text on the canvas along all three axis
      * `indent`, `height`, `raise` - offsets for text rendering on X (`indent`), Y (`height`), and Z axis (`raise`) 
      with regards to the plane of the text. One unit of these corresponds to 1 line spacing, which
      can be used to display multiple lines of text bound to the same `pos` 
@@ -296,7 +309,8 @@ Resource is identified by a path to the file.
 A path can contain letters, numbers, characters `-`, `+`, or `_`, and a folder separator: `'/'`. Any other characters are stripped
 from the name. Empty descriptors are invalid, except for `list_files` where it means the root folder.
  Do not add file extensions to the descriptor - extensions are inferred
-based on the `type` of the file.
+based on the `type` of the file. A path can have one `'.zip'` component indicating a zip folder allowing to read / write to and from
+zip files, although you cannot nest zip files in other zip files. 
  
 Resources can be located in the app specific space, or a shared space for all the apps. Accessing of app-specific
 resources is guaranteed to be isolated from other apps. Shared resources are... well, shared across all apes, meaning
@@ -310,7 +324,7 @@ specific data directory is under `world/scripts/foo.data/...`, and shared data s
 
 The default no-name app, via `/script run` command can only save/load/read files from the shared space.
 
-Functions return `null` if an error is encounter or no file is present (for read, list and delete operations). Returns `true`
+Functions return `null` if no file is present (for read, list and delete operations). Returns `true`
 for success writes and deletes, and requested data, based on the file type, for read operations. It returns list of files 
 for folder listing.
  
@@ -331,6 +345,14 @@ record to the file. Since files are closed after each write, sending multiple li
 write is beneficial for writing speed. To send multiple packs of data, either provide them flat or as a list in the
 third argument.
 
+Throws:
+- `nbt_read_error`: When failed to read NBT file.
+- `json_read_error`: When failed to read JSON file. The exception data will contain details about the problem.
+- `io_exception`: For all other errors when handling data on disk not related to encoding issues
+
+All other errors resulting of improper use of input arguments should result in `null` returned from the function, rather than exception
+thrown.
+
 <pre>
 write_file('foo', 'shared_text, ['one', 'two']);
 write_file('foo', 'shared_text', 'three\n', 'four\n');
@@ -382,6 +404,8 @@ specific data directory is under `world/scripts/foo.data/bar/../baz.nbt`, and sh
 
 You can use app data to save non-vanilla information separately from the world and other scripts.
 
+Throws `nbt_read_error` if failed to read app data.
+
 ### `store_app_data(tag)`
 
 Note:  `store_app_data(tag, file)` and `store_app_data(tag, file, shared?)` usages deprecated. Use `write_file` instead.
@@ -396,6 +420,83 @@ Returns `true` if the file was saved successfully, `false` otherwise.
 
 Uses the same file structure for exclusive app data, and shared data folder as `load_app_data`.
 
+### `create_datapack(name, data)`
+
+Creates and loads custom datapack. The data has to be a map representing the file structure and the content of the 
+json files of the target pack.
+
+Returns `null` if the pack with this name already exists or is loaded, meaning no change has been made.
+Returns `false` if adding of the datapack wasn't successful.
+Returns `true` if creation and loading of the datapack was successful. Loading of a datapack results in
+reloading of all other datapacks (vanilla restrictions, identical to /datapack enable), however unlike with `/reload` 
+command, scarpet apps will not be reloaded by adding a datapack using `create_datapack`.
+
+Currently, only json files are supported in the packs. `'pack.mcmeta'` file is added automatically.
+
+Reloading of datapacks that define new dimensions is not implemented in vanilla. Vanilla game only loads 
+dimension information on server start. `create_datapack` is therefore a direct replacement of manually ploping of the specified 
+file structure in a datapack file and calling `/datapack enable` on the new datapack with all its quirks and sideeffects
+(like no worldgen changes, reloading all other datapacks, etc.). To enable newly added custom dimensions, call much more
+experimental `check_hidden_dimensions()` after adding a datapack if needed.
+
+Synopsis:
+<pre>
+script run create_datapack('foo', 
+{
+    'foo' -> {
+        'bar.json' -> {
+            'c' -> true,
+            'd' -> false,
+            'e' -> {'foo' -> [1,2,3]},
+            'a' -> 'foobar',
+            'b' -> 5
+        }
+    }
+})
+
+script run create_datapack('funky_world',  {
+    'data' -> {
+        'minecraft' -> {
+            'dimension' -> {
+                'custom_ow.json' -> { 
+                    'type' -> 'minecraft:the_end',
+                    'generator' -> {
+                        'biome_source' -> {
+                             'seed' -> 0,
+                             'large_biomes' -> false,
+                             'type' -> 'minecraft:vanilla_layered'
+                        },
+                        'seed' -> 0,
+                        'settings' -> 'minecraft:nether',
+                        'type' -> 'minecraft:noise'
+                    }
+                }
+            }
+        }
+    }
+});
+check_hidden_dimensions();  => ['funky_world']
+        
+</pre>
+
+### `enable_hidden_dimensions()`
+
+The function reads current datapack settings detecting new dimensions defined by these datapacks that have not yet been added
+to the list of current dimensions and adds them so that they can be used and accessed right away. It doesn't matter how the
+datapacks have been added to the game, either with 'create_datapack()' or manually by dropping a datapack file and calling 
+`/datapack enable` on it. Returns the list of valid dimension names / identifiers that has been added in the process.
+
+Fine print: The function should be
+considered experimental. There 'should not be' (famous last words) any side-effects if no worlds are added. Already connected
+clients will not see suggestions for commands that use dimensions `/execute in <dim>` (vanilla client limitation) 
+but all commands should work just fine with
+the new dimensions. Existing worlds that have gotten modified settings by the datapacks will not be reloaded or replaced.
+The usability of the dimensions added this way has not been fully tested, but it seems it works just fine. Generator settings
+for the new dimensions will not be added to `'level.dat'` but it will be added there automatically next time the game restarts by 
+vanilla. One could have said to use this method with caution, and the authors take no responsibility of any losses incurred due to 
+mis-handlilng of the temporary added dimensions, yet the feature itself (custom dimensions) is clearly experimental for Mojang 
+themselves, so that's about it.
+
 ### `tick_time()`
 
 Returns server tick counter. Can be used to run certain operations every n-th ticks, or to count in-game time.
@@ -459,6 +560,8 @@ Evaluates the expression `expr` with different dimension execution context. `smt
 world-localized block, so not `block('stone')`, or a string representing a dimension like:
  `'nether'`, `'the_nether'`, `'end'` or `'overworld'`, etc.
  
+Throws `unknown_dimension` if provided dimension can't be found.
+ 
 ### `view_distance()`
 Returns the view distance of the server.
 
@@ -513,11 +616,12 @@ Available options in the scarpet app space:
  Relevant world related properties
   * `world_name` - name of the world
   * `world_seed` - a numeric seed of the world
+  * `world_dimensions` - a list of dimensions in the world
   * `world_path` - full path to the world saves folder
   * `world_folder` - name of the direct folder in the saves that holds world files
   * `world_carpet_rules` - returns all Carpet rules in a map form (`rule`->`value`). Note that the values are always returned as strings, so you can't do boolean comparisons directly. Includes rules from extensions with their namespace (`namespace:rule`->`value`). You can later listen to rule changes with the `on_carpet_rule_changes(rule, newValue)` event.
   * `world_gamerules` - returns all gamerules in a map form (`rule`->`value`). Like carpet rules, values are returned as strings, so you can use appropriate value conversions using `bool()` or `number()` to convert them to other values. Gamerules are read-only to discourage app programmers to mess up with the settings intentionally applied by server admins. Isn't that just super annoying when a datapack messes up with your gamerule settings? It is still possible to change them though using `run('gamerule ...`.
-
+  * `world_spawn_point` - world spawn point
 
  Relevant gameplay related properties
   * `game_difficulty` - current difficulty of the game: `'peaceful'`, `'easy'`, `'normal'`, or `'hard'`
@@ -528,7 +632,13 @@ Available options in the scarpet app space:
   * `game_view_distance` - the view distance
   * `game_mod_name` - the name of the base mod. Expect `'fabric'`
   * `game_version` - base version of the game
+  * `game_target` - target release version
+  * `game_major_target` - major release target. For 1.12.2, that would be 12
+  * `game_minor_reease` - minor release target. For 1.12.2, that woudl be 2
+  * `game_protocol` - protocol version number
+  * `game_pack_version` - datapack version number
   * `game_data_version` - data version of the game. Returns an integer, so it can be compared.
+  * `game_stable` - indicating if its a production release or a snapshot
   
  Server related properties
  * `server_motd` - the motd of the server visible when joining

docs/scarpet/api/BlocksAndWorldAccess.md

@@ -21,6 +21,8 @@ when it was used. Block values passed in various places like `scan` functions, e
 its properties are needed. This means that if the block at the location changes before its queried in the program this 
 might result in getting the later state, which might not be desired. Consider the following example:
 
+Throws `unknown_block` if provided input is not valid.
+
 <pre>set(10,10,10,'stone');
 scan(10,10,10,0,0,0, b = _);
 set(10,10,10,'air');
@@ -50,6 +52,8 @@ properties that the original source block may have contained.
 
 The returned value is either the block state that has been set, or `false` if block setting was skipped, or failed
 
+Throws `unknown_block` if provided block to set is not valid
+
 <pre>
 set(0,5,0,'bedrock')  => bedrock
 set(l(0,5,0), 'bedrock')  => bedrock
@@ -128,6 +132,8 @@ but doesn't open chests / containers, so have no effect on interactive blocks, l
 Returns true if placement/use was 
 successful, false otherwise.
 
+Throws `unknown_item` if `item` doesn't exist
+
 <pre>
 place_item('stone',x,y,z) // places a stone block on x,y,z block
 place_item('piston,x,y,z,'down') // places a piston facing down
@@ -146,6 +152,8 @@ If type is `null`, POI at position is removed. In any case, previous POI is also
 Interestingly, `unemployed`, and `nitwit` are not used in the game, meaning, they could be used as permanent spatial 
 markers for scarpet apps. `meeting` is the only one with increased max occupancy of 32.
 
+Throws `unknown_poi` if the provided point of interest doesn't exist 
+
 ### `set_biome(pos, biome_name, update=true)`
 
 Changes the biome at that block position. if update is specified and false, then chunk will not be refreshed
@@ -156,6 +164,8 @@ is only effective if you set it at y=0, and affects the entire column of. In the
 specific Y coordinate of the biome you want to change, and it affects roughly 4x4x4 area (give or take some random
 noise).
 
+Throws `unknown_biome` if the `biome_name` doesn't exist.
+
 ### `update(pos)`
 
 Causes a block update at position.
@@ -180,6 +190,8 @@ In item context, `true` means that breaking item has no nbt to use, `null` indic
 considered broken in process, and `nbt` type value, for a resulting NBT tag on a hypothetical tool. Its up to the 
 programmer to use that nbt to apply it where it belong
 
+Throws `unknown_item` if `tool` doesn't exist.
+
 Here is a sample code that can be used to mine blocks using items in player inventory, without using player context 
 for mining. Obviously, in this case the use of `harvest` would be much more applicable:
 
@@ -217,6 +229,13 @@ Causes a block to be harvested by a specified player entity. Honors player item
 tool if applicable. If the entity is not a valid player, no block gets destroyed. If a player is not allowed to break 
 that block, a block doesn't get destroyed either.
 
+### `create_explosion(pos, power?, mode?, fire?, source?, attacker?)`
+
+Creates an explosion at a given position. Default values of optional parameters are: `'power'` - `4` (TNT power), 
+`'mode'` (block breaking effect `none`, `destroy` or `break`: `break`, `fire` (whether extra fire blocks should be created) - `false`,
+`source` (exploding entity) - `null` and `attacker` (entity responsible for trigerring) - `null`. Explosions created with this
+endpoint cannot be captured with `__on_explosion` event, however they will be captured by `__on_explosion_outcome`.
+
 ### `weather()`,`weather(type)`,`weather(type, ticks)`
 
 If called with no args, returns `'clear'`, `'rain` or `'thunder'` based on the current weather. If thundering, will
@@ -271,6 +290,8 @@ back in state definition in various applications where block properties are requ
 
 `block_state` can also accept block names as input, returning block's default state.
 
+Throws `unknown_block` if the provided input is not valid.
+
 <pre>
 set(x,y,z,'iron_trapdoor','half','top'); block_state(x,y,z)  => {waterlogged: false, half: top, open: false, ...}
 set(x,y,z,'iron_trapdoor','half','top'); block_state(x,y,z,'half')  => top
@@ -291,6 +312,8 @@ Without arguments, returns list of available tags, with block supplied (either b
 of tags the block belongs to, and if a tag is specified, returns `null` if tag is invalid, `false` if this block doesn't belong 
 to this tag, and `true` if the block belongs to the tag.
 
+Throws `unknown_block` if `block` doesn't exist
+
 ### `block_data(pos)`
 
 Return NBT string associated with specific location, or null if the block does not carry block data. Can be currently 
@@ -299,16 +322,18 @@ used to match specific information from it, or use it to copy to another block
 <pre>    block_data(x,y,z) => '{TransferCooldown:0,x:450,y:68, ... }'
 </pre>
 
-### `poi(pos), poi(pos, radius?, type?, status?, column?)`
+### `poi(pos), poi(pos, radius?, type?, status?, column_search?)`
 
 Queries a POI (Point of Interest) at a given position, returning `null` if none is found, or tuple of poi type and its 
 occupancy load. With optional `type`, `radius` and `status`, returns a list of POIs around `pos` within a 
 given `radius`. If the `type` is specified, returns only poi types of that types, or everything if omitted or `'any'`.
 If `status` is specified (either `'any'`, `'available'`, or `'occupied'`) returns only POIs with that status. 
-With `column` set to `true`, it will return all POIs in a cuboid with `radius` blocks away on x and z, in the entire
+With `column_search` set to `true`, it will return all POIs in a cuboid with `radius` blocks away on x and z, in the entire
 block column from 0 to 255. Default (`false`) returns POIs within a spherical area centered on `pos` and with `radius`
 radius. 
 
+All results of `poi` calls are returned in sorted order with respect to the euclidean distance to the requested center of `pos`.
+
 The return format of the results is a list of poi type, occupancy load, and extra triple of coordinates.
 
 Querying for POIs using the radius is the intended use of POI mechanics, and the ability of accessing individual POIs 
@@ -325,9 +350,9 @@ poi(x,y,z,5) => [['nether_portal',0,[7,8,9]],['nether_portal',0,[7,9,9]]] // two
 
 Without arguments, returns the list of biomes in the world.
 
-With block, or name, returns the name of the biome in that position, or null, if provided biome is not valid. 
+With block, or name, returns the name of the biome in that position, or throws `'unknown_biome'` if provided biome or block are not valid. 
 
-With an optional feature, it returns value for the specified attribute for that biome. Available and querable features include:
+With an optional feature, it returns value for the specified attribute for that biome. Available and queryable features include:
 * `'top_material'`: unlocalized block representing the top surface material
 * `'under_material'`: unlocalized block representing what sits below topsoil
 * `'category'`: the parent biome this biome is derived from. Possible values include:
@@ -716,6 +741,7 @@ If structure is not specified, it will return a set of structure names that are
 as keys, and same type of map values as with a single structure call. An empty set or an empty map would indicate that nothing
 should be generated there.
 
+Throws `unknown_structure` if structure doesn't exist.
 
 ### `structures(pos), structures(pos, structure_name)`
 
@@ -749,6 +775,8 @@ structure starts.
 Requires a `Structure Variant` or `Standard Structure` name (see above). If standard name is used, the variant of the 
 structure may depend on the biome, otherwise the default structure for this type will be generated.
 
+Throws `unknown_structure` if structure doesn't exist.
+
 ### `plop(pos, what)`
 
 Plops a structure or a feature at a given `pos`, so block, triple position coordinates or a list of coordinates. 
@@ -771,7 +799,9 @@ All generated structures will retain their properties, like mob spawning, howeve
 itself has certain rules to spawn mobs, like plopping a nether fortress in the overworld will not spawn nether mobs, 
 because nether mobs can spawn only in the nether, but plopped in the nether - will behave like a valid nether fortress.
 
-### `custom_dimension(name, seed?)`
+###  (deprecated) `custom_dimension(name, seed?)`
+
+Deprecated by `create_datapack()` which can be used to setup custom dimensions
 
 Ensures the dimension with the given `'name'` is available and configured with the given seed. It merely sets the world
 generator settings to the overworld, and the optional custom seed (or using current world seed, if not provided). 

docs/scarpet/api/Entities.md

@@ -177,7 +177,7 @@ Returns `true` if en entity is standing on firm ground and falling down due to t
 
 ### `query(e, 'name'), query(e, 'display_name'), query(e, 'custom_name'), query(e, 'type')`
 
-String of entity name
+String of entity name or formatted text in the case of `display_name`
 
 <pre>
 query(e,'name')  => Leatherworker
@@ -722,6 +722,10 @@ Requires a living entity as an argument.
 
 Will make the entity jump once.
 
+### `modify(e, 'swing')` `modify(e, 'swing', 'offhand')`
+
+Makes the living entity swing their required limb.
+
 ### `modify(e, 'silent', boolean)`
 
 Silences or unsilences the entity.

docs/scarpet/api/Events.md

@@ -79,6 +79,19 @@ at the same time.
 Triggered right after a lightning strikes. Lightning entity as well as potential horseman trap would 
 already be spawned at that point. `mode` is `true` if the lightning did cause a trap to spawn. 
 
+### `__on_explosion(pos, power, source, causer, mode, fire)`
+
+Event triggered right before explosion takes place and before has any effect on the world. `source` can be an entity causing
+the explosion, and `causer` the entity triggering it,
+`mode` indicates block effects: `'none'`, `'break'` (drop all blocks), or `'destroy'` - drop few blocks. Event
+is not captured when `create_explosion()` is called.
+
+### `__on_explosion_outcome(pos, power, source, causer, mode, fire, blocks, entities)`
+Triggered during the explosion, before any changes to the blocks are done, 
+but the decision to blow up is already made and entities are already affected.  
+The parameter `blocks` contains the list of blocks that will blow up (empty if `explosionNoBlockDamage` is set to `true`).
+The parameter `entities` contains the list of entities that have been affected by the explosion. Triggered even with `create_explosion()`.
+
 ### `__on_carpet_rule_changes(rule, new_value)`
 Triggered when a carpet mod rule is changed. It includes extension rules, not using default `/carpet` command, 
 which will then be namespaced as `namespace:rule`.
@@ -107,7 +120,7 @@ Example events that may cause it to happen is releasing a bow. The event is trig
 the request, however the `item_tuple` is provided representing the item that the player started with. You can use that and
 compare with the currently held item for a delta.
 
-### `__on_player_finishes_using_item(player, item_tuple, hand))`
+### `__on_player_finishes_using_item(player, item_tuple, hand)`
 Player using of an item is done. This is controlled server side and is responsible for such events as finishing
 eating. The event is triggered after confirming that the action is valid, and sending the feedback back
 to the client, but before triggering it and its effects in game.

docs/scarpet/api/Inventories.md

@@ -28,14 +28,16 @@ an inventory, all API functions typically do nothing and return null.
 
 Most items returned are in the form of a triple of item name, count, and nbt or the extra data associated with an item. 
 
-### item_list(tag?)
+### `item_list(tag?)`
 
 With no arguments, returns a list of all items in the game. With an item tag provided, list items matching the tag, or `null` if tag is not valid.
 
-### item_tags(item, tag?)
+### `item_tags(item, tag?)`
 
 Returns list of tags the item belongs to, or, if tag is provided, `true` if an item maches the tag, `false` if it doesn't and `null` if that's not a valid tag
 
+Throws `unknown_item` if item doesn't exist.
+
 ### `stack_limit(item)`
 
 Returns number indicating what is the stack limit for the item. Its typically 1 (non-stackable), 16 (like buckets), 
@@ -43,6 +45,8 @@ or 64 - rest. It is recommended to consult this, as other inventory API function
 it is up to the programmer to keep it at bay. As of 1.13, game checks for negative numbers and setting an item to 
 negative is the same as empty.
 
+Throws `unknown_item` if item doesn't exist.
+
 <pre>
 stack_limit('wooden_axe') => 1
 stack_limit('ender_pearl') => 16
@@ -53,6 +57,8 @@ stack_limit('stone') => 64
 
 Returns the string representing the category of a given item, like `building_blocks`, `combat`, or `tools`.
 
+Throws `unknown_item` if item doesn't exist.
+
 <pre>
 item_category('wooden_axe') => tools
 item_category('ender_pearl') => misc
@@ -175,6 +181,8 @@ while( (slot = inventory_find(p, 'diamond', slot)) != null, 41, drop_item(p, slo
 inventory_drop(x,y,z, 0) => 64 // removed and spawned in the world a full stack of items
 </pre>
 
+Throws `unknown_item` if item doesn't exist.
+
 ### `inventory_remove(inventory, item, amount?)`
 
 Removes amount (defaults to 1) of item from inventory. If the inventory doesn't have the defined amount, nothing 

docs/scarpet/api/Scoreboard.md

@@ -6,13 +6,14 @@ Displays or modifies individual scoreboard values. With no arguments, returns th
 With specified `objective`, lists all keys (players) associated with current objective, or `null` if objective does not exist.
 With specified `objective` and
 `key`, returns current value of the objective for a given player (key). With additional `value` sets a new scoreboard
- value, returning previous value associated with the `key`.
+ value, returning previous value associated with the `key`. If the `value` is null, resets the scoreboard value.
  
 ### `scoreboard_add(objective, criterion?)`
 
 Adds a new objective to scoreboard. If `criterion` is not specified, assumes `'dummy'`.
-If the objective already exists, changes the criterion of that objective and returns `false`. If the criterion was not specified but the objective already exists, returns the current criterion.
-If the objective was added, returns `true`. If nothing is affected, returns `null`
+Returns `true` if the objective was created, or `null` if an objective with the specified name already exists.
+
+Throws `unknown_criterion` if criterion doesn't exist.
 
 <pre>
 scoreboard_add('counter')
@@ -31,6 +32,15 @@ for the objective.
 Sets display location for a specified `objective`. If `objective` is `null`, then display is cleared. If objective is invalid,
 returns `null`.
 
+### `scoreboard_property(objective, property)` `scoreboard_property(objective, property, value)`
+
+Reads a property of an `objective` or sets it to a `value` if specified. Available properties are:
+
+* `criterion`
+* `display_name` (Formatted text supported)
+* `display_slot`: When reading, returns a list of slots this objective is displayed in, when modifying, displays the objective in the specified slot
+* `render_type`: Either `'integer'` or `'hearts'`, defaults to `'integer'` if invalid value specified
+
 # Team
 
 ### `team_list()`, `team_list(team)`