Christian Sparks

I spent a week working on a framework that tells you how illuminated an actor is by lights in your level. It’s all blueprint-based, using components & overlaps & tracing. In this post I’ll break down how the system works, how to set it up in your project, and detail some limitations. In a more thorough post, I’ll break down all the code so that if you’re not using UE4 4.20 or newer, or if you’re just curious how this system was made, you can go through the creation process yourself.

Overview

This post assumes the end user is somewhat familiar with the Unreal Engine editor, blueprints scripting & actor editing. I’ll try to break things down as simply as possible. First, here are some videos showcasing how the system works, and what it tries to accomplish:

Here we see the base system, which traces from the points to the lights, and returns an illumination value showcased in the arrow color above the player’s head.

In this video, we see some more complex examples, with light sources being tracked on moving objects, and probe points having sample radii for more broad coverage of areas, as well as individual debugging intensity values.

Finally in this video, we see the probes sampling the color data multiplied by the intensity divided by scaled distance from the light sources, with color mixing for multiple different color overlaps, giving light intensity and color value at each probe intersection point.

The basic workflow for this system is:

-User copies IlluminationDetection folder from the Github Source Project to their project’s content folder -Actor gets assigned probe components -User places light boundary volumes for point & spot lights in level -Player assigns light illumination components to directional/sky lights in level -At runtime, probes trace for appropriate light sources and return light (and optionally color) illumination information. If their traces return a hit, it means that the probe does not have a clear line of sight to the light source, which means it’s in the shadows. -End user can use that data however they’d like, be it for stealth or puzzle mechanics or something else. 

This system will only trace for lights when it’s appropriate, thanks to the overlap logic it espouses; directional lights will always get a probe to trace, as they’re a global light actor. Sky lights also get checked every time the Detect Light Vis function runs, but it has the advantage of not needing trace logic, as it’s both global and ambient.

Point lights will only prompt a probe to trace if that probe is overlapping an Illumination Volume that’s assigned to the given point light. (I’ll go over how to assign volumes further down.)

Spot lights will also only prompt a probe to trace if that probe is overlapping an illumination volume that’s assigned to it, with an additional vector math step to determine if the probe is also within the spot light’s cone.

In order to assign volumes to lights, you can either place Illumination Sphere Volumes or Illumination Cube Volumes (found in IlluminationDetection>Blueprints>IlluminationVolumes) in your level and assign them to the appropriate spot/point lights (which will adjust location, bounds scale accordingly) OR you can use a handy blueprint that I included that does that work for you.

If you want to make these point/spot light volumes automatically, drag a BP_LightOverlapManager actor into your level, and then click the Generate Overlaps button. This will run through all the point lights and spot lights in your level and place/orient/adjust sphere overlap volumes for you. You can also remove the generated overlaps, and show/hide their bounds using the other Buttons in the Actor Details panel.

The Illumination Probe component can be attached to an object or skeletal sockets or really whatever you’d like, and has a handful of variables, including debugging options, and bools to control whether to check for directional lights, sky lights, and color values. The Max Illumination value is the individual probe’s overall Illumination value, which you can set to any arbitrary scale you’d like. In the example project, the 8 probes attached to the character all attribute to the player’s overall illumination equally. But going through and manually adding the probes to a character or object allows you to set different values per probe, as a probe on someone’s face might deserve a higher illumination value, as an AI would conceivably be able to identify a person’s face more than, say, their foot.

In the past couple UE4 engine releases, there’s been a bit of talk about adding additional mesh editing functionality in-editor, which we first saw manifested with additional static mesh editing capabilities, with functionality eventually (as of 4.20) extending to landscape editing via blueprint scripting.

I was curious if this had made the cut as of UE4 4.20 because I hadn’t recalled reading it in any changelogs, but sure enough, it does indeed work. I was tipped off by a post that Ryan Brucks (@shaderbits on Twitter) had made. Ryan’s showcase is much prettier than mine is, but I was still pleasantly surprised with how easy it was to iterate on terrain generation just by sampling perlin and voronoi noise.

The whole functionality for this hinges on the ability to update the landscape heightmap via blueprints, with the additional support for render targets. Since we’re already able to write materials to render targets, it’s a pretty easy setup to be able to take render target info and apply it to the landscape, with these basic blueprint calls:

With this basic functionality, the landscape generation comes down to material setups. Again with Ryan Brucks to the rescue, there’s a great post on the UE4 Blog called Getting the Most Out of Noise in UE4, that talks about how we can leverage different noise samples in materials to get some interesting results. I utilized what was shared there to mix different noise samples with configurable levels, strength and contrast, to get some decently flexible results, especially when exposing those parameters to a single blueprint for quick iteration.

Disclaimer: This tutorial assumes that the reader has a basic understanding of 3d modeling concepts and scripting with blueprints in UE4. Much of the information, i.e. the base for the construction script for this system, is derived from this video tutorial. If you just want to skip ahead to the building of this system without analysis or definition, check out the video, and thank you to Playful Synapse for the great tutorial.

Intro

