Xar Chunk Edit Package

Back

What This Package Does

This is a package which you can use to create your own Lua block script, to be used in your own Fractal Block World package.

A block script, let's say which is called block_simple_room.lua, might look something like the following:

function p.__get_is_solid()
    return true
end

function p.__get_tex()
    return "block_checkered"
end

function p.__main()
    -- The default block is the "empty block".
    set_default_block("e")
    
    --Adding a pillar.
    create_rect("s", 7,7,0, 7,7,15)
    
    --A tree on the ground.
    set_pos(3,3,0, "block_tree")

    -- Shrinking.
    add_bent(3,3,2, "bent_base_ring_green")

    -- Text box.
    local msg_str = "Hello."
    add_bent_s(9,9,6, "bent_base_txt", msg_str)
end

It is intended that you write these Lua block scripts by hand. Indeed, to do certain complicated things like have randomness, it makes sense to write them by hand. Note that all chunks in the xar package were written by hand.

However, some chunks have no randomness and could be called "custom structures". For example, you might want a chunk that contains a modern art sculpture. The associated block script would likely have many set_pos lines in it. Writing this by hand can be tedious. The purpose of this package is to allow you to edit the chunk in the game, and then save the chunk you are editing to a Lua block script. That is, the package takes blocks built by the player and uses this to auto generate Lua code.

How to Install the Package

To install, simply download the xar_chunk_edit package here, extract the zip file and put the directory xar_chunk_edit in the directory Data/Packages/. So you will have the directory Data/Packages/xar_chunk_edit.

Start the Fractal Block World program and start a new game that uses the xar_chunk_edit package. The rest of this page describes how to use the package.

Changing Movement Speed

By pressing the Q key or the E key you can change the speed at which you move around.

10 "Weapons"

While playing the game (for this package), there are 10 "weapons" you can use. You select a weapon by pressing a number key (0 through 9) or by using your mouse wheel.

Select a Block Type

Every weapon has a "block type" associated to it.

You can select a block type for a weapon by first having the weapon equipped and pressing the T key. Then go to "SELECT BLOCK TYPE". You will be asked to choose between selecting a "xar block type" or a "non-xar block type". The non-xar block types are associated to the block lua scripts in Data/Packages/xar_chunk_edit/WorldNodes/Nodes. The xar block types are the blocks that are built into the engine (they are specified by C++ code that you do not have access to). Note that when selecting a block type from a list, you can type a "search string". Only the block types that match that string will be listed.

There is another way to select the block type for a weapon. While you have the weapon selected, hold down the G key and left click on a block. That will select the type of that block. Alternatively, you can hold down the G key and right click on a block. This will select the block type of the empty block that is adjacent to the block that you are looking at.

Select a Tool Type

Each of your 10 weapons has a "tool type".

You change this by first selecting a weapon, pressing the T key, and going to "SELECT TOOL TYPE".

Left vs Right Clicking

You use a weapon by either left clicking or right clicking. These do different things.

Left clicking generally does something to the solid block you are looking at. For example, it might replace it with the block type of the weapon.

Right clicking generally does something to the empty block that is adjacent to the one you are looking at.

Taking a Snapshot of a Chunk

Once you have created blocks in whatever chunk you want, you can fly into the chunk, open the console and enter the command snap. This will take the chunk you are in and auto generate the following Lua file:

Output/FileOut/chunk_snapshot.lua

You can then take the file, change its name, modify its code slightly, and put it in the WorldNodes/Nodes directory of whatever package you are creating yourself.

Take a look at the following file to see how the snap command works:

Data/Packages/xar_chunk_edit/Game/Commands/game_cmd_snap.lua

Feel free to modify the game_cmd_snap.lua file to make it behave the way you want.

Note that the snap command will merge adjacent blocks together of the same type to create rectangles of blocks.

The Support Block

The block of type block_support is special. It is solid, but when you take a snapshot, it is not saved.

Placeholder Blocks

Any block whose name starts with block_placeholder is special. These are called "placeholder blocks". When you take a snapshot, these are not saved normally, but instead the placeholder_for(x,y,z) function of the block script is called to generate an alternate Lua code line for the block. For example, consider "block_placeholder_bent_shrink.lua":

function p.__get_is_solid() return true end
function p.__get_tex() return "xce_placeholder_shrink" end

function p.__main()
    set_default_block("r_black")
end

function p.placeholder_for(x,y,z)
    return
        "add_bent("
        .. tostring(x) .. ","
        .. tostring(y) .. ","
        .. tostring(z) .. ","
        .. " \"bent_base_ring_green\")"
end

If we have this placeholder block at position (1,3,4), then the corresponding line in the chunk_snapshot.lua file will be as follows:

    add_bent(1,3,4, "bent_base_ring_green")

That is, there will be green shrink rings in the location that the placeholder block used to be.

Feel free to create your own placeholder blocks.