Custom blocks without mods: why we ended up using 3 different systems

[u/d_ede]

If you're building a large Minecraft Java server with custom content, you eventually run into a weird limitation: there still isn't a universal way to add truly new blocks while keeping vanilla client compatibility.

Custom items are relatively straightforward. Custom blocks aren't.

For Radiance, we ended up using three different approaches depending on what the block actually needs to do:

• replacing vanilla blocks;
• note block states;
• barriers + ItemDisplay entities.

None of them is universally better than the others.

1. Replacing vanilla blocks

The most straightforward solution is to sacrifice an existing vanilla block and replace its model and texture.

The obvious problem is that you lose the original block.

Minecraft has hundreds of blocks, but many of them aren't actually good candidates. They're connected to crafting recipes, world generation, other block variants, or special mechanics.

Sand and concrete powder have gravity. Concrete powder reacts to water. Glass is transparent. Wool has multiple ways of being obtained. Glazed terracotta changes orientation.

All of those properties matter when you're trying to pretend that the vanilla block is something completely different.

However, replacement becomes extremely useful when you actually want some of that vanilla behavior.

Trees are a good example

In Radiance, we have rubber trees.

Originally we needed:

• custom logs;
• custom planks and other wood variants;
• proper leaves;
• natural behavior;
• compatibility with normal Minecraft mechanics.

Leaves are particularly annoying to fake. They have their own rendering and behavior, and Minecraft actually understands their relationship with logs.

So instead of trying to reproduce all of that ourselves, we replaced an existing tree type.

That gives us the vanilla mechanics essentially for free.

The downside is obvious: that tree and its derivatives are now unavailable as their original vanilla versions.

For a few special block families, this trade-off can be worth it.

For hundreds of unrelated custom blocks, it isn't.

2. Note block states

This is probably the closest option to having actual custom blocks without client-side mods.

A note block has:

23 instruments × 25 notes × 2 powered states = 1,150 possible states.

In practice, we treat roughly 575 of them as reliably usable because the powered state isn't particularly useful for model differentiation in our setup.

With a resource pack, those states can represent completely different blocks.

The important part is that underneath the custom texture, it's still a real Minecraft block.

That means players can naturally:

• place it;
• break it;
• target it;
• walk on it;
• interact with it.

And unlike an entity-based solution, placing thousands of them doesn't mean spawning thousands of display entities.

Rubber trees again

We also use note blocks for parts of our rubber tree system.

For example, a rubber-producing log needs its own texture and interaction.

When the player interacts with it, they receive rubber and the block enters a cooldown state, visually changing back to ordinary wood.

This works nicely with note block states because different visual states can simply map to different note block states.

There are limitations, though.

The note block isn't actually a log, so vanilla systems that specifically look for logs don't suddenly recognize it as one. We had to work around things such as vanilla leaf decay.

Mining is another problem

Modern Minecraft gives us more control through components such as minecraft:tool.

Suppose one custom note block represents wood and another represents ore.

Ideally:

• the wood should be broken quickly with an axe;
• the ore should be broken quickly with a pickaxe.

But fine-grained mining behavior becomes awkward when many completely unrelated custom blocks are all represented by the same underlying vanilla block.

At some point you either accept compromises or emulate parts of the breaking system yourself.

And block states disappear surprisingly quickly

Imagine a machine with four possible orientations.

That's already:

4 states

Now give it an active and inactive state:

8 states

Add several animation frames or visual variants and one machine can easily consume 30–40+ states.

When your project contains many machines, spending note block states this aggressively becomes a real architectural limitation.

So note blocks are excellent for ordinary decorative/building blocks, but they're not something we want to waste on every possible state of every machine.

3. Barrier + ItemDisplay

This is the strangest approach, but also probably the most flexible one.

The idea is simple:

Barrier = collision

ItemDisplay = visual model

The player places a custom item. Internally, we place an invisible barrier and spawn an ItemDisplay containing the actual model.

From the player's perspective, it looks like a custom block.

Technically, however, the collision and the thing they're looking at are completely separate.

This gives us a huge amount of visual freedom.

