> ## Documentation Index > Fetch the complete documentation index at: https://items.lodemc.net/llms.txt > Use this file to discover all available pages before exploring further. # Blocks > Full blocks, logs, see-through and walk-through blocks, stairs, slabs, trapdoors and doors. ## A first block ```yaml items/ores/ruby_ore.yml theme={null} ruby_ore: type: block name: "Ruby Ore" texture: ruby_ore.png # all six sides hardness: 3 # optional; stone is 1.5 tool: pickaxe # optional; the default ``` Reload, run `/lodeitems give ruby_ore`, and place it like any other block. You never choose *how* the block is shown to players (note blocks, mushroom blocks and so on). LodeItems picks that for you and remembers it, so placed blocks stay the same across reloads and restarts. Custom blocks are real blocks on the server. They cost the same as vanilla blocks to store and to load, so they're fine for building whole areas and for pasting with [WorldEdit](https://items.lodemc.net/integrations.md#worldedit). ## Mining **hardness** `number` (default: 1.5) How long it takes to mine, on vanilla's scale: dirt is 0.5, stone 1.5, iron ore 3, obsidian 50. `0` breaks instantly and `-1` makes it unbreakable. **tool** `text` (default: pickaxe) The tool that mines it quickly: `pickaxe`, `axe`, `shovel`, `hoe` or `none`. Better tiers and Efficiency mine faster, just like vanilla. It only changes speed, not whether the block drops (see [Drops](#drops)). ## Drops A custom block always drops **one of itself**, the same item that places it, whatever it is broken with: by hand, with any tool, with an explosion or by a piston. There is nothing to set. | Block | Drops | | - | - | | Any normal block (solid, see-through or walk-through) | 1 of itself | | `shape: stairs`, `trapdoor` | 1 of itself | | `shape: slab` | 1, or 2 for a double slab | | `shape: door` | 1 door, from the lower half only (breaking the top half breaks the whole door) | | A block whose config was deleted | Nothing | Players in creative mode get no drops, like vanilla. > [!NOTE] > > Blocks don't have a `drops:` option yet. You can't make a block drop other items (an ore dropping gems), need the right tool to drop, react to Silk Touch or Fortune, or give experience. To give extra items now, use a `break` [event](https://items.lodemc.net/events.md) with a `give` action. [Props](https://items.lodemc.net/furniture.md#drops) already have a full `drops:` option. ## World generation `generate:` makes a block appear in veins in newly generated chunks, like vanilla ores. The veins are placed by vanilla's own ore code, so they're shaped exactly like iron or coal veins. ```yaml items/ores/ruby_ore.yml theme={null} ruby_ore: type: block texture: ruby_ore.png hardness: 3 generate: height: -64..16 # Y range veins: 6 # veins per chunk size: 8 # blocks per vein deepslate: ruby_deepslate_ore # the version used inside deepslate ruby_deepslate_ore: type: block texture: ruby_deepslate_ore.png hardness: 4.5 ``` > [!WARNING] > > Only **new chunks** get veins. Chunks that were already generated are left as they are, so explore new land or start a new world to find the ore. **height** `range` (default: -64..64) The lowest and highest Y a vein can start at, like `-64..16` (`-64 to 16` works too). Veins are spread evenly across the range. The default is `10..117` in the nether and `0..128` in the end. Parts of the range outside the world are ignored. **veins** `number` (default: 4) How many veins each chunk tries to place, from 0 to 256. Fractions work: `0.5` is a vein in about every other chunk, `2.3` is 2 per chunk plus a third one 30% of the time. For comparison, vanilla iron is around 10 and diamonds around 7 below Y 16. **size** `number` (default: 8) How many blocks a vein tries to place, from 1 to 64. Vanilla coal is 17, iron 9, diamond 4 to 12. Only blocks it can replace (see `replace`) become ore, so real veins are often smaller. **deepslate** `block id` Another LodeItems block to use where the vein runs through deepslate and tuff, like vanilla's deepslate ores. Without it, the block itself is used there too. Overworld only. **replace** `list` The blocks a vein may replace, by id or `#tag`: ```yaml theme={null} replace: [stone, andesite, "#minecraft:base_stone_overworld"] ``` Without it, a vein replaces what vanilla ores replace: stone, granite, diorite, andesite, deepslate and tuff in the overworld, netherrack, basalt and blackstone in the nether, and end stone in the end. If you set `replace`, deepslate is only replaced when `deepslate:` is given too. **dimension** `text` (default: overworld) `overworld`, `nether` or `end`. Each rule generates in worlds of that kind only. **worlds** `list` Only these worlds, by name: `worlds: [world, mining]`. Without it, every world of the right dimension, including ones loaded later. **biomes** `list` Only in these biomes, by id or `#tag`: `biomes: [desert, "#minecraft:is_badlands"]`. The biome is checked where each vein starts. **hidden** `0 to 1` (default: 0) The chance to skip each block that would touch air, so less ore shows in cave walls. Vanilla diamonds use `0.5`, ancient debris `1`. ### Several rules Give a list to generate a block in more than one way, for example common small veins high up and rare big ones deep down, or once in the overworld and once in the nether: ```yaml theme={null} ruby_ore: type: block texture: ruby_ore.png generate: - height: 0..64 veins: 4 size: 6 - height: -64..0 veins: 1.5 size: 14 hidden: 0.5 deepslate: ruby_deepslate_ore - dimension: nether replace: [netherrack] veins: 8 ``` ### Good to know * Generated ore is a normal custom block. It costs the same as stone to store, and it [drops](#drops) and mines like a placed one. * Changes to `generate:` apply on `/lodeitems reload`, but only to chunks generated after that. * A mistake in one rule (an unknown biome, a `deepslate:` that isn't a LodeItems block) skips that rule and says why. The block itself still loads. ## Looks Use one of these: **One texture** ```yaml theme={null} ruby_block: type: block texture: ruby_block.png ``` **Per face** ```yaml theme={null} ruby_log: type: block textures: top: ruby_log_top.png # both ends, unless bottom is given too side: ruby_log.png rotation: axis ``` Face keys: `all`, `side`, `top`, `bottom`, or each face on its own: `up`, `down`, `north`, `south`, `east`, `west`. The most specific one wins, so `all` plus `north` gives every face the same texture except north. `particle` sets the breaking particles. **Model** ```yaml theme={null} ruby_lamp_block: type: block model: ruby_lamp.json # its textures are found next to it ``` ### Rotation **rotation** `text` * `axis`: turns like a log, along the axis of the face you clicked. * `horizontal`: the front faces the player, like a furnace. * `facing`: like `horizontal`, but it can also face up or down when you look steeply up or down, like an observer. ## See-through and walk-through blocks ```yaml theme={null} ruby_glass: type: block texture: ruby_glass.png transparent: true # see-through, still solid (like glass or leaves) ruby_flower: type: block texture: ruby_flower.png solid: false # walk through it; breaks instantly, like plants ``` Blocks you walk through always break instantly, so they can't have a `hardness`. ## Connected textures Blocks of the same kind next to each other can join up, so a wall of glass looks like one big window and a floor of tiles like one surface. ```yaml items/blocks/glass/framed_glass.yml theme={null} framed_glass: type: block transparent: true texture: framed_glass.png # a single pane, with its frame connected-texture: framed_glass_inner.png # the same pane without the frame connect: all ``` You only draw **two textures**, whichever mode you use: | Texture | What to draw | | - | - | | `texture` | The block on its own, with its border on all four edges | | `connected-texture` | The same picture with the border painted out, seamless when tiled | Both must be PNGs of the same size. LodeItems works out how wide the border is and makes every tile itself: the border stays on each edge that doesn't touch the same block. One pair covers all six faces. **connect** `text` Which neighbours it joins. Each combination of neighbours is its own look, so the modes cost differently: | `connect` | Joins | Looks it uses | | - | - | - | | `vertical` | the blocks above and below (pillars, logs) | 4 | | `horizontal` | the four blocks around it (bookshelves, panels) | 16 | | `all` | every direction (glass, tiles, frames) | 64 | > [!WARNING] > > Looks are limited (see [How many blocks](#how-many-blocks)). Solid blocks have plenty, but there are only 143 see-through looks, so at most 2 see-through blocks can use `connect: all`. The Framed Glass that comes with LodeItems is one of them. Use `vertical` or `horizontal` where they're enough. * Faces between two joined blocks aren't drawn, so connected glass shows no inner edges. * Corners where two joined edges meet stay seamless. Proper inner-corner notches would need the diagonal neighbours too, which is far too many looks. * A connected block uses one texture pair for every face, and can't also use `rotation`, `textures:` or `model:`. LodeItems comes with two connected blocks in `items/blocks/`: **Lodestone Tiles** (solid) and **Framed Glass** (see-through). ## Other options **light** `0 to 15` Light level the block gives off. **sounds** `text or section` A vanilla sound family for everything: `sounds: metal` (also `stone`, `wood`, `glass`, `wool`...). Or set single sounds: ```yaml theme={null} sounds: family: stone place: block.amethyst_block.place break: myserver:ruby_break step: block.amethyst_block.step hit: block.amethyst_block.hit fall: block.amethyst_block.fall ``` **tags** `list` Vanilla block tags it belongs to, so the game treats it like those blocks. For example `[beacon_base_blocks]` lets it build beacon pyramids, and `[dragon_immune, wither_immune]` keeps those bosses from breaking it. Mining speed comes from `tool`, not from tags. **strips-into** `block id` Right-clicking with an axe turns it into this other custom block, keeping its direction. Like stripping logs. ```yaml theme={null} ruby_log: type: block textures: { top: ruby_log_top.png, side: ruby_log.png } rotation: axis strips-into: stripped_ruby_log ``` Blocks also take every [item option](https://items.lodemc.net/items.md) (`lore`, `enchantments`, `events`...) for the item that places them, and [events](https://items.lodemc.net/events.md) like `place`, `break` and `interact`. ## Stairs, slabs, trapdoors and doors `shape:` makes a block that works exactly like that vanilla kind: stairs connect, slabs stack into double slabs, doors and trapdoors open by hand and with redstone. ```yaml theme={null} marble_stairs: type: block shape: stairs texture: marble.png # or textures: with top, bottom and side marble_slab: type: block shape: slab textures: { top: marble_top.png, side: marble_side.png } ruby_trapdoor: type: block shape: trapdoor texture: ruby_trapdoor.png ruby_door: type: block shape: door textures: top: ruby_door_top.png bottom: ruby_door_bottom.png item-texture: ruby_door_item.png # the icon; defaults to the top half open-by-hand: false # only redstone opens it ``` Doors and trapdoors can have holes in their texture but no half-transparent pixels. Stairs and slabs are always drawn solid. Shaped blocks can't have `model`, `rotation` or `light`. > [!WARNING] > > Shaped blocks have a **hard limit**, because each design has to borrow a whole set of vanilla states: **3 stairs, 3 slabs, 24 trapdoors and 25 doors**. Past that, loading tells you the shape is full. ## How many blocks | Kind | Looks available | Slots in `config.yml` (default) | | - | - | - | | Solid blocks | 1,489 | `blocks.slots` (1000) | | See-through (`transparent: true`) | 143 | `blocks.transparent-slots` (200) | | Walk-through (`solid: false`) | 111 | `blocks.passable-slots` (100) | Each direction of a rotating block uses its own slot and look: an `axis` block uses 3, a `horizontal` one 4 and a `facing` one 6. * **Looks** are how many different-looking blocks the game can show. That is a limit of Minecraft itself. * **Slots** are reserved when the server starts. New blocks need no restart as long as slots are free. Changing the number needs a restart. > [!WARNING] > > Never lower a slot count below what you use. Placed blocks in the slots you remove would disappear. A block keeps the kind it was first given. Changing a placed block from solid to `transparent` gives a warning and has no effect, because placed blocks can't move to another pool. ## Deleting a block When you delete a block's config, its placed copies stay in the world and show as stone. Its slot stays reserved, so if you add the config back, they come back as they were. The assignments are saved in `cache/blocks.json` and `cache/shaped_blocks.json`. Keep those files. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.