Utilizing The Custom Builder
The guide can also be found in the following GoogleDoc. Utilizing the Custom Builder
Currently we are updating and writing this wiki page, the guide has all the images required.
Zeel Nightwolf and I have been making mods for the server we play on and wanted to share some of what we have learned along the way. (FZM = FishZeelMods, original, we know.) You can find me on Discord FishAus#0367. You can get in touch with Zeel, Zeel Nightwolf#7289.
This tutorial assumes you have either done the tutorial for the ceiling-fan, and creating constructable blocks on this wiki, or are better with Unity than I am.
Before we Begin
Compatible Versions (for this tutorial): This tutorial has been tested with the below Versions. If you are using a newer or outdated version this tutorial may not work. We will try to update tutorial with the latest versions.
- Eco Version 7.3.1
- EcoModKit version updated for 0.7.3
- Unity Version 2017.3.1f1
What you Need:
- Have the above versions of Eco, and Unity Installed with the EcoModKit Setup in your Unity Project.
- To have completed and understood the FZM Eco Mod Tutorial: Creating New Constructable Blocks
- The 3 basic wall models and the materials from our download.
- For this tutorial we will need 3 Models and a Material that can be used by the models. You are free to use 3 of your own models, but we are providing the Models and Material used by us in this tutorial.
-
The models and materials are in a unity package. Once downloaded unzip the .zip file.
-
Open your project in Unity and got the menu Assets > Import Package > Custom Package. Navigate to the unzipped package on your computer and import it into Unity.
- After following our previous tutorial for creating a new constructable block, you have ended up with a single BlockSet “My Beautiful Blocks” and at least 1 CustomBuilder “Beautiful Floor”.
I will use “Beautiful”X throughout the tutorial, but if you gave your Blocks and BlockSet a different name simply use that instead.
- Create a new CustomBuilder. Right-click > Create > VoxelEngine > CustomBuilder and give it a name. We are using wall models in this tutorial so I am going to call my new CustomBuilder script “Beautiful Wall”.
- Select the new CustomBuilder and look at the Inspector Tab.
Add the material “RedWall” from the download to the Preview Material
Click the button “Open Editor”.
A new window will pop up on your screen.
- This is a fairly long step so I will break it into smaller parts so we can track our progress.
a) Here I’m going to explain what this step is going to achieve.
What we are going to do next is tell Unity what model to use for our “BeautifulWall” based on on the blocks that are neighboring it. Unity calls this block a Cube, but that doesn’t mean we need to use a cube model, it’s just a label. For clarity I will use the term Cube when referring to the block that we want to change models.
First though, we need think about our Cube and how we want it to change / behave in response to other blocks. So we are going to visualise out what we expect to happen in game.
Here is a top down look the 8 spaces around our “BeautifulWall” block in the world.
If we just want to have a straight row of these blocks then there is nothing more to do. They will line up and look like a wall. However, our “BeautifulWall” needs to know when to change.
Let’s start with something simple, only because it’s symmetrical. What if I have another wall block on each of the 4 sides of the Cube. That is, what if the situation looked like this.
We would like it to look like it is connecting to each of the walls around it, so it will need to be a + shape. We still need to set conditions for straight wall segments to rotate correctly, so don’t worry about the upper and lower walls for now, we will deal with them later in the tutorial. Let’s finish setting up our Cube becoming that + first.
b) Setting up our Cube
In the CustomBuilder screen that we just brought up in Unity click “Add New Cube”.
Drag in the model for the CrossWall to the field for the Game Object.
Once it is in place click edit to the right. The screen that comes up might look daunting but it will all be explained in the next sub-step.
c) i. Here I will explain how we want our Cube to react to the surrounding Blocks.
The screen you get represents the offset blocks of all the blocks that surround our Cube in 3D space. That "Free Space" in the middle - center represents our Cube. {Offsets are the positions that surround a block or space we care about.}
The Top, Middle and Bottom refer to the Y-Axis (in game) of the blocks that surround our Cube. Since we don’t care about the blocks above or below our cross in the Y-Axis and only the 8 blocks around our wall in the same layer, we can ignore the top and bottom layers. Leave them ticked, we just won’t apply any conditions.
Have another look out our 2D representation, this is our representation of the middle layer in Unity.
First, for our cross to form the 4 surrounding blocks need to be walls. Also, if we had wall blocks in the corners, we would want the walls to run parallel. So we do care what is in those corner boxes. If they are walls, we don’t want our cross to form. If they are NOT walls (if they are floor blocks for instance), then we would prefer the wall blocks connect.
Finally, do we want our Cube to behave this way for just “Beautiful Wall” blocks or do I want it to connect to other wall blocks? For this tutorial, we want them to connect to other wall blocks too, but you may decide otherwise for future projects.
c) ii. Now, we will make our Cube React to the surrounding blocks.
It is very easy to accidentally set conditions on a block you didn’t mean. Be careful and take your time. One of the easiest to do is try to put a condition on the "Free Space" and this can cause big issues in game if it is done. Always recheck there is no condition on this space as you can’t tell visually.
Click on the button to the exact right of [Free Space] and then hit the “Add New Rule” button.
Here is where we decide our conditions for our CrossWall to appear. For that to happen we need the block at this offset to be: Occupied By a Wall Block
Here is a quick rundown of what each of the options means:
Type: refers to a specific type of block, maybe even the very block type we are creating. If we select this then our Cube will only respond to blocks of its type and not ALL walls.
Solid: will respond to any block who has that Solid checkbox from the BlockSet definition checked.
Category: allows us to make categories of blocks. This is also done in the BlockSet. We will have a look at it later when we actually define our Wall Block there.
This seems the most logical as we could put all walls into a single category so they can work together. Since ECO already has a category for Wall blocks and Window blocks called ‘Building’, this is what were going to use.
This Type: gives you a quick way of self referencing this block type (useful for Columns)
Priority: refers to the Blend Priority also in the BlockSet definition.
Go ahead and select “Equals Category” and enter ‘Building’ into the field.
Repeat the condition for the four blocks surrounding the "Free Space" as per the picture below.
Next, we put the condition from the corner blocks of the CrossWall need to make sure the corner blocks are not walls. So let’s go ahead and set a condition for each of those offsets to **“NOT Equals Category” **and enter ‘Building’ in the field.
Since we are relying on these rules to match the category we set elsewhere SPELLING IS VERY IMPORTANT here as this is how things link together. Make sure you have the Building spelt correctly and with a capital ‘B’.
We now have our offsets set-up for our Cube, let’s look at the other settings below.
_Apply Rules To Rotations: allows us to to use world symmetry and have our rules apply around a particular axis. It’s not really crucial for an already symmetrical situation but it doesn’t hurt to leave it on. _
Rotation Axis: is the axis to check for the symmetry. This will almost always be the Y axis for our building blocks.
Don’t rotate Mesh: would leave the mesh in place this is unlikely to be practical for building purposes. Leave it Unchecked.
Import Rotation: Highly important for stairs, not much for anything else. Because of how stairs work we need to have 4 CustomBuilders for stairs but can get away with 1 model and just import the model rotated.
Decoration Builder Count: leave 0.
- Our CrossWall is done. Only we really need to implement a straight wall to see it in action. Let’s do that now. Click “Add New Cube”. This time Drag in the ‘StraightWall’ model from the project window and click ‘Edit’.
We would like our straight piece to be straight unless something causes it to change.
If we reconsider this image, we can see that in order for the wall to be straight we need to not have the top or bottom block there.
The blocks on the side don’t really matter if they are there or not, but if they are, adding the top or bottom wall will change our Cube (To a cross or, later, a T).
So we need to set up conditions which say our Cube is straight If the top and bottom block are NOT walls.
In the middle layer for the top and bottom offset set the condition to “NOT Equals Category” and enter ‘Building’ in the field, like we did for the corner blocks of the CrossWall.
We will leave these settings like we had them for the CrossWall, symmetry will take care of the rest for us… and you told your math teacher you’d never use geometry!
- With those two conditions done lets set up our BlockSet so we can check the progress we’re making in game. We have done in the previous tutorial so we will recap quickly. Select your BlockSet from your project window.
Click New Block in the Inspector Tab.
Name: BeautifulWall
Layer: Terrain
Category: Building Here is that link to the category we set.
Builder: drag in the “BeautifulWall” CustomBuilder
Material: Add the ‘RedWall’ material supplied
Solid, BuildCollider? And Rendered all checked.
Shader: Curved/Standard
Leave everything else alone.
- Add a C# definition for our new wall block… in the same .cs file as the previous tutorial add the following class. Don’t forget the class name must match the name in the BlockSet + “Block”.
[Serialized]
[Constructed, Solid, Wall]
[IsForm("Wall", typeof(BeautifulBlockItem))]
public partial class BeautifulWallBlock : Block
{ }
- Let’s Export our modkit!
If everything is done correctly then we should be able to see the following in game after giving yourself some BeautifulBlocks.
Don’t be surprised if your models don’t show before placing, or maybe are even invisible on placement until they connect. Remember we have only set up SOME of the conditions we need. The most efficient way to place your blocks to test would be to place the 4 outside walls and then place the 5th wall in the centre and watch it place as a CrossWall.
Looks great. But if you played with it a bit you know we are certainly not finished. We need to consider all our possible Cubes. So let’s go back and do that.
- Reopen our Unity project and head to our Beautiful Wall CustomBuilder.
Let’s set up a T-Wall Cube. Go Ahead and open up the CustomBuilder Editor and “Add New Cube” Drag in the WallT model and set your conditions up.
Have a think about what you think you need before checking ours below.
Here is a diagram to help you think about it.
The 3 blue must be ’Building’… But what about the spaces? Is it important what is there?
The spaces above and below the wall offset that forms the T are important to have NOT Building, if they were building then the offset to the right should possibly connect with those as a StraightWall and therefore our Cube should also be straight.
If we had a block to the left offset then we would need a CrossWall not a TWall. The other two offsets are not important as whatever is there won’t actually change our Cube in this instance.
Make sure the bottom settings are still our default settings and we can move on.
- Next we need a CornerWall, We are going to copy what the Hewn Logs do and just make our corner block look like a CrossWall.
Click on “Add New Cube” drag in the crosswall model to the new slot and click on edit. Hopefully your getting the hang of thinking about what you need to set up for your rules. Here is the setup for the corner block.
- This list of Cubes we are creating runs down the page to check which block it should be. This means we need to be smart about the order because once it gets to a condition that is satisfied it stop checking further. That means our wall with the fewest conditions on it could potentially be reached first even if we really want it to be a different block. Let’s do a bit of reordering. Use the Up and Down arrows to reorder the Cubes in the list.
Our list is now:
- CrossWall
- TWall
- Corner (using the CrossWall model)
- StraightWall
Now we have created the four most common variations of the wall and thanks to the power of symmetry they should be working from whichever angle.
- If we play with our wall blocks in world for a bit we might come across one the following 2 scenarios…
Honestly, neither of these two scenarios is the end of the world right?
Well, that really depends on what we are building with around our new wall blocks.
- There are some things we can do to fix this though. Lets “Add New Cube” to our wall CustomBuilder.
Drag in the straight wall and click edit.
Let’s create a condition that if there is a wall running along below our straight wall piece and there is NOT walls on the same level that would make it go it the opposite direction to have it face the same way as the wall below. Here is how we do that.
Notice we have put this higher in our list, because we want to check for this scenario before it just places the straight wall.
- Go ahead and create an identical condition but for a wall running above our Cube. Place it below the bottom wall (to give the underneath wall priority) but above the standard wall condition.
- Our wall is really starting to act the way we want it to. What happens if we try to place 4 of our walls down in a 2X2 area.
Well, It’s no wall but it looks ok right?
Let’s try placing a wall coming away from that cube.
This is less than ideal.. Sure we could pick up our cube and use a “Form” that is not a wall for this situation, but we don’t really want to have graphical glitches like this on our model.
- “Add New Cube” and drag in the T-Wall, this is going to be below our straight wall now because we want to have all the other possibilities selected first before our glitch fixes need to be used.
Create conditions that are almost identical to the T-Wall rules but ignore the NOT rules for the corner blocks.
- “Add New Cube” and drag in the CrossWall, this is going to be below our Glitch T-Wall fix as our final check.
We don’t need any conditions for this one. Basically we are saying, if the checker makes it passed everything above, just make our Cube a cross wall.
Go ahead and test it in game.
No more glitchy cubes.
- Now we know how to use the Custom Builder and how to use it to stylise your building blocks.
This process is the same for anytype of block you need to change based on its neighbours.
Columns are pretty simple they check above and below to decide if they are a bottom ,middle or top block. Using the This Type rule for those will mean the Cubes won't try and change if another column is stacked on top.
Roofs are very complicated and will take a fair amount of testing and multiple models to look good.
Thanks again, hope it’s been useful
End of Tutorial.
Acknowledgements:
Thanks to the following people in assisting getting this tutorial out in any of it’s revisions…
-
ZeelNightwolf, for providing editing, information, models for tutorial and general moral support :)
-
Psycho Romeo, for providing more awesome feedback on improving the simplicity, layout and language used throughout the tutorial. Also for putting up with Zeel and I arguing while reading the tutorial.
-
zEverdeen, for providing feedback on flow and readability.
-
Strange Loop Games, for providing the game, and the EcoModKit.