Optimize Cybran build effects (FAForever#3355)

* Add build drone counts per unit

* Add (and name-refactor) total drone count for cybran engineers

* Ensure the OnCreate hierarchy is called properly to initialise maximum drone count

* Optimize cybran build drones

* Optimize cybran build effects

* Optimize cybran build drones

* Refactor cybran classes for better build bot support

* Add Cybran build bots made by Madmax

* Fix orientation of cybran build bots

* Add cybran build beams so that we can tweak them

* Tweak aesthetics of cybran build bots

* Add efficient version of effect utilities

This makes it easier to keep track of files and functions that
have been optmized.

* Revert changes to effect utilities

* Appeneded optimized functions to old effect utilities file

* Tweak visuals build bots and add deprecation warnings

* Rename functions for sake of clarity

* Inline an expensive function for performance

The function (RandomOffset) of unit.lua retrieved blueprints twice
and too many random numbers. Inlining and caching it improves
performance by another significant amount (0.5ms - 1ms less!)

* Tweak aesthetics of cybran build animation

* Refactor for less indenting and minor loop fix

* Prevent AI from using the cybran build drones

* Add comment for clarity

effects/emitters/build_beam_01_emit.bp

@@ -0,0 +1,10 @@
+BeamBlueprint {
+    Lifetime = 2,
+    TextureName = '/textures/particles/beam_disruptor.dds',
+    Thickness = 0.025,
+    StartColor = {x=0.2,y=0.2,z=1,w=0.3}, # R,G,B,A
+    EndColor = {x=0.2,y=0.2,z=1,w=0.3}, # R,G,B,A
+    Length = 8,
+    UShift = 0.0,
+    VShift = -0.5,
+}

effects/emitters/build_beam_02_emit.bp

@@ -0,0 +1,10 @@
+BeamBlueprint {
+    Lifetime = 2,
+    TextureName = '/textures/particles/beam_white_02.dds',
+    Thickness = 0.018,
+    StartColor = {x=0.6,y=0,z=0.1,w=0.2}, # R,G,B,Glow
+    EndColor = {x=1,y=0.2,z=0,w=0.2}, # R,G,B,Glow
+    Length = 8,
+    UShift = 0.0,
+    VShift = 0.0,
+}

effects/emitters/build_beam_03_emit.bp

@@ -0,0 +1,10 @@
+BeamBlueprint {
+    Lifetime = 2,
+    TextureName = '/textures/particles/beam_white_07.dds',
+    Thickness = 0.025,
+    StartColor = {x=1,y=0.2,z=0,w=0.2}, # R,G,B,Glow
+    EndColor = {x=0,y=0,z=0,w=0}, # R,G,B,Glow
+    Length = 8,
+    UShift = 0.0,
+    VShift = 0.0,
+}

effects/emitters/build_bot_beam_01_emit.bp

@@ -0,0 +1,10 @@
+BeamBlueprint {
+    Lifetime = 2,
+    TextureName = '/textures/particles/beam_white_02.dds',
+    Thickness = 0.020,
+    StartColor = {x=0.6,y=0,z=0.1,w=0.0}, # R,G,B,Glow
+    EndColor = {x=1,y=0.2,z=0,w=0.0}, # R,G,B,Glow
+    Length = 8,
+    UShift = 0.0,
+    VShift = -0.05,
+}

effects/emitters/build_bot_beam_02_emit.bp

@@ -0,0 +1,10 @@
+BeamBlueprint {
+    Lifetime = 2,
+    TextureName = '/textures/particles/beam_white_02.dds',
+    Thickness = 0.015,
+    StartColor = {x=0.6,y=0,z=0.1,w=0.0}, # R,G,B,Glow
+    EndColor = {x=1,y=0.2,z=0,w=0.0}, # R,G,B,Glow
+    Length = 8,
+    UShift = 0.0,
+    VShift = 0.0,
+}

effects/emitters/build_bot_beam_03_emit.bp

@@ -0,0 +1,11 @@
+BeamBlueprint {
+    Lifetime = 2,
+    TextureName = '/textures/particles/beam_white_02.dds',
+    Thickness = 0.030,
+    StartColor = {x=1,y=0.2,z=0,w=0.0}, # R,G,B,Glow
+    EndColor = {x=0,y=0,z=0,w=0}, # R,G,B,Glow
+    RepeatRate = 0.1,
+    Length = 2,
+    UShift = 0.0,
+    VShift = -0.2,
+}

lua/EffectUtilities.lua

@@ -10,6 +10,8 @@ local Entity = import('/lua/sim/Entity.lua').Entity
 local EffectTemplate = import('/lua/EffectTemplates.lua')
 local RandomFloat = import('/lua/utilities.lua').GetRandomFloat
 
+local DeprecatedWarnings = { }
+
 function CreateEffects(obj, army, EffectTable)
     local emitters = {}
     for _, v in EffectTable do
@@ -377,6 +379,14 @@ function CreateAeonBuildBaseThread(unitBeingBuilt, builder, EffectsBag)
 end
 
 function CreateCybranBuildBeams(builder, unitBeingBuilt, BuildEffectBones, BuildEffectsBag)
+
+    -- deprecation warning for more effcient alternative
+    if not DeprecatedWarnings.CreateCybranBuildBeams then 
+        DeprecatedWarnings.CreateCybranBuildBeams = true 
+        WARN("CreateCybranBuildBeams is deprecated: use CreateCybranBuildBeamsOpti instead.")
+        WARN("Source: " .. repr(debug.getinfo(2)))
+    end
+
     WaitSeconds(0.2)
     local BeamBuildEmtBp = '/effects/emitters/build_beam_02_emit.bp'
     local BeamEndEntities = {}
@@ -407,6 +417,14 @@ function CreateCybranBuildBeams(builder, unitBeingBuilt, BuildEffectBones, Build
 end
 
 function SpawnBuildBots(builder, unitBeingBuilt, BuildEffectsBag)
+
+    -- deprecation warning for more effcient alternative
+    if not DeprecatedWarnings.SpawnBuildBots then 
+        DeprecatedWarnings.SpawnBuildBots = true 
+        WARN("SpawnBuildBots is deprecated: use SpawnBuildBotsOpti instead.")
+        WARN("Source: " .. repr(debug.getinfo(2)))
+    end
+
     -- Buildbots are scaled: ~ 1 pr 15 units of BP
     -- clamped to a max of 10 to avoid insane FPS drop
     -- with mods that modify BP
@@ -464,6 +482,14 @@ function SpawnBuildBots(builder, unitBeingBuilt, BuildEffectsBag)
 end
 
 function CreateCybranEngineerBuildEffects(builder, BuildBones, BuildBots, BuildEffectsBag)
+
+    -- deprecation warning for more effcient alternative
+    if not DeprecatedWarnings.CreateCybranEngineerBuildEffects then 
+        DeprecatedWarnings.CreateCybranEngineerBuildEffects = true 
+        WARN("CreateCybranEngineerBuildEffects is deprecated: use CreateCybranEngineerBuildEffectsOpti instead.")
+        WARN("Source: " .. repr(debug.getinfo(2)))
+    end
+
     -- Create build constant build effect for each build effect bone defined
     if BuildBones and BuildBots then
         for _, vBone in BuildBones do
@@ -489,15 +515,16 @@ function CreateCybranEngineerBuildEffects(builder, BuildBones, BuildBots, BuildE
     end
 end
 
+local BuildEffects = {
+    '/effects/emitters/sparks_03_emit.bp',
+    '/effects/emitters/flashes_01_emit.bp',
+}
+local UnitBuildEffects = {
+    '/effects/emitters/build_cybran_spark_flash_04_emit.bp',
+    '/effects/emitters/build_sparks_blue_02_emit.bp',
+}
+
 function CreateCybranFactoryBuildEffects(builder, unitBeingBuilt, BuildBones, BuildEffectsBag)
-    local BuildEffects = {
-        '/effects/emitters/sparks_03_emit.bp',
-        '/effects/emitters/flashes_01_emit.bp',
-    }
-    local UnitBuildEffects = {
-        '/effects/emitters/build_cybran_spark_flash_04_emit.bp',
-        '/effects/emitters/build_sparks_blue_02_emit.bp',
-    }
 
     CreateCybranBuildBeams(builder, unitBeingBuilt, BuildBones.BuildEffectBones, BuildEffectsBag)
 
@@ -1881,3 +1908,34 @@ function DestroyRemainingTeleportChargingEffects(unit, EffectsBag)
         unit.TeleportCybranSphere:Destroy()
     end
 end
+
+--- Optimized functions --
+
+local EffectUtilitiesOpti = import('/lua/EffectUtilitiesOpti.lua')
+
+--- Creates tracker beams between the builder and its build bots. The
+-- bots keep the tracker in their trashbag.
+-- @param builder The builder / tracking entity of the build bots.
+-- @param buildBones The bones to use as the origin of the beams.
+-- @param buildBots The build bots that we're tracking.
+-- @param total The number of build bots / bones. The 1st bone will track the 1st bot, etc.
+CreateCybranEngineerBuildEffectsOpti = EffectUtilitiesOpti.CreateCybranEngineerBuildEffects
+-- original: CreateCybranEngineerBuildEffects
+
+--- Creates the beams and welding points of the builder and its bots. The
+-- bots share the welding point which each other, as does the builder with
+-- itself.
+-- @param builder A builder with builder.BuildEffectBones set. 
+-- @param bots The bots of the builder.
+-- @param unitBeingBuilt The unit that we're building.
+-- @param buildEffectsBag The bag that we use to store / trash all effects.
+-- @param stationary Whether or not the builder is a building.
+CreateCybranBuildBeamsOpti = EffectUtilitiesOpti.CreateCybranBuildBeams
+-- original: CreateCybranBuildBeams
+
+--- Creates the build drones for the (cybran) builder in question. Expects  
+-- the builder.BuildBotTotal value to be set.
+-- @param builder A cybran builder such as an engineer, hive or commander.
+-- @param botBlueprint The blueprint to use for the bot.
+SpawnBuildBotsOpti = EffectUtilitiesOpti.SpawnBuildBots
+-- original: SpawnBuildBots