Blocks

A first block

items/ores/ruby_ore.yml

ruby_ore:
  type: block
  name: "<red>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.

Mining

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.

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

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.

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 with a give action. Props 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.

items/ores/ruby_ore.yml

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

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.

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.

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.

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.

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.

list

The blocks a vein may replace, by id or #tag:

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.

text

default:"overworld"

overworld, nether or end. Each rule generates in worlds of that kind only.

list

Only these worlds, by name: worlds: [world, mining]. Without it, every world of the right dimension, including ones loaded later.

list

Only in these biomes, by id or #tag: biomes: [desert, "#minecraft:is_badlands"]. The biome is checked where each vein starts.

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:

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 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
Per face
Model

ruby_block:
  type: block
  texture: ruby_block.png

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.

ruby_lamp_block:
  type: block
  model: ruby_lamp.json     # its textures are found next to it

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

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.

items/blocks/glass/framed_glass.yml

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.

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

Looks are limited (see 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

0 to 15

Light level the block gives off.

text or section

A vanilla sound family for everything: sounds: metal (also stone, wood, glass, wool…). Or set single sounds:

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

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.

block id

Right-clicking with an axe turns it into this other custom block, keeping its direction. Like stripping logs.

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 (lore, enchantments, events…) for the item that places them, and events 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.

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.

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.

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.

Getting Started

Content

Elements

Text and sound

Server

A first block

Mining

Drops

World generation

Several rules

Good to know

Looks

Rotation

See-through and walk-through blocks

Connected textures

Other options

Stairs, slabs, trapdoors and doors

How many blocks

Deleting a block

​A first block

​Mining

​Drops

​World generation

​Several rules

​Good to know

​Looks

​Rotation

​See-through and walk-through blocks

​Connected textures

​Other options

​Stairs, slabs, trapdoors and doors

​How many blocks

​Deleting a block

A first block

Mining

Drops

World generation

Several rules

Good to know

Looks

Rotation

See-through and walk-through blocks

Connected textures

Other options

Stairs, slabs, trapdoors and doors

How many blocks

Deleting a block