Swarm Agent Troubleshooting
About This Guide . This guide is intended to go over some best practices when using Lightmass to build static lighting in Unreal Engine 4 and to address some of the more common issues that can aris...
About This Guide
.
This guide is intended to go over some best practices when using Lightmass to build static lighting in Unreal Engine 4 and to address some of the more common issues that can arise with Swarm Agent while doing so. This guide is in no way meant to be comprehensive and is a living document that can be updated along with engine releases.
Swarm Agent is a program that is used to process Unreal's Lightmass calculations for a single system or it can distribute its workload across a network to other computers through Swarm Coordinator. Largely, Swarm Agent will go unnoticed to most who are not using network distribution for light builds since it will startup, perform its tasks, and shut down once the light build has finished.
Swarm Agent Documentation and Other Links
- Lightmass Global Illumination
- Swarm Agent Documentation
- UDK-Networking Swarm Agent
- Brian Goodsell's Tutorial: Setting Up Swarm for Multiple Machines
_________________________________________________________________________________________________
Recommendations and Tips
_________________________________________________________________________________________________
General Tips for using Lightmass in Unreal Engine 4
Reducing Build Times
- Lightmass Importance Volume:
When using Lightmass Importance Volumes itÔÇÖs important to know and understand that you can use as many of these as you like. You are not limited to a single instance in your level. The idea behind these volumes is to focus photons in a single area where higher quality lighting is needed where the player is. Anything outside of these volumes will only get a single bounce of lighting and will not look as high quality as the lighting generated within the volume.By using these volumes you can reduce the amount of calculation that is needed for the scene and this will help increase light builds. ItÔÇÖs important to also note that these volumes are not meant to be scaled to extreme sizes. This defeats their use and purpose.
For more information have a look at the documentation here: Lightmass Basics
- Lightmap Resolutions:
These resolutions play a big part in how long it can take for Swarm Agent to build a scene. The higher the lightmap resolutions for your meshes the more time it can take to calculate and generate these textures. It is best to use the lowest possible resolution that still gives the results you are happy with.
It is not recommended to set all static meshes to higher resolutions. If you are finding that you have to set a mesh to a significantly higher resolution you may want to look at breaking the mesh into smaller pieces so that the Lightmap UV can be more effectively used, or you may simply need reorganize the Lightmap UV to get better results by using the 0,1 UV space better.
- Foliage Tool: Lightmap Resolutions:
For instanced static meshes placed with the Foliage Tool these assets will use the default set Lightmap Resolution of the static mesh. This will likely generate a warning when you build lighting. ItÔÇÖs best to go into the Foliage ToolÔÇÖs Instance Settings and enable Lightmap Resolution with a lower value of 4 or 8. With instanced static meshes this should be sufficient depending on the number of static mesh instances that have been painted into the scene. These will be clustered together into a single lightmap based on cluster size.
- Number of Assets and Lights:
The number of assets that cast shadows and the number of shadow casting lights in the scene that are Stationary or Static will also add to the number of calculations that need to be done when using Lightmass. These calculations can directly affect how much Swarm Agent needs to process and essentially how long the light build will take.
- System Specs:
Swarm Agent is a very CPU intensive process that requires a lot of calculations. Depending on your system specs this can speed up or slow down the process or even cause Lightmass to crash. A fast CPU can help improve calculation speed. The amount of RAM needed is dependent upon the size of the scene, number of lights, and assets being calculated. Lightmass will Crash if it runs out of memory. This is often reported as a bug, but it is simply a limitation of your system setup. See the other tips above to help reduce the chance of this happening or increase your systems RAM. _________________________________________________________________________________________________
Building Large Worlds
If your project is going to use a larger world or even a fully open world with thousands of assets, instanced foliage, etc it is generally not recommended to use Lightmass to build lighting for these types of worlds.
One may argue that it has been preached that ÔÇ£Static lighting is better for performance and looks better.ÔÇØ Yes, this is a true statement, but within certain restrictions. This is not to say that static lighting cannot be used for larger worlds, it is just not an ideal use due to the memory it would take to store all the generated lightmap textures and the amount of memory it would take to build the level in the first place.
Larger worlds and open worlds will generally use dynamic lighting. This may seem counter-intuitive when thinking about how static lighting has zero overhead at run-time compared to dynamic lighting. This again is true, but instead of calculating shadows you will have to worry about the lightmap textures having to load for all those meshes. ItÔÇÖs better to focus on using dynamic lighting and then optimizing your games by gauging the performance by profiling the CPU and GPU for any bottlenecks that may come up.
For more information about profiling have a look at the following documentation and YouTube Support stream:
- Documentation: Profiler
- Documentation: Performance and Profiling
- Documentation: GPU Profiling
- Support Stream Video: Rendering Best Practices
_________________________________________________________________________________________________
Frequently Asked Questions
_________________________________________________________________________________________________
"Lightmass Crashed" common error messages
"Ran out of Memory"
Just as the explanation suggests, this crash is because there was not enough memory to build lighting for the scene as is.
Steps to try:
- Add a Lightmass Importance Volume(s) around your playable areas. (See the Tips section above for more information)
- Lower the number of meshes in the scene
- Lower the Lightmap Resolution for meshes that do not need higher quality shadows.
- If using the Foliage Tool, use lightmap resolutions starting with 4 or 8, since meshes will be clustered together into a texture atlas.
- Clean and Validate cache
- Increase the amount of Virtual Memory that is available. Think of this as an overflow when RAM is running low. Do not rely on this over adding additional RAM though.
- Add additional RAM to your system.
===="Assertion Failed: (Index>=0)&(Index\