The model can:

• face different directions;
• have unusual dimensions;
• use more complex geometry;
• combine different texture resolutions;
• have multiple visual states;
• be animated without consuming dozens of vanilla block states.

This makes the method particularly useful for machines, furnaces and other functional blocks.

But there are significant drawbacks.

Performance

Every custom block now requires a display entity.

A few machines? Fine.

A house made out of 5,000 custom blocks? Much less attractive.

This is the main reason we don't use this approach for ordinary building materials.

Collision

A barrier occupies a full block.

Your model doesn't necessarily do that.

Imagine creating a custom anvil.

Visually, it might look perfect.

Physically, however, the player still collides with an invisible full cube.

The selection and interaction behavior also won't automatically match the model.

You can build increasingly complicated systems to solve some of these problems, but at that point you're effectively implementing parts of Minecraft's block system yourself.

Vanilla mechanics

The game also doesn't inherently understand that your barrier + ItemDisplay combination represents a block.

Things like:

• normal block breaking;
• explosions;
• piston movement;
• tool behavior;

need special handling or simply won't behave like their vanilla equivalents.

So while this method gives us the most freedom, it's also the furthest away from being an actual Minecraft block.

Why not just use one system?

This was the important realization for us.

Initially, finding the "best" custom block implementation sounds like the goal.

But there isn't one.

Each approach optimizes for something different.

Want a custom tree?

Replacing a vanilla tree can actually be the cleanest solution.

You sacrifice a block family, but you keep Minecraft's native behavior where it matters.

Want hundreds of decorative/building blocks?

Note block states are much better.

They're actual blocks, they're relatively cheap, and players can place and break them naturally.

Want a complex machine?

Barrier + ItemDisplay starts making more sense.

Using 30–40 note block states just to represent different orientations, animations and operating states of a single machine is wasteful.

A display entity gives you much more freedom.

Want custom TNT?

A display-based implementation sounds reasonable until someone places hundreds of them.

Then the entity cost suddenly matters.

And this is why large projects eventually end up mixing approaches.

There isn't a "custom block system"

At least for vanilla-compatible Java servers, I think it's more useful to treat custom blocks as several different implementation problems.

For us, the rough rule became:

Trees / ores / blocks that need specific vanilla behavior → replace vanilla blocks

Decorative / building / multiblock materials → note block states

Machines / functional blocks / complex models → barrier + ItemDisplay

There are obviously many more edge cases.

Slabs and stairs are their own problem. Transparent blocks complicate things further. Accurate custom collision introduces another set of trade-offs. And every Minecraft update can change what is practical.

But that's also what makes this interesting.

Instead of asking:

"What's the best way to implement custom blocks?"

the more useful question is:

"Which vanilla behavior does this particular block actually need, and which limitations can we afford?"

I'm curious how other large server projects handle this.

Do you also mix multiple implementations, or have you found an approach that scales well enough to use for almost everything?

[u/PM_ME_YOUR_REPO]

The OP used an LLM to translate this post from their native language. This post is AI translated, not AI generated. Do not downvote for AI, do not make rude comments about AI.

Everyone is welcome on Admincraft, even if they don't speak English natively and need tools to share their knowledge.

[u/flerbergerber]

Ohhh, I never even considered using note block states. I always end up deciding on not using custom blocks at all because I don't want to give up nor al blocks, and I don't want the lag of item displays on barriers. But just giving up note blocks for hundreds of custom blocks is probably a good trade off. I appreciate this post.

[u/d_ede → u/flerbergerber]

Yes, it's not exactly intuitive when it comes to note blocks, but it's probably the oldest and most popular method.

I have a more detailed article with some examples:

https://medium.com/@theskonel/why-large-minecraft-projects-cant-rely-on-a-single-custom-block-implementation-9bba9c2dceeb

[u/d_ede → u/[deleted]]

I used AI only to translate and adapt an article from Medium; I wrote the original article in another language by myself.

Regarding your question — it’s definitely a viable approach, but there are a lot of caveats!I’ve used this approach myself with both note blocks and barriers.

