Document basic Minecraft types and global scope references

wiki/concepts/block/Block/en.yml

@@ -0,0 +1,4 @@
+title: "Block"
+description: "The base representation of a Minecraft block"
+
+optional: "#[[#c3c7cb;border:1px solid #51565d;font-size:0.8rem;padding:0.2em 0.3em; border-radius: 1em|Optional]]"

wiki/concepts/block/BlockState/en.yml

@@ -0,0 +1,4 @@
+title: "BlockState"
+description: "Block with states!"
+
+optional: "#[[#c3c7cb;border:1px solid #51565d;font-size:0.8rem;padding:0.2em 0.3em; border-radius: 1em|Optional]]"

wiki/concepts/block/BlockState/page.kubedoc

@@ -0,0 +1,6 @@
+# Creating BlockStates
+
+In places where `BlockState`s are expected, KubeJS will try to implicitly convert other objects into them.
+Most `BlockState`s can be written as string literals, with block property syntax being the same as one used in [`/setblock` or `/fill`](https://minecraft.wiki/w/Argument_types#minecraft:block_state).
+
+# Useful BlockState methods

wiki/concepts/block/LevelBlock/en.yml

@@ -0,0 +1,4 @@
+title: "LevelBlock"
+description: "A representation of a block in world"
+
+optional: "#[[#c3c7cb;border:1px solid #51565d;font-size:0.8rem;padding:0.2em 0.3em; border-radius: 1em|Optional]]"

wiki/concepts/block/LevelBlock/page.kubedoc

@@ -0,0 +1,201 @@
+**LevelBlock** is a KubeJS interface defining the script-friendly abstraction of a block in world. LevelBlocks can be easily manipulated to your heart's content.
+
+# How to get LevelBlocks
+
+`LevelBlock`s are usually obtained via block-getting methods on `Level` (object representing the Minecraft world), such as `[js]level.getBlock(x, y, z)`.
+
+# Useful LevelBlock methods
+
+## Position
+
+| Getter                   | Read-only bean      | Description                                       |
+| `[js]block.getPos()`     | `[js]block.pos`     | Gets the position of the block, as BlockPos.      |
+| `[js]block.getX()`       | `[js]block.x`       | Gets the x coordinate of the block.               |
+| `[js]block.getY()`       | `[js]block.y`       | Gets the y coordinate of the block.               |
+| `[js]block.getZ()`       | `[js]block.z`       | Gets the z coordinate of the block.               |
+| `[js]block.getCenterX()` | `[js]block.centerX` | Gets the x coordinate of the center of the block. |
+| `[js]block.getCenterY()` | `[js]block.centerY` | Gets the y coordinate of the center of the block. |
+| `[js]block.getCenterZ()` | `[js]block.centerZ` | Gets the z coordinate of the center of the block. |
+
+**Example**
+Position related beans on `LevelBlock` make for a useful application of a [destructuring pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) to quickly get all the block's coordinates to variables.
+
+```js
+const { x, y, z } = block
+// Now x, y and z constants are respectively the block's x, y and z coordinate.
+```
+
+---
+
+## Relative
+
+>>> #get-north
+Gets the block to the north of the `block`.
+<<<
+>>> #get-south
+Gets the block to the south of the `block`.
+<<<
+>>> #get-east
+Gets the block to the east of the `block`.
+<<<
+>>> #get-west
+Gets the block to the west of the `block`.
+<<<
+>>> #get-up
+Gets the block above the `block`.
+<<<
+>>> #get-down
+Gets the block below the `block`.
+<<<
+
+These getters allow you to get blocks around the currently referenced block, as `LevelBlock`s.
+
+| Getter                 | Read-only bean    | Description  |
+| `[js]block.getNorth()` | `[js]block.north` | <#get-north> |
+| `[js]block.getSouth()` | `[js]block.south` | <#get-south> |
+| `[js]block.getEast()`  | `[js]block.east`  | <#get-east>  |
+| `[js]block.getWest()`  | `[js]block.west`  | <#get-west>  |
+| `[js]block.getUp()`    | `[js]block.up`    | <#get-up>    |
+| `[js]block.getDown()`  | `[js]block.down`  | <#get-down>  |
+---
+
+## Other
+
+### Accessors
+
+>>> #entity-data
+Gets or sets the block entity data (as `CompoundTag`) of the block. The data get or set may be `null`.
+<<<
+>>> #block-state-note
+Gets or sets the BlockState of the block.
+**Note**: `setBlockState` also has an overload that allows for setting block update flags, see "Setters".
+<<<
+
+| Getter                      | Setter                                | Bean                   | Description         |
+| `[js]block.getEntityData()` | `[js]block.setEntityData(entityData)` | `[js]block.entityData` | <#entity-data>      |
+| `[js]block.getBlockState()` | `[js]block.setBlockState(state)`      | `[js]block.blockState` | <#block-state-note> |
+
+### Setters
+
+- `[js]block.set(block, properties, updateFlags)`
+  - `[js]block`: The Block to set the `block` to. It may be a string representing a block, for example `[js]'minecraft:oak_log'`
+  - `[js]properties` {optional}: Block properties to set on that block. It can be an object representing the block properties, for example `[js]\{ axis: 'x' \}`
+  - `[js]updateFlags` {optional}: Block update flags. They are a bit map of update properties.
+
+- `[js]block.setBlockState(blockState, updateFlags)`
+  - `[js]blockState`: The BlockState to set the `block` to. It may be a string representing a block state, for example `[js]'minecraft:oak_log\[axis=x\]'`
+  - `[js]updateFlags` {optional}: Block update flags. They are a bit map of update properties.
+
+### Getters
+
+>>> #players-in-radius-note
+Gets a list of all player entities in an 8-block radius, excluding fake players.
+**Note**: `getPlayersInRadius` also has an overload with customizable radius, see below this table.
+<<<
+>>> #inventory-note
+Gets the block's inventory (as `InventoryKJS`) accessible from the top of the block.
+Will get `[js]null` if the block does not have an inventory.
+**Note**: `getInventory` also has an overload with customizable access side, see below this table.
+<<<
+>>> #can-see-sky
+Gets `true` if block can see sky, `false` if it can't.
+<<<
+>>> #drops-note
+Gets the block's drops that are independent of entity and item held (as a list of [[/concepts/item-stack|ItemStacks]]).
+Will get an empty list if the block is not on a server-side world.
+**Note**: `getDrops` also has an overload with customizable entity and item, see below this table.
+<<<
+
+**Parameterless (with beans)**
+
+| Getter                           | Read-only bean              | Description                                                   |
+| `[js]block.getBiomeId()`         | `[js]block.biomeId`         | Gets the biome ID as ResourceLocation.                        |
+| `[js]block.getBlock()`           | `[js]block.block`           | Gets the Block of the block.                                  |
+| `[js]block.getBlockLight()`      | `[js]block.blockLight`      | Gets the block's block light level.                           |
+| `[js]block.getCanSeeSky()`       | `[js]block.canSeeSky`       | <#can-see-sky>                                                |
+| `[js]block.getDimension()`       | `[js]block.dimension`       | Gets the dimension of the block.                              |
+| `[js]block.getDimensionKey()`    | `[js]block.dimensionKey`    | Gets the dimension key of the block.                          |
+| `[js]block.getDrops()`           | `[js]block.drops`           | <#drops-note>                                                 |
+| `[js]block.getEntity()`          | `[js]block.entity`          | Gets the block entity of the block.                           |
+| `[js]block.getEntityId()`        | `[js]block.entityId`        | Gets the block entity ID (as ResourceLocation) of the block.  |
+| `[js]block.getId()`              | `[js]block.id`              | Gets the block's ID as string.                                |
+| `[js]block.getIdLocation()`      | `[js]block.idLocation`      | Gets the block's ID as ResourceLocation.                      |
+| `[js]block.getInventory()`       | `[js]block.inventory`       | <#inventory-note>                                             |
+| `[js]block.getItem()`            | `[js]block.item`            | Gets the ItemStack corresponding to this block.               |
+| `[js]block.getKey()`             | `[js]block.key`             | Gets the block's ResourceKey.                                 |
+| `[js]block.getLevel()`           | `[js]block.level`           | Gets the world the block is in.                               |
+| `[js]block.getLight()`           | `[js]block.light`           | Gets the block's light level.                                 |
+| `[js]block.getMod()`             | `[js]block.mod`             | Gets the block's mod ID as string.                            |
+| `[js]block.getPlayersInRadius()` | `[js]block.playersInRadius` | <#players-in-radius-note>                                     |
+| `[js]block.getProperties()`      | `[js]block.properties`      | Gets the block's properties.                                  |
+| `[js]block.getRegistry()`        | `[js]block.registry`        | Gets the block registry.                                      |
+| `[js]block.getRegistryId()`      | `[js]block.registryId`      | Gets the block's ResourceKey from the block registry.         |
+| `[js]block.getSkyLight()`        | `[js]block.skyLight`        | Gets the block's sky light level.                             |
+| `[js]block.getTagKeys()`         | `[js]block.tagKeys`         | Gets the list of block's TagKeys.                             |
+| `[js]block.getTags()`            | `[js]block.tags`            | Gets the list of block's tags as ResourceLocations.           |
+| `[js]block.getTypeData()`        | `[js]block.typeData`        | ???                                                           |
+
+**With parameters**
+
+- `[js]block.getInventory()`
+- `[js]block.getInventory(direction)`
+  - `[js]direction` {optional}: A `Direction`. In can be a string representing a direction, for example `[js]'north'`. Defaults to `[js]'up'` if not provided.
+  - **Returns**: The block's inventory (as `InventoryKJS`) accessible from the specified side. Will get `[js]null` if the block does not have an inventory.
+
+- `[js]block.getDrops()`
+- `[js]block.getDrops(entity, heldItem)`
+  - `[js]entity`: The [[/concepts/entity|`Entity`]] that would break the block. Defaults to `[js]null` if not provided. There's no overload without `heldItem`, so it must be provided too, regardless whether you want to use an item or not.
+  - `[js]heldItem`: The held item (as [[/concepts/item-stack|ItemStack]]) that would break the block. Defaults to air if not provided.
+  - **Returns**: The block's drops as a list of [[/concepts/item-stack|ItemStacks]], if the block is on a server-side world, an empty list otherwise.
+  - This method doesn't break the block, it just simulates the drops for that block.
+
+- `[js]block.getPlayersInRadius()`
+- `[js]block.getPlayersInRadius(radius)`
+  - `[js]radius` {optional}: The radius around the `block` to search players for. Defaults to `8` if not provided.
+  - **Returns**: All players found (as a list of [[/concepts/entity|Entities]]), excluding fake players.
+  - ==Guarantee==: Entities in this list are guaranteed to be [[/concepts/player|Players]], so documentation for [[/concepts/player|Player]] applies to those entities as well.
+
+### Other methods
+
+- `[js]block.offset(direction)`
+- `[js]block.offset(direction, amount)`
+  - `[js]direction`: A `Direction`. In can be a string representing a direction, for example `[js]'north'`
+  - `[js]amount` {optional}: Amount of blocks to move away from the `block`. Defaults to `1` if not provided.
+- `[js]block.offset(x, y, z)`
+  - `[js]x`, `[js]y`, `[js]z`: Amount of blocks to move from the `block` in x, y and z directions respectively.
+  - **Returns**: A `LevelBlock` representing a block at a specified offset.
+
+- `[js]block.mergeEntityData(entityData)`
+  - `[js]entityData`: The block entity data (as `CompoundTag`) to merge with existing entity data.
+
+- `[js]block.explode(explosionProperties)`
+  - `[js]explosionProperties`: The [[/ref/records/ExplosionProperties|explosion properties]] to use.
+  - **Returns**: An `Explosion` object. Also creates an explosion at the location of the block.
+
+- `[js]block.createEntity(entityType)`
+  - `[js]entityType`: The type of entity to create. It may be a string representing an entity, for example `[js]'minecraft:creeper'`
+  - **Returns**: An new [[/concepts/entity|`Entity`]] object with its position set to the position of the `block` (not its center!). Of course, you still need to spawn the entity, so don't discard the return type!
+
+- `[js]block.spawnLightning()`
+- `[js]block.spawnLightning(isEffectOnly)`
+- `[js]block.spawnLightning(isEffectOnly, player)`
+  - `[js]isEffectOnly` {optional}: Whether the lightning is purely visual (that is, harmless). Defaults to `[js]false` if not provided.
+  - `[js]player` {optional}: A player who caused the lightning.
+  - Results in a Lightning Bolt spawned at the center of the `block`, optionally with above properties set.
+
+- `[js]block.spawnFireworks(fireworksProperties, flightTime)`
+  - `[js]fireworksProperties`: The [[/ref/records/Fireworks|firework properties]] to use.
+  - `[js]flightTime`: Flight time of the firework, in ticks.
+  - Results in a firework launched from the center of the `block`, with above properties set.
+
+- `[js]block.popItem(item)`
+  - `[js]item`: The item to pop from the block (as [[/concepts/item-stack|ItemStack]]).
+  - Results in the specified `[js]item` being popped as an item entity from the location of the block.
+
+- `[js]block.popItemFromFace(item, direction)`
+  - `[js]item`: The item to pop from the block (as [[/concepts/item-stack|ItemStack]]).
+  - `[js]direction`: A `Direction`. It can be a string representing a direction, for example `[js]'north'`
+  - Results in the specified `[js]item` being popped as an item entity from the specified side from the location of the block.
+
+- `[js]block.toBlockStateString()`
+  - **Returns**: The block's state as a string, with syntax being the same as one used in [`/setblock` or `/fill`](https://minecraft.wiki/w/Argument_types#minecraft:block_state).

wiki/concepts/block/en.yml

@@ -0,0 +1,4 @@
+title: "Block"
+description: "It wouldn't be Minecraft if not for blocks!"
+
+optional: "#[[#c3c7cb;border:1px solid #51565d;font-size:0.8rem;padding:0.2em 0.3em; border-radius: 1em|Optional]]"

wiki/concepts/block/page.kubedoc

@@ -0,0 +1,13 @@
+**Blocks** are the very foundation of a Minecraft block.
+
+In the game, their role is split into the following Java objects:
+- [[/concepts/block/Block|`Block`]]  - which are the singleton objects defining block behavior. These aren't generally used in in-world interactions.
+
+- [[/concepts/block/BlockState|`BlockState`]]  - which define additional properties attacked to a block (like axis, being waterlogged, orientation, etc.). These are actual objects stored in world, and can be manipulated.
+
+- [[/concepts/block/LevelBlock|`LevelBlock`]] - a special interface added by KubeJS which abstracts away common cases of manipulating blocks in world.
+
+# See also
+
+
+

wiki/concepts/data-components/page.kubedoc

@@ -1,4 +1,35 @@
 WIP!
+**Data components** are structured data consisting of key-value pairs, that define various properties of items and block entities, such as their name, lore, enchantments, inventory, etc. Data components can be attached to Items (and thus [[/concepts/item-stack|ItemStacks]]), and block entities.
+
+This article will discuss how you can create data component types and manipulate them.
+
+# Creating DataComponentMaps
+
+In places where DataComponentMap is expected (such as the second argument of `[js]Item.of(item, components)`), you can write string literals with the same string format as you would use in [`/give`](https://minecraft.wiki/w/Argument_types#item_stack).
+
+Example: `[js]Item.of('minecraft:diamond_sword', '\[damage=2,lore=[{text:"This item is cool."}]\]')`
+
+# Using DataComponentMaps
+
+In the following examples, `components` will refer to the DataComponentMap.
+
+- `[js]components.get(type)`
+  - `type` - A component type. It can be a string representing a type, for example `[js]'minecraft:lore'`.
+  - **Returns**: Value associated with the component type.
+- `[js]components.has(type)`
+  - `type` - A component type. It can be a string representing a type, for example `[js]'minecraft:lore'`.
+  - **Returns**: `true` is the component has data associated with a type, `false` otherwise.
+- `[js]components.isEmpty()`
+  - **Returns**: `true` is the component contains no data, `false` otherwise.
+>>>info
+Also available as a **read-only** bean: `components.empty`.
+<<<
+- `[js]components.keySet()`
+  - **Returns**: A set of all types (as implementations of `DataComponentType` interface) in the component map.
+- `[js]components.size()`
+  - **Returns**: The amount of keys in the component map.
+
+Just like other read-only maps, `components` also contain `filter` and `forEach` methods. 
 
 # Further Reading
 - [Minecraft Wiki: Data Component format](https://minecraft.wiki/w/Data_component_format)