Geometry Scripting Through Blueprints

Geometry Scripting provides Blueprint and Python functions for creating custom modeling tools and workflows. This guide covers the fundamentals of using Geometry Scripting through Blueprints. The steps below go through generating a procedural mesh tool for level design, similar to the geometry tools created for the Lyra sample project.

This guide shows you how to:

• Generate procedural geometry for quick level blocking.

• Use boolean operations to cut out a mesh dynamically.

• Create a Static Mesh bake function.

The tool you develop is a small example of procedural mesh generation and tools you can create with Geometry Scripting. An advanced example is the Procedural Content Generation Framework, which uses Geometry Scripting as a base. To learn more about this toolset, see Procedural Content Generation Overview.

Additional workflows you can create besides procedural generation include:

• Assigning multiple materials to assets .

• Applying mesh booleans with Python.

• Generating Blocking Volumes based on convex hulls.

Prerequisite Knowledge

To understand and use the content on this page, you must:

• Have a fundamental understanding of Blueprints.

• Be familiar with the introductory topic of Geometry Scripting, specifically the new object types introduced.

Enabling Plugin

Using Geometry Scripting requires having the associated plugin enabled.

To enable the plugin or verify that it is already enabled:

1. In the Menu Bar, select Edit > Plugins.

2. In the search bar, type "geometry script".

3. Enable Geometry Script plugin, and select Yes in the dialog popup.
   

4. Restart the engine.

Creating a Blueprint Class

To get started, you must ensure you have the correct Blueprint class. Since the goal is to create a procedural mesh for level design, you need to use the GeneratedDynamicMeshActor class.

To select a Blueprint class:

1. In the Content Browser, right-click and select Blueprint Class.

2. Search for and select GeneratedDynamicMeshActor.

3. Name the Blueprint BP_ProceduralGen.

Event Setup

After creating the class, you must set up the specific event to populate the Dynamic Mesh you will use for building your tool.

To create the event:

1. In the Content Browser, double-click the Blueprint class.

2. Open the Event Graph.

3. Right-click in the graph, and type "generated mesh" to filter the available nodes, then select Event on Rebuild Generated Mesh. This event triggers every time you update the parameters of the Dynamic Mesh–causing the mesh to be rebuilt.
   

4. Promote the Target Mesh output to a local variable by right-clicking its pin and selecting Promote to Variable.

5. Name the variable DynamicMesh, set the type to Dynamic Mesh, and keep it private. This variable represents the Dynamic Mesh you edit.

Building Geometry

With the Blueprint class and event created, you can begin adding geometry scripting functions. The goal in this guide is to generate block-out shapes that you can transform and cut out. For that, you need first create the mesh you want to edit.

To create a mesh:

1. Drag off the DynamicMesh variable's execution pin, then search and select the Append Box node. This adds a box primitive to the Dynamic Mesh.

2. Connect the out pin of the DynamicMesh variable to the Target Mesh input pin.

With these first few nodes, you have created a procedural mesh. You can test it by compiling and dragging the Blueprint into your Level. To learn what other shapes you can instantly make, see the Primitive Generation section of the Geometry Scripting Reference document.

Adding Transformation Widget

In order to be able to dynamically adjust the transformation of your mesh, you can add interactive controls.

To add interactive controls:

1. Create a new public variable called BoxSize and set the type to Vector.

2. In the Details panel of this variable, enable Instance Editable and Show 3D widget. Set the Default Value to 200, 200, 200. Enabling the 3D widget creates a manipulator for interactively controlling the X, Y, and Z transforms.

3. Drag out the variable and select Get BoxSize.

4. Right-click the variable and select Split Struct Pin. The X, Y, and Z values of the variable will drive the dimensions of the box.

5. Connect the corresponding X, Y, and Z values to the respective dimension values of Append Box.

6. Compile (Ctrl + Alt) and Save (Ctrl + S).

You can now generate a cube mesh and dynamically adjust the dimensions. Each adjustment with the widget generates a new dynamic mesh of the set size versus scaling the mesh.

Editing with Booleans

Boolean operations subtract or add mesh pairs. These are helpful for quickly adding detail and displacement effects to your mesh. To create the second mesh for the boolean function, you can allocate a temporary mesh from a mesh pool. The temporary mesh avoids unnecessary geometry in the editor, which puts less strain on computing processing.

