From fe96f3e500842982ce4d056c86e3d04b414da4f4 Mon Sep 17 00:00:00 2001
From: bagel786 <safbaig5@gmail.com>
Date: Sat, 29 Aug 2026 12:05:29 -0500
Subject: [PATCH] Fix global plugin mappings in HEADLESS mode

---
 src/plugins/PluginManager.js        |  2 +-
 tests/plugins/PluginManager.test.js | 36 +++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/src/plugins/PluginManager.js b/src/plugins/PluginManager.js
index b5fd72bb5d..8f0f779f37 100644
--- a/src/plugins/PluginManager.js
+++ b/src/plugins/PluginManager.js
@@ -452,7 +452,7 @@ var PluginManager = new Class({
             start = true;
         }
 
-        if (!this.game.isBooted)
+        if (!this.game.isBooted && this.game.config.renderType !== CONST.HEADLESS)
         {
             this._pendingGlobal.push({ key: key, plugin: plugin, start: start, mapping: mapping, data: data });
         }
diff --git a/tests/plugins/PluginManager.test.js b/tests/plugins/PluginManager.test.js
index 936f80c5b8..9b10a04948 100644
--- a/tests/plugins/PluginManager.test.js
+++ b/tests/plugins/PluginManager.test.js
@@ -3,6 +3,7 @@ var PluginCache = require('../../src/plugins/PluginCache');
 var GameObjectFactory = require('../../src/gameobjects/GameObjectFactory');
 var GameObjectCreator = require('../../src/gameobjects/GameObjectCreator');
 var FileTypesManager = require('../../src/loader/FileTypesManager');
+var CONST = require('../../src/const');
 
 describe('PluginManager', function ()
 {
@@ -98,6 +99,41 @@ describe('PluginManager', function ()
 
             expect(bootSpy).toHaveBeenCalled();
         });
+
+        it('should install mapped global plugins immediately in HEADLESS mode', function ()
+        {
+            var MockPlugin = createMockPluginClass();
+            var cachedPlugin;
+            var headlessGame = createMockGame();
+
+            headlessGame.config.renderType = CONST.HEADLESS;
+            headlessGame.config.installGlobalPlugins = [
+                { key: 'headlessPlugin', plugin: MockPlugin, mapping: 'headlessPlugin' }
+            ];
+
+            vi.spyOn(PluginCache, 'hasCustom').mockImplementation(function ()
+            {
+                return cachedPlugin !== undefined;
+            });
+            vi.spyOn(PluginCache, 'registerCustom').mockImplementation(function (key, plugin, mapping, data)
+            {
+                cachedPlugin = { plugin: plugin, mapping: mapping, data: data };
+            });
+            vi.spyOn(PluginCache, 'getCustom').mockImplementation(function ()
+            {
+                return cachedPlugin;
+            });
+
+            var headlessManager = new PluginManager(headlessGame);
+            var mockSys = {
+                scene: {},
+                settings: { map: {}, isBooted: false }
+            };
+
+            headlessManager.addToScene(mockSys, [], []);
+
+            expect(mockSys.scene.headlessPlugin).toBeInstanceOf(MockPlugin);
+        });
     });
 
     describe('getIndex', function ()