Fix bug where dummy weapon bps are assigned to non-dummy weapons

changelog/snippets/fix.6882.md

@@ -0,0 +1 @@
+- (#6882) Fix the `ModWeapons` blueprint field adding weapons after dummy weapons, causing the unit weapon to incorrectly get the dummy weapon's blueprint for the new weapon.

changelog/snippets/other.6882.md

@@ -0,0 +1 @@
+- (#6882) Give a warning when non-dummy weapons are assigned dummy weapon blueprints because they are positioned after a dummy weapon blueprint in the `Weapon` table of the unit blueprint.

engine/Core/Blueprints/UnitBlueprint.lua

@@ -100,7 +100,8 @@
 ---@field Physics UnitBlueprintPhysics
 ---@field Transport? UnitBlueprintTransport
 ---@field Veteran? UnitBlueprintVeterancy
----@field Weapon? WeaponBlueprint[]
+--- The weapon in the first index controls unit AI. Weapons with `DummyWeapon = true` must be at the end of the table.
+---@field Weapon? WeaponBlueprint[] 
 ---@field ModWeapon? WeaponBlueprint[] # Used during blueprint loading to mod `Weapon` table
 ---@field Wreckage? UnitBlueprintWreckage
 ---

lua/sim/Unit.lua

@@ -161,7 +161,7 @@ local cUnitGetBuildRate = cUnit.GetBuildRate
 ---@field ignoreDetectionFrom table<Army, true>? # Armies being given free vision to reveal beams hitting targets
 ---@field reallyDetectedBy table<Army, true>?    # Armies that detected the unit without free vision and don't need intel flushed when beam weapons stop hitting
 ---@field Weapons table<string, Weapon> # string is weapon Label
----@field WeaponInstances Weapon[]
+---@field WeaponInstances table<integer|string, Weapon> # string matches weapon label
 ---@field WeaponCount number
 ---@field CaptureProgress? number # Keeps track of capture progress to prevent sharing units being captured and to sync capture work progress bars
 ---@field oldowner? Army # After a unit is transferred, keeps track of the original Army to kill shared units when needed.

lua/system/Blueprints.lua

@@ -1001,24 +1001,37 @@ function MergeWeaponByLabel(baseBp, label, insertPos, newBp)
         return
     end
 
+    local firstDummyIndex
     for i, w in weaponTable do
         if w.Label == label then
             weaponTable[i] = BlueprintMerged(w, newBp)
             return
         end
+        if w.DummyWeapon then
+            firstDummyIndex = i
+        end
     end
 
+    local finalInsertIndex = firstDummyIndex or TableGetn(weaponTable) + 1
     if insertPos then
-        local size = table.getn(weaponTable)
-        if insertPos > size + 1 then
-            WARN("Tried to insert a weapon bp in a position beyond the end of the Weapon array! Inserting at the end instead.")
-            TableInsert(weaponTable, newBp)
+        if firstDummyIndex and insertPos > firstDummyIndex then
+            WARN(string.format("Tried to insert weapon with label `%s` for unit %s at a position %d beyond the first dummy weapon of the Weapon array! Inserting before the dummy weapon at: %d"
+                , tostring(newBp.Label)
+                , baseBp.BlueprintId
+                , insertPos
+                , firstDummyIndex
+            ))
+        elseif insertPos > finalInsertIndex then
+            WARN(string.format("Tried to insert weapon with label `%s` for unit %s at a position %d beyond the end of the Weapon array! Inserting at the end instead."
+                , tostring(newBp.Label)
+                , baseBp.BlueprintId
+                , insertPos
+            ))
         else
-            TableInsert(weaponTable, insertPos, newBp)
+            finalInsertIndex = insertPos
         end
-    else
-        TableInsert(weaponTable, newBp)
     end
+    TableInsert(weaponTable, finalInsertIndex, newBp)
 end
 
 --#endregion

lua/system/blueprints-weapons.lua

@@ -152,7 +152,9 @@ function ProcessWeapons(allBlueprints, units)
     for _, unit in units do
         if not unitsToSkip[StringLower(unit.Blueprint.BlueprintId or "")] then
             if unit.Weapon then
-                for _, weapon in unit.Weapon do
+                local giveWarning = false
+                local seenDummyWeapon
+                for i, weapon in unit.Weapon do
                     if not weapon.DummyWeapon then
 
                         local projectile
@@ -165,8 +167,22 @@ function ProcessWeapons(allBlueprints, units)
                         end
 
                         ProcessWeapon(unit, weapon, projectile)
+
+                        -- Warn about a bug where non-dummy weapons are assigned a dummy weapon's blueprint by
+                        -- the engine because it expects all non-dummy weapons to be at the start of the table.
+                        if seenDummyWeapon then
+                            giveWarning = true
+                        end
+                    else
+                        if not seenDummyWeapon then
+                            seenDummyWeapon = true
+                        end
                     end
                 end
+                if giveWarning then
+                    WARN(string.format("Weapon Blueprint Processing - units %s has weapons that come after a weapon with `DummyWeapon = true` in its blueprint. The units' weapon scripts will not function correctly, please move all dummy weapons to the end of the `Weapon` table in the blueprint."
+                    , unit.BlueprintId))
+                end
             end
         end
     end