To create a boolean operation:

1. Right-click the graph, then search and select Get Compute Mesh Pool. This allocates a temporary mesh to perform a boolean operation.

2. Pin Append Box's execution pin to Get Compute Mesh Pool.

3. Drag out the Return Value pin, then search and select Request Mesh. Connect the execution pins.

4. Drag out the Return Value pin, then search and select Append Cylinder. This node adds a cylinder mesh that you will use to subtract from the box mesh.
   

5. Promote the output Target Mesh to a variable called BoolMesh. Set the type to Dynamic Mesh and leave it private.

6. Drag out the execution pin of BoolMesh, then search and select Apply Mesh Boolean. You will use this node to apply the boolean operation to your mesh.

7. Drag out and connect the DynamicMesh variable to the Target Mesh input of Apply Mesh Boolean.

8. Connect BoolMesh to the Tool Mesh pin of Apply Mesh Boolean. Tool Mesh represents the mesh you want to do the boolean with. This parameter is why you added the Append Cylinder node.

9. Set the Operation type in the Apply Mesh Boolean node to Subtract.

10. After applying the needed operations, you must return the temporary mesh to the pool so its memory can be reused. Connect the execution pin of Apply Mesh Boolean to Release All Compute Meshes. When the event is triggered, all compute meshes the pool has allocated will be released.

11. Compile (Ctrl + Alt) and Save (Ctrl + S).

Adding Widgets

Just as you created a widget for the box primitive, you can do the same for the boolean mesh and location.

To create a widget:

1. Under the Variables panel, create a public variable for the location of the boolean mesh, name it BoolLocation, and set the type to Vector.

2. In the Details panel, enable Instance Editable and Show 3D widget.

3. Right-click the Transform pin of the Append Cylinder node, select Split Struct Pin, then connect the BoolLocation variable to the Transform Location.

4. Create another public variable, name it BoolSize, and set the type to Vector. You can use this to adjust the size of the boolean mesh.

5. In the Details panel, enable Instance Editable and Show 3D widget, then set the Default Value to 1, 1, and 5.

6. Drag the variable into the graph and select Get Bool Size.

7. Right-click the pin and select Split Struct Pin.

8. Connect the Bool Size pins to the corresponding Transform Scale pins of the Append Cylinder node.

9. Compile (Ctrl + Alt) and Save (Ctrl + S).

You now have a mesh you can dynamically transform into different shapes.

Bake to Static Mesh Function

Now that you have your dynamically generated mesh, you can apply it to existing Static Meshes for quick level design. To do so, you can create a function and expose it to the Level Editor's Details panel.

To control when Static Meshes are updated:

1. Create a new function called Bake Static Mesh.

2. In the Details panel of the function, enable Call in Editor to activate the event from the Level Editor.

3. Drag off the function's execution pin, then search for and select Get Dynamic Mesh. The function pulls the Dynamic Mesh currently in use.

4. Drag off the Get Dynamic Mesh execution pin, then search for and select Copy Mesh to Static Mesh. Also, connect the Return Value to From Dynamic Mesh. When the function executes, the Dynamic Mesh is baked to the selected Static Mesh.

5. To select the Static Mesh you want to bake, you must expose the parameter to the editor. Create a public variable, call it TargetMesh, and set the type to Static Mesh.

6. Drag the variable into the graph and select Get TargetMesh.

7. Right-click the variable pin and select Convert to Validated Get. This conversion sets up the function to only run the code if you have a mesh selected.
   

8. Connect Target Mesh pin to To Static Mesh Asset.

   Finale Bake Script.

9. Compile and Save.

10. A Bake to Static Mesh button now appears in theLevel Editor's Details panel. Before using the button, update the Target Mesh to the Static Mesh you want to bake.
    

Reviewing End Results

With the Bake Static Mesh function and procedural mesh script, you can use the Dynamic Mesh to update the Static Meshes in your Level continually.

On Your Own

Using what you learned try making the following adjustments:

• Change the box mesh to a sphere.

• Add a second boolean mesh for extra modeling control.

• Use the Create New Static Mesh Asset From Mesh to bake the Dynamic Mesh to a new Static Mesh instead of an existing one.