Gradientspace Script
Gradientspace Script, or GSS, is a set of UFunction Libraries intended for use in Unreal Engine Blueprints. Technically this means they are also available in Python, but (at least for now) I’m focused on Blueprints. Currently there are two main parts of GSS - functions for procedurally creating and editing ModelGrid objects, and utility functions for math and DynamicMesh manipulation (ie, the things I think should probably be part of Geometry Script, but aren’t).
For now this will be a brief reference of the available functions. I will build out this documentation as the libraries expand.
jump to…
[ GSIntBox3 ] [ Math Utilities ]
[ DynamicMesh Transforms ] [ Iterators ] [ Utilities ]
[ ModelGrid Edits ] [ Iterators ] [ Neighbours ] [ Meshing ] [ Utilities ]
ModelGrid Queries
These functions can be used to query information about a ModelGrid. They are read-only, and do not make any changes.
| GetGridCellDimensions | Get the dimensions of the unit cell in the ModelGrid |
| GetGridOccupiedCellRange | Get the integer bounding box of non-empty cell indices in the ModelGrid |
| GetGridCellBounds | Get the local-space bounding box of a grid cell |
| GetGridCellType | Get the in-grid/empty/non-empty and cell-type state for a grid cell index |
| GetGridCellShape | Get the cell-type, transform, and material info for a grid cell index |
| GetGridCellIndexAtPoint | Find the index of the grid cell that contains a local-space 3D point |
ModelGrid Edits
These functions can be used to make modifications to a ModelGrid.
| SetGridCellDimensions | Set the dimensions of the unit cell in a ModelGrid |
| RemoveAllCellsFromGrid | Clear out a ModelGrid, setting all cells to be Empty |
| EraseGridCell | Set a single cell to be Empty |
| EraseGridCellsInRange | Set all cells in a GSIntBox3 range (inclusive) to be Empty |
| FillGridCell | Set a single cell to be filled/solid with a specified Color |
| FillGridCellsInRange | Set all cells in a GSIntBox3 range (inclusive) to be filled/solid with a specified Color |
| SetGridCellShape | Set the cell type, (optional) cell transform, and Color for a single cell |
| TranslateGridCellsInRange | Shift the cells in a GSIntBox3 range (inclusive) by a given IntVector translation |
| CopyGridCellsInRange | Copy the cells in a GSIntBox3 range (inclusive) to a new location specified by an IntVector translation |
ModelGrid Iterators
Iterator functions can be used to process each (x,y,z) integer index inside a given region, or with a specific property. The iterations take advantage of the Delegate functionality of UFunctions/BPs - the nodes will have a Delegate input that can be connected to an auto-generated Event or BP Function that implements the per-element processing. This avoids having to figure out For loops ranges/etc.
| ForEachCellInRange | Call a delegate for each (x,y,z) cell index contained in the specified GSIntBox3 range (inclusive) |
ModelGrid Neighbour Queries
Neighbour Query functions can be used to find out information about the cells adjacent to a given cell. Currently two types of neighbour are supported. Face Neighbours are the 6 neighbours across each of the +/- XYZ axes. Plane Neighbours are the 8 neighbours surrounding a cell in a specified plane (XY, XZ, or YZ).
| GetGridCellFaceNbrs | Get the set of 6 face-neighbours for a given cell |
| GetFaceNbrOffset | Compute the integer offset to a face-neighbouring cell (eg +X = (1,0,0)) |
| GetFaceNbrCellIndex | Compute the cell index of a face-neighbour of a given cell |
| GetGridCellPlaneNbrs | Get the set of 8 neighbour cells in the X/Y/Z plane surrounding a central cell |
| GetPlaneNbrOffset | Compute the integer offset to a plane-neighbour cell (eg (+X,-Y) in PlaneYZ = (0,1,-1) |
| GetPlaneNbrCellIndex | Compute the cell index of a plane-neighbour of a given cell |
| CountPlaneNbrsOfType | Count the number of plane-neighbours of a cell that have (or don't have) a given cell-type |
ModelGrid Meshing
Utility functions for mesh processing based on ModelGrids
| GenerateMeshForModelGrid | Generate a UDynamicMesh for a ModelGrid, with various options for mesh processing and optimization, polygroup generation, and UV generation |
ModelGrid Utilities
Utility functions for ModelGrid scripting
| SetDeferUpdatesUntilNextTick | This function prevents a ModelGrid from sending change/update notifications until the next Tick. This will improve performance of scripted ModelGrid Editing. Note: GeneratedModelGridActor's OnRegenerateModelGrid function already manages updates, this function is not necessary there. It is meant for other ModelGrid editing scripts/functions, and may become unnecessary in the future. |
GSIntBox3
GSIntBox3 is a new ustruct type in GSS that represents an integer-coordinate bounding box, with Min and Max IntVector3 values. In many functions this box is used as a Range of integer X/Y/Z coordinates, rather than Bounds, meaning that the Max value is Inclusive. So a box with Min=(0,0,0) and Max=(0,0,1) will be considered to “contain” both (0,0,0) and (0,0,1).
Various utility functions for GSIntBox3 are available:
| ExpandBox | Grow a GSIntBox3 by an integer in each dimension |
| ForEachIndex3InRange | Iterate through each (x,y,z) tuple contained in GSIntBox3 (inclusive) and call a delegate for each |
DynamicMesh Utilities
These functions can be used to simplify Procedural mesh generators
| RequestOneFrameTemporaryMesh | This is an Experimental function that can be used to return a UDynamicMesh from a global pool, for use as a temporary mesh inside a single BP evaluation (eg like a OnRebuildGeneratedMesh function). The object will be automatically returned to the pool after the next Tick/Frame. Please read the function tooltip for more info! |
DynamicMesh Transforms
These functions provide shortcuts for transforming a UDynamicMesh between different coordinate spaces. These functions are all equivalent to using the GeometryScript function TransformMesh and the various transforms and transform-inverses.
| MapMeshFromActorSpaceToWorld | Transform a UDynamicMesh from local coordinates in an Actor into World coordinates |
| MapMeshToWorldFromActorSpace | Transform a UDynamicMesh from World coordinates into local coordinates of an Actor |
| MapMeshFromActorToActor | Transform a UDynamicMesh from the local space of one Actor to the local space of Another |
| MapMeshToOtherLocalSpace | Transform a UDynamicMesh one local space to another local space (via respective LocalToWorld transforms) |
DynamicMesh Iterators
These utility functions simplify processing elements of a mesh, like for example computing a custom mesh deformation by iterating through each vertex and moving it. The iterations take advantage of the Delegate functionality of UFunctions/BPs - the nodes will have an Delegate input that can be connected to an auto-generated Event or BP Function that implements the per-element processing. This avoids having to figure out For loops.
| ForEachMeshVertex | Iterate through the vertices of a UDynamicMesh and call a delegate for each ID/Position |
| ForEachMeshSelectionIndex | Iterate through the indices of a MeshSelection and call a delegate for each element |
Math Utilities
These utility functions can simplify the setup of common cases around geometric constructions
| CalcLineTraceStartEnd | Compute start and end points for a Line Trace given a 3D Point, Direction (can be un-normalized), and Start/End Distances |
(…)