Usage

Pressing the 'Open Build Guide' key (default: 'B') will open the Build Guide GUI, which is at the Shape sub-GUI initially. Toggling the 'Enable' checkbox on the top-left will determine whether or not a shape will be rendered. A bit below this checkbox, you can find two buttons to cycle through the available shapes, which can be found in the 'Shapes' section at the bottom of this usage guide. The 'Set origin' button will set the location of the little cube (red by default) at your feet. This cube is what the shape will be based on (for example, the start of a line or the centre of a circle). The origin can also be changed using the text fields and button below the 'Set origin' button. In the middle or on the right of the GUI is a list of properties belonging to the currently selected shape, like the radius or the orientation.

The 'Visualization' button takes you to a sub-GUI with sliders to change the colours of the larger cube of the shape (white by default) and the smaller origin cube (red by default). This sub-GUI also contains an option to toggle 'Depth test'; having depth test disabled allows you to see the shape through blocks.

Pressing 'Shape list' will allow you to use multiple shapes at once. In this sub-GUI, pressing the 'Add' button adds an instance of the shape shown above. The to-be-added shape can, again, be cycled to change what shape to add. Each shape in the list has its own origin, which by default is at your feet when first adding it. Clicking a shape in the list in the centre of the screen will select it, indicated by the black bar. The selected shape is the one that can be changed in the Shape GUI. Toggling the 'Visible' checkbox can temporarily hide the selected shape and ignores it in the total number of blocks count. Pressing 'Delete' will delete the selected shape. The 'Global origin' buttons and text fields shift the origin of the selected shape the same way as the normal origin buttons in the main GUI, but the origins of the unselected shapes will also do the same relative shifts, preserving the relative origins.

All the shapes and their settings are bound to world name (singleplayer) or server IP (multiplayer) and the dimension. The shapes can be preserved between restarts of the client by enabling the persistenceEnabled config option. Otherwise, the shapes will be lost when the client closes.

Shapes

Catenary: A catenary (aka a chain or rope line) between two points with a arc length (rope length) of the distance between these points plus a given additional distance.

Circle: A circle that can be around any of the three axes and can be stacked to form walls or tubes.

Cone: A cone that can be towards any of the three axes with a given radius and height.

Cuboid: A hollow cuboid with toggleable walls.

Ellipse: An ellipse that can be around any of the three axes and can be stacked to form walls or tubes.

Ellipsoid: An ellipsoid which can also be turned into one of six possible domes towards a direction along an axis.

Grid: A grid of blocks with a given step size and number of steps in each of the three axes.

Line: A line in one of the six directions along an axis.

Parabola: A parabola with a given half-width and height, facing a given direction and rotated by a given angle.

Paraboloid: A paraboloid towards any of the three axes with two given half-width and a given height.

Polygon: A triangle or a square or a pentagon or a hexagon, etc. Can be rotated around any of the three axes and can be stacked to form walls or tubes.

Sphere: A sphere which can also be turned into one of six possible domes towards a direction along an axis.

Torus: A donut-like shape with configurable radius and thickness that can be around any of the three axes.

The Build Guide GUI

The Build Guide GUI can be accessed using a keybind. By default, this keybind will be 'B', but, as any keybind, it can be changed via Minecraft's settings (with the GUI closed, Escape-> Options -> Controls for Minecraft 1.17 and lower, Escape -> Options -> Controls -> Key Binds for Minecraft 1.18 and higher). In this sub-GUI, you can only handle one shape at a time. The GUI is divided into four sub-GUIs, accessible through their four buttons at the top: 'Shape', 'Visualization', 'Shape list', and 'Configuration'. On the top-left, there is a global 'Enable' checkbox which toggles the rendering of shapes.There also exists a keybind, unbound by default, called 'Toggled enabled' as an alternative to the 'Enable' checkbox. The total number of blocks for the selected shape and for all shapes in total can be found at the top. The first line is the exact number of blocks. The second line shows this amount in the number of stacks plus a remainder. The 'X' button on the top-right will close the GUI, just like pressing Escape will.

The Shape sub-GUI

The Shape sub-GUI is divided into three sections: 'Shape', 'Origin', and 'Shape properties'.

Shape

The 'Shape' section determines which shape is shown. Initially, this will be the first shape the mod knows about, which should be a circle. Pressing the arrow buttons left and right of the name of the current shape will cycle between the available shapes.

Origin

