Build Guide (Forge+Fabric)
A client-side only mod to project shapes like circles and spheres into the world. It works both in singleplayer and multiplayer, even if the server doesn't have the mod installed.
Short usage guide
Pressing the 'Open Build Guide' key (default: 'B') will open the main Build Guide GUI. Toggling the 'Enable' checkbox will determine whether or not a shape will be rendered. Above this checkbox, you can find two buttons to cycle through the available shapes (if 'Advanced mode' is unchecked), which can be found in the 'Shapes' section at the bottom of this usage guide. The 'Set base position' 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 base position can also be changed using the text fields and button below the 'Set base position' button. At the bottom 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 base 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. A keybind also exists that will take you to this sub-GUI directly, but it is unbound by default.
Back in the main GUI, enabling 'Advanced mode' will allow you to use multiple shapes at once. Managing these shapes can be done in a sub-GUI that can now be accessed using the "..." button in the top-left of the main GUI. This one also has a (by-default unbound) keybind to directly access it. 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 base position, 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 main 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 base position' buttons and text fields shift the base position of the selected shape the same way as the normal base position buttons in the main GUI, but the base positions of the unselected shapes will also do the same relative shifts, preserving the relative base positions.
All the shapes and settings are bound to world name (singleplayer) or server IP (multiplayer) and the dimension, and are preserved as long as the client isn't closed.
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.
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.
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.
Full usage guide
The Build Guide GUI
The Build Guide GUI, or the main 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). Initially, the mod will be in 'simple mode', which means that you can only handle one shape at a time. The GUI is divided into four sections; 'Global properties', 'Base position', 'Number of blocks' and 'Shape properties', each described in the following paragraphs. Closing the GUI is as simple as pressing Escape or pressing the 'X' button at the top-right of the screen.
The 'Global properties' section contains functions which govern which shape(s) are shown and how they are shown. In simple mode, the first line 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. Next, to actually render the shape, you have to check the 'Enable' checkbox. Below the 'Enable' checkbox is a large button with 'Visualization' on it. Clicking it will take you to the Visualization GUI, which is described further in the next section with the same name. In short, the Visualization GUI is where you can change the colour of the blocks that trace the shape and this GUI contains an option to allow the shape's blocks to be seen through blocks. There also exists a keybind, unbound by default, called 'Toggled enabled' as an alternative to the 'Enable' checkbox. The final checkbox in this section of the main GUI toggles 'advanced mode'. Advanced mode allows us to handle and render multiple shapes at once, but using it is slightly different than simple mode. For now, this usage guide will assume that you remain in simple mode. Usage of advanced mode is described in the later section 'Advanced mode'.
So far, you should have a random shape that is being rendered. You will very likely want to move that shape around, which is what this section of the 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 'base position' of the shape. This base position what the shape is based on and is usually something like the centre of a circle or the start of a line. The initial base position will be the location you were in when you first opened the main GUI. The buttons in the 'base position' section all change the location of the base position and the blocks that trace the shape will move along with it. The first button, 'Set base position', will simply move the base position 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 base position' button, and has the same name.
Number of blocks
This section just shows the number of trace blocks the shape is made up of. The first line is the exact number of blocks. The second line shows this amount in the number of stacks plus a remainder.
Finally, the 'Shape properties' contains the parameters of the shape; length, radius, orientation, etc., 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 in simple mode, their parameters will be preserved.
The Visualization GUI
The Visualization GUI can be opened from the main GUI by pressing the 'Visualization' button. Like the main GUI, the Visualization GUI is also accessible via a keybind. However, as most moderately modded Minecraft clients are littered with keybind conflicts, this keybind is unbound by default to avoid clutter. The Visualization 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 base position 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 base position 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 base position 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. Finally, using the arrow button at the top-left of the screen will take you back to the main GUI and, like the main GUI, pressing the 'X' button at the top-right of the screen or pressing Escape will close the GUI entirely.
Advanced mode and the Shape List GUI
When first enabling advanced mode, you'll notice that a lot of buttons have changed; the shape properties are gone, the buttons relating to the base postiion are disabled, you cannot cycle the shape anymore, and the current shape is now 'None'. The Visualization GUI is also almost completely unusable. This all happened because, at the moment, you don't have any shapes. Where you used to be able to cycle the shapes, right next to 'None', is now a button called "...". Pressing it will take you to the Shape List GUI. The Shape List GUI also has a keybind, also unbound by default, which will only open the Shape List GUI is advanced mode is enabled. This GUI also has a lot of disabled buttons which will come into play later on. Like the main GUI, the Shape List GUI is divided into four sections: 'Add new shape', 'Shapes', 'Number of blocks' and 'Global base position'. Just like the Visualization GUI, the arrow button in the top-left will take you back to the main GUI, and pressing the 'X' button in the top-right or pressing Escape will close the GUI entirely. The states of simple mode and advanced mode are preserved when switching between them.
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. Doing so will also enable all the buttons in this GUI that were disabled before. The base position for the newly added shape will be at your feet. You can freely cycle and add other shapes without affecting the ones you added before. Below the 'Add' button is a checkbox called 'Visible'. Disabling the checkbox will hide the selected shape, indicated by it now being crossed out in the shape list. Finally, 'Delete' will remove the currently selected shape from the list.
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. If you have a shape selected, the main GUI should now look (almost) like normal again; the main GUI now controls the base position and shape parameters of the selected shape. 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. Most shapes can only be odd size by default because the base position is centered on one block (for example, circles can only be 3x3, 5x5, 7x7, etc. this way). Shapes like these have all have an 'Even mode' checkbox to shift the base position half a block in relevant directions (from the previous example, circles can now only be 4x4, 6x6, 8x8, etc.).
Number of blocks
Like the 'Number of blocks' section in the main GUI, this section shows the total number of blocks as just a number and in terms of stacks. It will only count the blocks of shapes that are currently visible. Back in the main GUI, this section will only show the number of blocks of the currently selected shape.
Global base position
This section works similarly to the normal 'Base position' section in the main GUI. Using the buttons and text fields will set the base position of the currently selected shape. However, the base position of all the other shapes will also change such that the shapes will maintain the same relative positions. Also like the normal base position handling, the 'Set global base position' button has a keybind alternative under the same name, which is unbound by default.
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 base position and the point relative to the base position 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.
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'.
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.
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.
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.
A simple line. The two points the line is based on are the base position and the point relative to the base position 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.
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.
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.
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 base position 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.
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.
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. There is currently also no way of preserving shapes or states inbetween client restarts, but this may change in the future as well.
As of mod version 0.3.3, the mod jar files work for both Forge and Fabric installations, as long as they fit their respective requirements below.
Forge 1.12.2: Planned.
Forge 1.13.2: Planned.
Forge 1.14.4: Planned.
Forge 1.15.2: Planned.
Forge 1.16.5: Minecraft Forge 36.2.39 or higher.
Forge 1.17.1: Minecraft Forge 37.1.1 or higher.
Forge 1.18.2: Minecraft Forge 40.1.68 or higher.
Forge 1.19: Minecraft Forge 41.1.0 or higher.
Forge 1.19.2: Minecraft Forge 43.0.0 or higher.
Forge 1.19.3: Minecraft Forge 44.1.0 or higher.
Forge 1.19.4: Minecraft Forge 45.1.29 or higher.
Forge 1.20: Minecraft Forge 46.0.2 or higher.
Forge 1.20.1: Minecraft Forge 47.0.1 or higher.
Fabric 1.12.2: Planned.
Fabric 1.13.2: Planned.
Fabric 1.14.4: Planned.
Fabric 1.15.2: Planned.
Fabric 1.16.5: Fabric Loader 0.14.8 or higher and Fabric API 0.42.0 or higher.
Fabric 1.17.1: Fabric Loader 0.14.8 or higher and Fabric API 0.44.0 or higher.
Fabric 1.18.2: Fabric Loader 0.14.8 or higher and Fabric API 0.57.0 or higher.
Fabric 1.19: Fabric Loader 0.14.10 or higher and Fabric API 0.58.0 or higher.
Fabric 1.19.2: Fabric Loader 0.14.9 or higher and Fabric API 0.59.0 or higher.
Fabric 1.19.3: Fabric Loader 0.14.12 or higher and Fabric API 0.72.0 or higher.
Fabric 1.19.4: Fabric Loader 0.14.18 or higher and Fabric API 0.76.0 or higher.
Fabric 1.20: Fabric Loader 0.14.21 or higher and Fabric API 0.83.0 or higher.
Fabric 1.20.1: Fabric Loader 0.14.21 or higher and Fabric API 0.83.1 or higher.
Compatibility with shaders through Optifine is not guaranteed. Shaders in Optifine are know to break the projections due to an issue that appears to be on Optifine's end. Non-shader features in Optifine appear to work perfectly fine.
The mod is designed to run solely on the client. Installing the mod on a server is discouraged, but attempts have been made to prevent servers from crashing immediately and clients shouldn't be denied access for not having (the correct version of) the mod installed, though this server-side behaviour is neither supported nor guaranteed.
The configuration file can be found in a folder called `config` in your game directory, and is called `buildguide.cfg`. It can be used to configure the following options:
debugGenerationTimingsEnabled (default: false)
A debug option to print the time it takes to generate a shape to the logs.
asyncEnabled (default: true)
When this option is enabled, shapes will be generated asynchronously, meaning that the shapes will be put together in the background without having to block your client. Having this option enabled can cause shape projections to flash a bit, so
if you're sensitive to flashing images, especially if you feel discomfort while using the mod, consider disabling this option.
advancedRandomColorsDefaultEnabled (default: false)
If this option is enabled, the setting to randomly generate colors for new shapes in advanced mode ('Adv. mode random colors' in the Visualization screen) is enabled when starting Minecraft.
Feel free to add it to a modpack!