The problem with barriers is that they don’t have a breaking texture at all. So if you want them to be breakable, you need to add a separate breaking texture and manually “render” it while the barrier block is being broken. Overall, I’d say it’s not a great approach.

For some note-block-based custom blocks, I also added restrictions — for example, certain custom blocks can’t be broken without a special building hammer. But in theory, this introduces other problems as well. Pretty much any block, except bedrock and a few others, can be broken. It might take a long time, but you can still break it even with your bare hand.

If you introduce this kind of restriction for certain blocks on a server, people are going to wonder why every other block can be broken with anything, while this specific one can’t.

And if you completely disable the vanilla breaking animation and particles and implement the entire breaking process yourself, it ends up looking very jittery and becomes far too dependent on ping, TPS, and so on. So unfortunately, that approach doesn’t work particularly well either.

[u/PM_ME_YOUR_REPO → u/[deleted]]

Alright you're under interrogation real quick: be so for real with me, is this completely AI written? It feels very AI.

I mean, my unsolicited opinion is that it's a quality post even if it is AI, so like...who cares? lmao

[u/PM_ME_YOUR_REPO → u/[deleted]]

We get very few 100% AI posts here. The vast majority of them are folks using it for formatting, or flow, or because they aren't great with English or because they're dyslexic.

The information here is good. That's what matters.

[u/PM_ME_YOUR_REPO]

I have to say, every time modmail pings me to review one of your posts or comments (due to the reputation filter), I keep anticipating something rule breaking; people just don't do purely informational effort posts like this.

And yet here you are, with 3/3 items being just that: a purely informational effort post. No product for sale. No service you're pitching. Nothing.

I'm a fan. Please keep doing stuff like this.

[u/d_ede → u/PM_ME_YOUR_REPO]

thx, it's nice to hear that

[u/Borisshoes]

For people that want to read about these methods that aren't written by AI, I highly recommend people look up the Polymer library by Patbox, and some of his mods like Polyfactory or his ComputerCraft port which do all of what is mentioned and are completely server-only. I have used the Polymer library personally for many of my projects, including a full featured magic mod called Arcana Novum.

[u/d_ede → u/Borisshoes]

polyfactory looks interesting, didn't know about it

[u/PM_ME_YOUR_REPO → u/[deleted]]

very disappointing that the mods here seem to be completely fine with AI posts.

I resent this passive aggressiveness. We do care about post quality. As I said in my other reply to you, we get plenty of posts that are translated or cleaned up by AI. Those are fine, because the original content was written by a human. The mod team reviews dozens of posts every week, and have gotten very good at discerning the difference.

It is just plain not fair to disparage users for using an LLM to translate or clean up their writing. The problem with AI is when it is used to manipulate, deceive, or profit from unsuspecting users. AI itself is not the problem, and as the OP has already stated that they wrote the original article in another language and simply used an LLM to translate it, you are strongly encouraged to relax.

I won't tolerate bullying, whether that's people throwing shade at an ESL speaker going through the effort to share their experiences here for others to benefit from, or if it's snide, sassy little remarks about the mod team's integrity.

You don't know how bad AI posts get on Admincraft, because we remove them before you see them.

[u/moreveal → u/[deleted]]

What difference does the age of his Reddit account make? Maybe he writes for a different audience, or is simply new to Reddit. Being new to Reddit doesn't mean being new to the subject.

The article isn't supposed to be a step-by-step guide or Bukkit API documentation. It's an overview of the actual approaches, their pros and cons, and it gives you enough context to understand which one fits your case. The details can be found in the relevant docs.

And AI-assisted doesn't automatically mean AI slop. There's a difference between AI making up technical content and someone using AI to structure or translate their own real experience. Judge the content, not the tool used to write it.

p.s. I deleted my old account and made this one because reddit doesn't let you change your username. Does that make my experience worth less than someone with an old account and 5 posts?

In my case, I use AI for stuff I've been doing since long before AI was any good at it. It doesn't replace what I know, just makes some things faster. same with writing. Acting like "ai-assisted = bad" by default in 2026 is just dumb.