ProBuilder 2.0 Documentation
2-4-2013
r531
~
Table of Contents:
[1] Helpful Links and Info
[2] Overview of ProBuilder 2.0
ProBuilder 1.x vs ProBuilder 2.0: ProBuilder 2.0 is a complete, from scratch, rebuild and overhaul of ProBuilder 1.x. The entire tool has a vastly improved interface and workflow, much more efficient final builds, and a whole new feature set, far beyond ProBuilder 1.x.
ProBuilder is a custom editor extension for the Unity 3D game engine, one that brings some very exciting and powerful new features to the engine. With ProBuilder, you can finally build, edit, and texture custom geometry with an extremely fluid, intuitive, and fast workflow. You can even manipulate UV direction, tiling, offset, rotation, and more.
Using ProBuilder, you can also quickly setup very efficient collision and occlusion, and trigger volumes for events, switches, and zones.
At it's core, building your game environment in ProBuilder is simply fast, intuitive, and fun! There is no more "go between", importing and loading times, or tedious trial and error. With ProBuilder, you just BUILD. You create, edit, and manipulate and your game world, as fast as you can imagine it.
[3] Installing and Upgrading
[3-a] Installing ProBuilder 2.0 in a new Project
Import the Unity Package, then from the top menu choose “Window > ProBuilder > QuickStart”. An install screen will appear- choose “New Install”, then just follow the on-screen instructions.
[3-b] Upgrading from an older version of ProBuilder, or 2.0 Beta
WARNING: The upgrade process is NOT reversible, and if an error occurs, you will almost certainly lose all your work. Make a backup of your entire project!
Import the Unity Package, then from the top menu choose “Window > ProBuilder > QuickStart”. An install screen will appear- choose “Upgrade”, then just follow the on-screen instructions.
We are 100% dedicated to making your 1.0 and Beta scenes upgrade properly to 2.0. However, the systems are entirely different, so upgrading is still not error-proof. If you encounter an error, please do not hesitate to email us at “contact@sixbysevenstudio.com”, or post on the forums at “www.sixbysevenstudio.com/forum”. We will get it working!
[4] Introduction to World Building with ProBuilder
(Coming soon!)
[5] Interface Overview
[5-a] Opening the ProBuilder GUI Panel
In order to begin creating with ProBuilder, you’ll need the ProBuilder GUI Panel open. This is done by selecting, from the top menu bar in Unity:
Window > ProBuilder > ProBuilder Window
This will open the ProBuilder GUI Panel, which you can leave floating, or dock in the GUI.
[5-b] Using the ProBuilder 2.0 GUI Panel
The ProBuilder 2.0 interface is built to use up very little space on your screen, but still have all the functionality you will need for 98% of construction:
Editing Mode: When working with ProBuilder, you are always in one of three modes: Object Editing, Geometry Editing, or Texture Editing.
Object Editing is the default, standard mode- this is essentially “nothing special” mode- you can select, move, rotate, delete, etc, just like you normally would. To exit any other mode, and return to Object Editing mode, simply press the “Escape” key on your keyboard.
Geometry Editing mode allows you to edit the actual geometry of any ProBuilder object, either by Face or Vertex. Hit the “G” key on your keyboard to enter Geometry Editing mode. You will instantly enter either Face Geometry Editing, or Vertex Geometry Editing, depending on which you have set as default in the ProBuilder Editor Preferences.
Face Geometry Editing allows you to select and manipulate the faces of ProBuilder Objects. Once in this mode, simply left-click to select a face, (use the standard shift-left-click to select multiple), and manipulate them with with the standard unity movement handles. To toggle into Vertex Geometry Editing, hit the “H” key on your keyboard.
Vertex Geometry Editing gives you even finer control, right down to the individual vertices. Since showing all the vertices in a complex scene could very likely crash Unity, you must select any ProBuilder Objects whose vertices you intend to edit. Their vertices will immediately show up as blue dots, and can then be selected (their color will change to green) and manipulated. You can drag-select vertices, and use the “Shift” key to add to the selection, just like any other item in Unity. ProTip- click on a face to instantly select all of it’s connected vertices! To toggle into Face Geometry Editing, hit the “H” key on your keyboard.
Texture Editing mode opens the Texture and UV Tools panel, giving you access to the powerful uv and texturing toolset of ProBuilder. Just like Face Geometry Editing, left-click to select a single face, and use the standard shift-left-click to select additional faces. Then use the Texture and UV Tools panel to apply textures, set UV tiling, rotation, and offset, and more. Hit the “J” key on your keyboard to enter Texture Editing mode.
See the “Geometry Editing” and “Texture and UV Editing” sections for more details.
Coordinate Space: This setting controls the direction of the handles when editing faces or vertices.
Planar: movement relative the selected face
Global: Movement in the “Global” XYZ directions
Local: Movement relative to the object’s transform orientation
Not making sense? This can be a confusing subject the first time you encounter it. Stick with “Global”, and give each of the others a try from time to time- they will make better sense with practice, than I could ever explain. You will soon find these are incredibly handy for complex construction. Hit the “P” key on your keyboard to swap between Coordinate Space modes.
Create New Shape: Click this button to open the “Create New Shape” panel, which allows you to instantly construct user-configurable special Shapes.
To create a shape, select a type (Cube, Stairs, Plane, etc) from the drop down list. The Create New Shape panel will change it’s contents to match the selected type, displaying different options for each:
Merge Objects: Click this button to merge all selected ProBuilder objects into one single ProBuilder Object, with the option to save or delete the originals. If you choose to save the originals, they will simply be deactivated in the scene- their names will appear greyed-out in the hierarchy list.
Merging objects is a great way to make your game run more efficiently, since it combines meshes and therefore lowers draw calls- very important for mobile games! However, be aware that if there are multiple materials on the resulting object, each material will still incur a separate draw call- this is just the way Unity works.
Create AutoCollapse Group: Click this button to create a new AutoCollapse Group (ACG) from all selected ProBuilder objects. The objects will be parented to an empty game object in the hierarchy. Only upon scene start, will the objects will be merged down to one single mesh. NOTE: this feature has been removed temporarily, but will be back soon!
Creating ACGs, much like Merging, is a very effective way to maximize your game’s performance. ACGs have the advantage of staying separate objects in the editor, but auto-merging in the game. However, at the time of writing this, they can sometimes result in slightly more draw calls than Merging in the editor, since lightmapping does not always keep all objects in the ACG on the same sheet. This will be fixed in an upcoming release!
Create ProBuilder Group: This button will parent all selected ProBuilder objects to a new, empty game object. The result is a “group” that can be moved or rotated as one single object, a handy technique to use as your scenes grow more and more complex.
Create New Prefab: Prefab support, at the time of writing, is still very basic in Probuilder 2.0. Due to this, you must use the special “Create New Prefab” button to create prefabs!
Clicking this button will create a prefab object, replicating all selected ProBuilder objects, and place that prefab object direction in the root of your Assets folder.
Unfortunately, the “Apply” and “Revert” prefab buttons do not work correctly yet. We aim to fully support prefabs very soon, as they are core to an efficient workflow in Unity.
Prepare Scene for Lightmapping: Clicking this button will update and prepare all ProBuilder objects in the scene for lightmapping. You must press this before lightmapping, or your UV2 channels will not be set correctly.
VisGroups: ProBuilder 2.0 identifies 5 unique Entity Types for ProBuilder objects: Detail, World, Collision, Trigger, and NoDraw. Click any of the five VisGroup buttons to toggle their respective Entity Type’s visibility on and off- this is an incredibly handy visual aid, in both simple and complex scenes. See the “VisGroups and Entity Types” section for more information, you’ll be using these quite a bit!
[6] Building and Editing Geometry (Modeling)
In the previous section, we went over the technical details of how to construct and edit geometry with ProBuilder. Before you jump right in though, you should definitely watch the ProBuilder “Intro to Modeling” tutorial- it’s fairly quick but extremely informative. Here, we’ll go over some basic tips, tricks, and advice for modeling with ProBuilder 2.0:
Use ProGrids! If you are not using ProGrids, at least the free version, you are seriously handicapping yourself. With ProBuilder, you will most often be constructing hard-surface models, with many parts that need to align exactly, match sizes, and so forth. ProGrids will save you hours of time and sanity, and your resulting creation will look and function better as well.
Stay “On The Grid”. Now that you are using ProGrids, stay on that grid! Making sure all your vertices are on an exact grid point will make your ProBuilder objects much, much simpler to align, edit, and modify.
Start Big. The first version you build won’t always be wrong, but it won’t ever be right, either. So, start with with large, simple, boxy construction- I typically start at a grid level of 50cm, sometimes 25 if I’m feeling extra confident in the design. If you are building a level or world, test out the flow, fit, and scale. Even do some lighting and atmosphere tests, really get a feel for what you are constructing. Then pair it down to smaller and smaller grid levels, adding more detail with each level, just like LODs.
Stick to 45 Degree Angles. If you need to make an angle, always try to keep it at 45 degrees
Textures Come Last. Greybox that level completely, before you even think about adding real textures! Use the included dev materials (grey, orange, red, blue) to differentiate your level/world/item as needed, but save the real texturing for the very last. Only once the geometry is 95% finished and final, should you begin adding real textures, else you risk wasting many hours of work when that geometry you painted has to change...
Use NoDraw. NoDraw might seem a little strange at first, but use the shortcuts provided plus the “Auto NoDraw” action, and you will be a pro in no time. The performance savings will be huge, and your lightmaps will take MUCH less time to bake! See the NoDraw section for more details.
Assign “World” Geometry. Only ProBuilder objects that are given the “World” entity type will occlude other objects. This isn’t the default type, so you have to assign it manually. See the VisGroups section for more details.
[7] Textures and UVs
[7-a] The Texture and UV Tool Panel
ProBuilder’s Texture and UV Tool panel is one of it’s most powerful and useful features. It is automatically opened when you enter Texture Edit mode, by hitting “J” on your keyboard.
Firstly, it facilitates extremely fast, simple, “painting” of materials onto your ProBuilder objects, and even allows painting a different material on each and every face, should you need to.
Secondly, It allows you to change how a material is displayed on individual faces of your ProBuilder objects, without editing the material itself. This means you can create infinite variations, with still just a single draw call.
Material Slot: Drag ‘n drop the material you intend to use, into this slot...
Open Material Browser: ...or, click the small circle-with-a-dot to open the standard Unity Material Browser, and choose your material there.
Preview of Ready-To-Paint Material: This area shows a flat preview of your selected material. I will size itself according to the panel size.
Apply Material: Applies the material to all selected faces.
Flip U or V: Use these toggles to flip, or “mirror” the selected face’s UV coordinates.
Swap U and V: Use this toggle to completely swap the selected face’s UV coordinates.
Face Highlight on/off: When on, all selected faces will be highlighted. You can change the color and opacity of this highlight in the Editor Preferences panel, see the “Customization” section for more details.
Horizontal/Vertical Scale: This number controls scale, or “tiling”, of the selected face’s UVs.
Horizontal/Vertical Offset: This number controls offset, or “position”, of the selected face’s UVs. You can use the Movement handles to move your texture around very intuitively and easily!
Rotation: This number controls the rotation, in degrees, of the selected face’s UVs.
[7-b] Applying Materials (“Texturing”)
First, a note on definition and methodology: somewhere along the way in game engine development, the difference between “Texture” and “Material” became a source of much confusion and misinterpretation. In the case of ProBuilder, just know this- nothing special at all is happening with materials or textures. You apply materials to your ProBuilder objects just like any other object, and those materials will act/display just the same, as well.
That aside, there are several ways to apply materials in ProBuilder. All of the following methods assume you are already in Texture Edit mode, and have a material set in the Material Slot of the Texture and UV Tools panel:
Apply To Entire Object(s): To apply one material to an entire object, or several objects, first select the full object(s) by either drag-selecting a box, or selecting via the Hierarchy. Click the “Apply Material” button to instantly paint all faces of the selected object(s) with the chosen material.
Apply to Selected Face(s): Select one or more faces, then click the “Apply Material” button to instantly paint all selected faces with the chosen material.
Quick Paint: This one is very handy! While holding ctrl and shift on the keyboard, any face you left-click on will be instantly be painted with the chosen material.
[7-c] Editing UVs
Being able to edit the individual UVs of each face on a ProBuilder Object, allows for virtually infinite variation and re-use of textures. This is great for both performance and making your scene look great!
For example, use the Flip and Swap U/V toggles to quickly make three different faces look different, despite using the same material. These are also handy if your texture needs to have a specific direction (arrows, grids, text, etc).
Use Offset to move textures around, displaying only certain parts of the texture per-face, or in an exact location. You can even use the movement handles for quick, intuitive control of placement.
Scale, or “tiling”, is extremely handy for controlling the perceived size of an item, fitting textures to geometry, and lessening obviously tiling patterns.
The Fill Mode options allow you control over the basic method of UV mapping that is applied to the selected face(s):
UV Justify can anchor the texture to any of the 4 sides of a face, or to the center. Very useful in situations where you need the texture placement to stay put while you edit geometry.
Projection gives you advanced control over exactly how the texture is “projected” onto the surface. 99% of the time you will want to just leave this on Auto, however the option is available just for those special, niche situations where nothing else will work, and such control is needed.
[8] VisGroups and Entity Types
All ProBuilder objects have an Entity Type, or simply “type”. These are basically categories, like “Melee, Ranged, Explosive, etc”- they set certain properties in the object, and how it acts in your game.
VisGroups are simply a very handy side effect of these Entity Types. Since all ProBuilder objects have a type, and you generally don’t need to see all types at once, you can use the VisGroups panel to toggle the visibility on or off for each “group” of types. This becomes extremely useful as your scenes become more and more detailed/complex.
Detail is the standard, default ProBuilder Object type. A mesh with a texture and a collider, nothing more. It can be occluded, but will not occlude other objects. This is set as default, since too many occluders will actually hurt performance much more than too few. Set any ProBuilder object(s) to “Detail” type by selecting them, and hitting the “B” key on your keyboard.
World type objects are same as Detail, except they do occlude other objects. If you have large, simple objects, ones that you know will block larger portions of your level from view, they should probably be set as “World” type. Set any ProBuilder object(s) to “World” type by selecting them, and hitting the “O” key on your keyboard.
Collision objects are invisible in-game, but still have full collision. These are very handy for smoothing stairways into ramps, adding player clip to round out sharp corners, force fields, and many other semi-advanced uses. They will show in the editor as bright-green and semi transparent. Naturally, they do not occlude or block light. However, you should always disable them via VisGroups panel before lightmapping, or their color will affect nearby areas. Set any ProBuilder object(s) to “Collision” type by selecting them, and hitting the “C” key on your keyboard.
Triggers are a special type of ProBuilder object, designed specifically to aid in the creation of Zones, Volumes, and (of course) Triggers. They are invisible in game, but have a collision component set to “trigger”. This makes them great for things like triggering elevators, doors, or cutscenes (as the player enters or exits the Trigger zone), designating “Kill Zones” or FX Volumes, and so forth. Set any ProBuilder object(s) to “Trigger” type by selecting them, and hitting the “T” key on your keyboard.
NoDraw is actually not an Entity Type, but does have a VisGroup dedicated to it. “NoDraw” refers to any ProBuilder Object’s face that has the NoDraw material applied to it. Toggling on/off the NoDraw VisGroup will show/hide all faces (not the entire object) that have NoDraw applied. You should be using NoDraw a lot, so be sure to read the “Optimization” section below for details on it’s use and methods!
[9] Optimization
ProBuilder 2.0 is very efficient on it’s own- in fact it is 6x more efficient than ProBuilder 1.x without any work on your part, due to using a single mesh per object now. On top of that, we have expanded the already existing optimization methods, and added a few new ones- all of which are simple to implement, and will seriously aid your project.
NoDraw will be your primary method of optimization. Any face that will never be seen in-game, should always be set as “NoDraw”. These faces will be deleted at runtime, which makes a substantial dent in the number of vertices being rendered. Most importantly, NoDraw faces are not lightmapped, which saves you quite a bit of texture space, and saves you time when baking lightmaps. Do not underestimate this- if done properly, NoDraw faces will be around 40-60% of your scene!
Setting a face as NoDraw is quick and simple- simply apply the “NoDraw” material to it. However, you must do this via the Texture and UV Tools panel, not by simply drag-and-dropping the material onto the object.
While in Texture Edit mode, you can also select any number of faces, and hit “N” on the keyboard to apply the NoDraw material, without changing your chosen material.
Lastly, there is also the “Auto NoDraw” action available from the top Unity menu, under “Window > ProBuilder > Actions > Auto NoDraw”. This will automatically apply NoDraw to all faces that appear to be completely occluded, and is a quick way to get all those annoying small/inner/hidden faces. However, be aware that this action is somewhat experimental still, and while it will get all the hidden faces, it often will apply NoDraw to incorrect faces as well. In general though, it’s much faster (and more accurate) to use Auto NoDraw, and then fix it’s few mistakes, than to hunt down each and every face yourself.
ProTip- when starting out, build your entire scene in NoDraw, then only apply “real” materials to those faces you are certain you will see.
Occlusion is your second best method of optimization. Wherever you have large, simple ProBuilder objects, assign them the “World” Entity Type. This will let them take advantage of Unity’s Occlusion system, by becoming Occluders.
However, Occlusion’s benefits are very much situational. Too much Occlusion can be worse than too little- the game needs to calculate what can and can’t be seen, and if you have a very complex Occlusion setup, it can easily crush your framerate. On the other hand, if you have a room with lots of high-poly objects inside, even a complex Occluder might be worthwhile. Further, if you use purely static Occlusion data, then you can use quite a few more Occluders without hurting performance, and vice versa if using a more dynamic Occlusion method.
Occlusion can be tricky at first, but will yield serious performance benefits, so don’t overlook it. Experiment with this one, and read up on Unity’s Occlusion system for the best results.
Merging allows you to collapse multiple ProBuilder objects into one single object, while still being able to edit it like any other ProBuilder object. This is mainly useful for reducing draw calls. See “Merging” in the “Interface Overview” section for details on using this function.
AutoCollapse Groups work the same as Merging, but don’t actually merge down to a single object until entering the game. This is useful when you don’t want to completely merge objects in the editor, but still need them to merge in-game. See “AutoCollapse Groups” in the “Interface Overview” section for details on using this function. NOTE: this feature has been removed temporarily, but will be back soon!
Custom Collision should be used wherever possible, as it can significantly reduce in-game overhead and pre-game loading times. Essentially, anywhere that you can reduce a complex collider, or a group of colliders, down to a single, simple collider, you should use Custom Collision.
A good example of this is a stairway- if you left it’s collision default, each and every step is part of the collision, and it would also be non-convex. Instead, disable the stairway’s collision component, then create a ProBuilder Object that matches the stairways slope. Set this Object to the “Collision” Entity Type by pressing “C” on your keyboard, and give the stairway a test run- not only will your game run better, but you can now move smoothly up and down the stairway, without those annoying “bumping” and collision-snagging actions that happen far too often in sub-par games. Here is an image for better illustration:
Do Not Scale ProBuilder Objects! Scaling breaks batching (bad for draw calls), skews UV coordinates, causes havoc with scripting, and (probably) rips the very fabric of the universe. The only thing worse than scaling, is the dreaded Boolean. Please, just trust us on this one!
Lightmap Size is a special fix that involves using a separate script, so we left it for last. Essentially, all the visual optimizations in ProBuilder are geared toward reducing draw calls- this is mostly done by getting objects to “batch” in the renderer. In an ideal game, every single mesh that uses the same material will batch down to one single draw call. You could have thousands of items, and only one draw call- as long as they all batch properly.
Unfortunately, there are lots of things that break batching- scaling, as mentioned is one of those. Another, trickier one, is lightmap index.
Lets say you have 10 objects, you lightmap your scene, and end up with 2 lightmaps at 1024x1024 each. All objects should batch down to one, but you get 2 draw calls- why? Because you have more than one lightmap, and therefore, technically more than one material. This can get really ugly in a real-world situation, where you have multiple materials, and once you lightmap, your objects are spread throughout the lightmaps, allowing only a few or none to actually batch.
So, the solution is bigger lightmaps. And you can control that via this very handy script:
http://forum.unity3d.com/threads/56435-light-map-max-at-1k-solved
All credit for this “Optimization”, and many thanks, goes to the forum users in the above linked post. We will be implementing our own version of this, as part of the ProBuilder 2.0 GUI, but for now just use the above script to set your lightmap size to larger than 1k (1024).
Each time after building your maps at larger than 1K size, you will also need to reset the lightmap texture’s import settings to “Max: 4K”, as well.
[10] Lightmapping
ProBuilder automatically generates perfectly sized, normalized, UV2 channels for each and every ProBuilder Object. There are a few things to keep in mind when lightmapping, however:
Lightmap Size: As mentioned above, make sure you use the largest lightmap size possible. For mobile devices and web/flash, I wouldn’t go over 2K (2048x2048), but otherwise 4096 should be perfectly fine, if you need it.
Use NoDraw: Without using NoDraw, your lightmaps will, on average, be about 2-3 times the size they should be- bad for baking time and game performance. So use that NoDraw wherever possible!
Miter Corners: This is a throw-back to the days of Hammer, Radient, etc, but still very much applies, even with non-ProBuilder meshes. Take a look at this illustration:
(Illustration credit to “camydoger” on www.tf2maps.net)
Figure 1 will allow light and/or shadows to “leak” and “bleed” under the edges, causing visual seems, artifacts, and wasted lightmap texture space.
Figure 2 is the OCD mapper’s method, and honestly the best- the mitered corners make sure zero light/shadows can leak or bleed, and no space is wasted.
Figure 3 is technically just as good as Figure 2, but not as clean on the corners.
Prepare Scene for Lightmapping button must be pressed before lightmapping. Also, If you notice your lightmaps changing/breaking after a ProBuilder Object has been selected,, press this button to force UV2 channels to rebuild, and fix the issue.
[11] Customizing ProBuilder 2.0
Also new in ProBuilder 2.0 is the ability to customize many of the tools features, visuals, and shortcuts. To open the ProBuilder Customization Panel, click on “Edit > Preferences”, in the Unity top menu, which will open the Editor Preferences window. Choose the “ProBuilder” tab, and you will be presented with the following options:
Edit as much as you like, and simply press “Use Defaults” if you would like to return to the standard configuration. We really hope everyone enjoys and uses this new feature, it should be very useful for those who want a specific keyboard layout, visuals, and workflow.
This documentation is still in-progress, so please post any questions, comments, or suggestions for improvement on the forum at: “www.sixbysevenstudio.com/forum”, or email to “contact@sixbysevenstudio.com”. Thanks, and happy building!