So far, you should have a random shape that is being rendered (if you've pressed the 'Enable' checkbox). You will very likely want to move that shape around, which is what this section of the sub-GUI is all about. Assuming you haven't touched the Visualization GUI yet, you should see two kinds of blocks rendered; a lot of white blocks, which trace the shape and one small red block, which is called the 'origin' of the shape. This origin is what the shape is based on and is usually something like the centre of a circle or the start of a line. The initial origin will be the location you were in when you first opened the GUI. The buttons in the 'Origin' section all change the location of the origin and the blocks that trace the shape will move along with it. The first button, 'Set origin', will simply move the origin to your feet. The other three lines allow for finer control of each of the three components of the position (X, Y and Z). The '-' and '+' buttons will decrement and increment the relevant component, respectively. An exact value can be typed into the black text box. Clicking the 'Set' button will try to set the component to the value in the text box. If this value is not a valid whole number, the component will not be updated and the text will turn red. Trying a valid number will turn it white again. Additionally, there exists a keybind, unbound by default, that acts like the 'Set origin' button, and has the same name.

Shape properties

Finally, the 'Shape properties' contains the parameters of the shape; length, radius, orientation, etc. Parameters for each shape and descriptions of parameters can be found in the 'Shapes' section further on in this usage guide. When cycling between shapes, their parameters will be preserved.

The Visualization sub-GUI

The Visualization sub-GUI can be opened by pressing the 'Visualization' button. The Visualization sub-GUI mostly contains two sets of four sliders and two buttons. The left set controls the colour of the blocks that trace the shape and the right set controls the colour of the small origin block. Each of the four slides controls one of the colour components of its respective type of block: Red, Green, Blue and Alpha. The latter of those, Alpha, is the transparency of the blocks. After the sliders are at the desired positions, the colour can be applied by pressing 'Set'. Pressing 'Default' will return the colours to the default of white for the shape tracing blocks and red for the origin block. The 'Depth test' checkbox at the bottoms determines whether depth testing will be used during rendering, which is the technical term for "only draw this if there is not something between it and the camera". In other words, unchecking 'Depth test' will allow you to see the shape tracing blocks and the origin block through the world. This cannot be used as a form of x-ray or another kind of cheat, as the mod does not interact with the world in any way.

The Shape List sub-GUI

Pressing the 'Shape list' button it will take you to the Shape List sub-GUI. Like the Shape sub-GUI, the Shape List sub-GUI is divided into four sections: 'Add new shape', 'Selected shape', 'Global origin' and 'Shapes'.

Add new shape

In this section, you'll be able to cycle between shapes again. Cycling to the desired shape and pressing the 'Add' button below it will add the shape to the list under the 'Shapes' section. The origin for the newly added shape will be at your feet. You can freely cycle and add other shapes without affecting the ones you've added before.

Selected shape

Disabling the 'Visible' checkbox will hide the selected shape, indicated by it now being crossed out in the shape list. Pressing the 'Delete' button will delete the shape from the shape list.

Global origin

This section works similarly to the normal 'Origin' section in the Shape sub-GUI. Using the buttons and text fields will set the origin of the currently selected shape. However, the origins of all the other shapes will also change such that the shapes will maintain the same relative positions. Also like the normal origin handling, the 'Set global origin' button has a keybind alternative under the same name, which is unbound by default.

Shapes

The list under the 'Shapes' section lists the currently active shapes. Clicking on one of the shapes in the list will select it, indicated by the black box around it. If too many shapes are added to fit on the screen, a scrollbar will appear on the right of the list. Either dragging the scrollbar or using the scrollwheel on your mouse will scroll the list. Setting a colour in the Visualization GUI will also only affect the currently selected shape. However, at the moment, the depth test checkbox is still a global setting, meaning that it affects all the shapes, not just the selected one. This behaviour will likely change in the future to be more in line with the rest of the visualization stuff. If you have deleted all shapes from the list, a lot of buttons across most of the sub-GUIs will be disabled, as there will not be any shape to act upon. Adding a shape will enable them again.

The Configuration sub-GUI

Pressing the 'Configuration' button will open the Configuration sub-GUI. This sub-GUI offers a direct and instantaneous interface to the configuration file (see the Configuration section at the end of the mod description). Changing values won't require a restart to take effect.

Shapes

Most shapes can only be odd size by default because the origin is centered on one block (for example, this way, circles can only be 3x3, 5x5, 7x7, etc.). Shapes like these have all have an 'Even mode' checkbox to shift the origin half a block in relevant directions (from the previous example, circles can now only be 4x4, 6x6, 8x8, etc.).

Catenary

A catenary, also known as a chain line or a rope line, which is the shape of a rope hanging between two points. The two points the catenary is based on are the origin and the point relative to the origin described by the parameters 'Delta X', 'Delta Y' and 'Delta Z'. This second point can also be set using the 'Set endpoint' button, which places this position at your feet. The arc length of the catenary (the length of the rope) is defined by the distance between the two points plus the value given in 'Additional distance', which has to be 1 or more.

Circle

A simple circle. The 'Direction' property determines which axis the circle goes around. For example, when set to 'X', the circle will extend into the Y and Z directions. 'Radius' will set the radius of the circle and can be any positive whole number. Increasing 'Depth' will create a cylindrical tube in the direction given by 'Direction'.

Cone

A cone. The 'Direction' property determines which axis the cone points at. 'Radius' will set the radius of the cone and can be any positive whole number. 'Height' sets the height of the cone and can be negative.

Cuboid

A cuboid is a hollow cube-like shape where the length of each side is given by the parameters 'X', 'Y' and 'Z', which all have to be positive whole numbers. The 'Walls' parameter shows the walls which are currently active, where, for example, the presence of 'X' means that the walls towards the negative X direction and the positive X direction are enabled, and similarly for 'Y' and 'Z'. '-' means that no walls are enabled and the cuboid is only a wireframe. You can choose whether the origin is the corner or the centre of the cuboid.

Ellipse

An ellipse is very similar to a circle. The only difference is that, instead of a radius, it uses two semi-axes. These semi-axes work similar to a radius, but, if you consider a radius working in two directions, these semi-axes only work in one direction, which is the one shown in the parameter's name.

Ellipsoid

An ellipsoid is to a sphere like an ellipse is to a circle. It's only difference with the sphere is that it now has three semi-axes instead of a radius. Like a sphere, it also has dome modes.

Grid

A grid of blocks. The number of blocks and the step size between the blocks can be changes for each direction.

Line

A simple line. The two points the line is based on are the origin and the point relative to the origin described by the parameters 'Delta X', 'Delta Y' and 'Delta Z'. This second point can also be set using the 'Set endpoint' button, which places this position at your feet.

Parabola

A parabola. Its shape is described by the parameters 'Half-width' and 'Height', such that the point (Half-width,Height) is part of the parabola. 'Direction' and 'Rotation' allow the parabola to face a certain direction and be rotated by a given amount. 'Depth' will add layers towards the 'Direction' and can be negative.

Paraboloid

A paraboloid. It works similarly to the parabola, but now has two half-widths in the directions given by the parameter names. Rotation is now only given by the 'Direction' parameter.

Polygon

A polygon is a regular shape with a given number of sides. This number of sides is given by the 'Sides' parameter; 3 gives a triangle, 4 gives a square, 5 gives a pentagon, etc. The 'Sides' parameter has to be a whole number of 3 or higher. 'Radius' is a bit of a loose interpretation of a radius, and is the distance between the origin and one of the sides. 'Radius'' has to be a positive whole number. 'Direction' works like it does with a circle in that it determines which axis the polygon goes around. 'Rotation' is a multiple of 90° that the polygon will be rotated. Finally, 'Height' works like with a circle again.

Sphere

A sphere with a radius given by 'Radius', which is a positive whole number. 'Dome' sets the dome mode of the sphere: '-' means disabled, and any other option will only show only one hemisphere of the sphere in the direction it describes.

Torus

Also known as a donut. Like a circle, the 'Direction' parameter determines which axis it goes around. If you imagine the torus as a tube around a ring, then 'Outer radius' is the radius of the ring and 'Inner radius' is the radius of the tube. Both of them need to be positive whole numbers and 'Outer radius' must always be larger than or equal to 'Inner radius'. If 'Outer radius' is set to be smaller than 'Inner radius' or 'Inner radius' is set to be larger than 'Outer radius', the other parameter will be set to the same value.

Moving inbetween worlds, servers and dimensions

Planning out shapes is usually done in a very specific environment; shapes in your singleplayer world may not sense on your favourite server or another world, and the building you've planned in the Overworld is completely useless in the End where it floats in the void 500 blocks away from you. The latest version of the mod will therefore have a different state for each unique combination of world/server IP and dimension. As of writing, there is no way to transfer these a state to another world/server/dimension anyway, but a future version of the mod will implement toggling of this behaviour and moving/copying state around. By default, shapes and states are lost inbetween client restarts. Enabling the config option persistenceEnabled allows the mod to save shapes and states to files, and restore them when the client restarts. Due to technical limitations, restoring a state will begin when you open the GUI.