Splines are a fantastic resource for taking linear resources and dynamically shaping them to fit your likely non-linear worldspace, without having to a) use up valuable artist time measuring and scaling static curved objects to fit an exact setup, and b) overload your asset library with multiple iterations of similar objects to fit those setups.

A spline mesh, what this post is covering, is a conjunction of the computational spline with a static mesh, allowing a great deal of variance and transformation from the mesh's initial shape and bounds. Popular uses of the spline mesh include construction of rivers, roads, ropes and cables, and even fences. In this post, I'll be using the example of creating caves using spline meshes. (Note: This tutorial was created using Unreal Engine v. 4.11.1)

Understanding Splines

So how does a spline mesh work in UE4? Well, first we need to take a look at what exactly a spline component is in the context of UE4. It is essentially a linear line with two ends, called points. More points can be added to a spline between its beginning and end points, which are what give a spline its shape. The more points you add, the more shape variation you can have. Taking this concept, we add a spline mesh component, which applies a static mesh or meshes to the spline (depending on how many points there are) and lines the mesh up along the line direction between the points. Starting out adding a spline mesh, you'll have 2 points, constituting the beginning and end of the spline, and of the spline mesh. But when you add another point in between the beginning and end points, the blueprint actually adds a second mesh, using the 3 points as beginning and end coordinates for the beginning and end of your mesh, using a forward vector that you identify in the blueprint. (I'll get to forward vectors in a second.) Here is a diagram to illustrate the concepts of how splines, spline points, and spline meshes work together:

So say your tunnel piece moves, "foward," in the sense of walking through the tunnel, on the X axis; the forward vector for your spline mesh component will be in the X direction. If this were the case but you instead used the Y axis as your forward vector, the mesh would be scaled and duplicated side by side, instead of extending the length of the tunnel itself.

This may be a bit confusing, but it starts to make sense as you build the script and play with the blueprint in UE4.

Getting Started

The first thing we're going to need is a cave asset that will be used as a static mesh. Since this tutorial is more for the scripting and less for the art, I'm not going to spend a huge amount of time on the example mesh. Here's a link to download the fbx.

When you import the tunnel mesh, be sure to uncheck Auto-Generate Collisions, as I have generated the fbx file with collisions included. Once you have the mesh imported, right click inside the content browser, and under Create Basic Asset, click Blueprint Class. In the Pick Parent Class window, select Actor. Name your blueprint actor something like, "BP_Cave," or something similar. (Note: It's a good idea to get into the habit of using naming conventions to better organize your asset library.)

Double click on your new blueprint actor, and you'll see the blueprint editor pop up. The first thing you'll want to do is click add component, and search for Spline Component. Navigate to the construction script, and we'll get started on building the script that will control our spline actor.

The first section of the script, highlighted here, sets up the repeat-behavior of adding in spline points.

The next section of the script, highlighted here, sets up the creation of the mesh or meshes along the spline points, and the attachment of the ends of multiple meshes along the spline when it has more than 2 points. Before we continue to the final part of the script, we need to set what mesh is being spawned, and the mesh's forward vector. In this case, we'll be using the X axis for the forward vector. It's also important to set the mesh mobility to moveable, as its shaping will be changing to some extent during placement/deformation. (I'll discuss what kind of deformation occurs later.)

And here is the last portion of the script:

This sets the start and end points of the mesh or meshes. In order to access this node, you'll need to drag off of the return value on the Add Spline Mesh Component node.

And that's it for the construction script! You can now drag your blueprint into the level editor and play around with it. When you first drop it in, the first two points may be close together, and it may seem like there are a lot more than just the two first points. This is because each point also has a tangent bar that can be used to control the intensity of the curve between each spline point. (If you look at the first diagram, you'll notice that the mesh appears straight, but the spline lines are curved, this is due to spline points approximating their shape between points on an auto-curve rather than linearly.) To move a spline point, select the point, not the tangent bar, and move it around, and you'll start to see mesh deformation occurring. Moving the end point away from the beginning point will pull and stretch the mesh out to follow the spline point location. You can right click on the spline line between the beginning and end points and add a point along your spline, which will then split the mesh into two instances of that mesh, using that spline point's location to set the end location along the first mesh components forward vector, and the beginning location along the second mesh components forward vector. Along with just scaling/skewing the mesh, it may also deform it along the spline path, but how straight or curvey this deformation is depends on how many vertices your mesh has. If you were to use a cube mesh with no extra vertices other than the ones necessary to form the cube shape, the deformation would be very rigid and sharp, but if you had a subdivided cube mesh with multiple extra vertices, more curvey, smooth deformation would occur, as the extra vertices would serve as more, "curve points," so to speak:

This version of the mesh was not subdivided, so only the vertices necessary to form the shame were present, resulting in sharp corners between meshes.

This version of the mesh (the one in the download link above) was subdivided, so there's a bit more curvature-deformation occurring on each mesh, serving to approximate the upcoming direction change (if applicable) on the next mesh along the spline.

And there you have it! You've successfully created a spline mesh blueprint! Pat yourself on the back!

Caveats