Adding Blocks

Now that you have created a Lua mod in Introduction, let's continue by adding blocks.

The Exdilin API

The Exdilin API is a global variable that allows to interact with Blocksworld. It has a lot of functions which are all referenced in the Lua API Reference. But in this tutorial, we'll be interested in exdilin.new_block.

The exdilin.new_block function takes a table (see Lua - Tables), today we will only need to understand two fields in the table: id and modelName.

The first is straightforward, id must be set to the block's identifier/name, model name is the name (inside Blocksworld's Resources!) of the 3D model of the block, this defaults to the block's name, but we don't have any model to put for our block, so we will use the cube's model. The cube's model name is very simple, it's simply Cube, with all that setup let's create a block named Test.

-- ... previous code

function pre_init()
    local block = exdilin.new_block({
        id = "Test",
        modelName = "Cube"
    })
end

However the block does not register itself (read: does not exist yet), so we will have to register it.

function pre_init()
    local block = exdilin.new_block({
        id = "Test",
        modelName = "Cube"
    })
    block.register()
end

Cool, the block is registered, however we cannot place it from the Build Panel 😕

To do that we need to add a block item, it is not really specific to block and can be applied to script functions, textures, and others.

Manually creating a block item is exhausting and takes a lot of lines of code, hopefully the block we just saved in a variable provides a way to do just that, the default_block_item function.

This function is simple, it takes two arguments: the first is the icon name and the second is the rarity (rarity define the border around it, like does it have any, are they golden, etc.)

The icon of the default cube block is Yellow/Cube, and the rarity will be common (note: you can choose any rarity that is present in Rarity Levels)

Like the block, we will also have to register that new block item, now let's write the code:

function pre_init()
    local block = exdilin.new_block({
        id = "Test",
        modelName = "Cube"
    })
    local blockItem = block.default_block_item("Yellow/Cube", "common")
    blockItem.register()
    block.register()
end

As you should know if you learnt Lua, the block part in block.default_block_item refers to the variable we did just above (local block = ...), so if you name your variable something else like idontknowlua, the function should be idontknowlua.default_block_item.

Now launch Blocksworld, scroll down the Blocks tab and tada! A new block you just made has appeared!

You can also fiddle with the rarity and the icon, try the Yellow/Cylinder icon, or the rare rarity.