Getting Started - rvandoosselaer/Blocks GitHub Wiki

A block world isn't actually made up out of 3D cubes. It's made up of quads that give the impression of looking like cubes.

To accomplish this task, we need to organise the block data in a structured way: chunks. A chunk is a manner of bundling a number of adjacent blocks together. Then, based on the blocks of a chunk, a mesh of the chunk is generated and rendered.

The Blocks framework tries to facilitate this process as much as possible.

Let's draw a block

The library is available on jitpack.io.

Step 1. Add the jitpack.io repository to the list of repositories.

repositories {
    maven { url 'https://jitpack.io' }
}

Step 2. Add the dependency information:

• group: com.github.rvandoosselaer
• artifact: Blocks
• version: 1.7.1

Check the releases or jitpack pages for available versions.

Step 3. That's it!

Gradle example:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.rvandoosselaer:Blocks:v1.7.1'
}

1. Initialize Blocks

Before we can use Blocks, we should initialize it first. This can be done with a single line of code:

BlocksConfig.initialize(assetManager);

2. Add a block

As said before, blocks are arranged in chunks. The default size of a chunk is 32x32x32 blocks. So let's create a chunk and add a block to it.

Chunk chunk = Chunk.createAt(new Vec3i(0, 0, 0));

BlockRegistry blockRegistry = BlocksConfig.getInstance().getBlockRegistry();
Block grass = blockRegistry.get(BlockIds.GRASS);
chunk.addBlock(0, 0, 0, grass);

The above code creates an empty Chunk at the center (0, 0, 0) coordinate. The grass block is retrieved from the BlockRegistry and placed in the chunk at 0, 0, 0.

3. Generate the node of the chunk and render it

Now that we have placed a block in the chunk, we can generate the mesh of the chunk and render it.

ChunkMeshGenerator meshGenerator = BlocksConfig.getInstance().getChunkMeshGenerator();
chunk.createNode(meshGenerator);

rootNode.attachChild(chunk.getNode());

The above code generates the mesh of the chunk and attaches it to the rootnode.

⚠️ Don't forget to add a light to the scene, to make the block visible!

Congratulations, you just created and showed your first block to the world!

💡 In most use cases however, you don't want the hassle of managing the blocks and chunks yourself. Or doing calculations to know in what chunk a block resides. Blocks can take care of this process for you. See the examples and ChunkManager and Pager pages for more information.

full source code:

public class BlockTest extends SimpleApplication {

    public static void main(String[] args) {
        BlockTest blockTest = new BlockTest();
        blockTest.start();
    }

    @Override
    public void simpleInitApp() {
        BlocksConfig.initialize(assetManager);

        Chunk chunk = Chunk.createAt(new Vec3i(0, 0, 0));

        BlockRegistry blockRegistry = BlocksConfig.getInstance().getBlockRegistry();
        Block grass = blockRegistry.get(BlockIds.GRASS);
        chunk.addBlock(0, 0 ,0, grass);

        ChunkMeshGenerator meshGenerator = BlocksConfig.getInstance().getChunkMeshGenerator();
        chunk.createNode(meshGenerator);

        rootNode.attachChild(chunk.getNode());

        rootNode.addLight(new AmbientLight(new ColorRGBA(0.2f, 0.2f, 0.2f, 1f)));
        rootNode.addLight(new DirectionalLight(new Vector3f(-0.1f, -1f, -0.1f).normalizeLocal(), new ColorRGBA(2f, 2f, 2f, 1f)));
    }
    
}