From 82657daa97bc708fff58ac6298143fa3f0ed6e50 Mon Sep 17 00:00:00 2001
From: Isaac Hudson <isaac.hudson@terraformation.com>
Date: Thu, 10 Sep 2026 16:53:16 -0700
Subject: [PATCH] Fix cleanup for scripts with explicit scriptName

---
 .changeset/tidy-script-cleanup.md           |  5 +++
 packages/lib/src/components/Script.test.tsx | 44 +++++++++++++++++++++
 packages/lib/src/hooks/use-script.tsx       |  8 +++-
 3 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/tidy-script-cleanup.md

diff --git a/.changeset/tidy-script-cleanup.md b/.changeset/tidy-script-cleanup.md
new file mode 100644
index 0000000..83d3914
--- /dev/null
+++ b/.changeset/tidy-script-cleanup.md
@@ -0,0 +1,5 @@
+---
+"@playcanvas/react": patch
+---
+
+Respect explicit static scriptName values when cleaning up Script components so unmounting removes the registered script and remounting avoids duplicate-script warnings. Preserve class-name fallback cleanup for scripts without an explicit name.
diff --git a/packages/lib/src/components/Script.test.tsx b/packages/lib/src/components/Script.test.tsx
index 50e1559..675b6a8 100644
--- a/packages/lib/src/components/Script.test.tsx
+++ b/packages/lib/src/components/Script.test.tsx
@@ -170,6 +170,50 @@ describe('Script Component', () => {
     });
 
     describe('Cleanup', () => {
+        class _OrbitCamera extends PcScript {
+            static scriptName = 'orbitCamera';
+        }
+
+        class FallbackScript extends PcScript {}
+
+        it.each([
+            ['explicit scriptName', _OrbitCamera, 'orbitCamera'],
+            ['class-name fallback', FallbackScript, 'fallbackScript']
+        ] as const)('should clean up and remount using %s', async (_label, script, scriptName) => {
+            const scriptRef = React.createRef<PcScript>();
+            const Container = ({ mounted }: { mounted: boolean }) => (
+                <Application deviceTypes={['null']}>
+                    <Entity>{mounted && <Script script={script} ref={scriptRef} />}</Entity>
+                </Application>
+            );
+
+            const { rerender } = render(<Container mounted />);
+            await waitFor(() => expect(scriptRef.current).toBeInstanceOf(script));
+            const firstInstance = scriptRef.current!;
+            const entity = firstInstance.entity;
+            expect(entity.script![scriptName]).toBe(firstInstance);
+
+            rerender(<Container mounted={false} />);
+            expect(scriptRef.current).toBeNull();
+            expect(entity.script).toBeDefined();
+            expect(entity.script![scriptName]).toBeUndefined();
+
+            const warnSpy = vi.spyOn(console, 'warn');
+            try {
+                rerender(<Container mounted />);
+                await waitFor(() => expect(scriptRef.current).toBeInstanceOf(script));
+                expect(scriptRef.current).not.toBe(firstInstance);
+                expect(scriptRef.current!.entity).toBe(entity);
+                expect(entity.script![scriptName]).toBe(scriptRef.current);
+                expect(warnSpy).not.toHaveBeenCalled();
+            } finally {
+                warnSpy.mockRestore();
+            }
+
+            rerender(<Container mounted={false} />);
+            expect(entity.script![scriptName]).toBeUndefined();
+        });
+
         it('should clean up script instance on unmount', async () => {
             const destroySpy = vi.fn();
 
diff --git a/packages/lib/src/hooks/use-script.tsx b/packages/lib/src/hooks/use-script.tsx
index 8603821..4c73163 100644
--- a/packages/lib/src/hooks/use-script.tsx
+++ b/packages/lib/src/hooks/use-script.tsx
@@ -17,10 +17,14 @@ import { useParent } from './use-parent.tsx';
  *   myProperty: 'value',
  * });
  */
-export const useScript = (scriptConstructor: SubclassOf<Script>, props: Props, ref: ForwardedRef<Script>): void => {
+export const useScript = (
+    scriptConstructor: SubclassOf<Script> & { scriptName?: string },
+    props: Props,
+    ref: ForwardedRef<Script>
+): void => {
     const parent: Entity = useParent();
     const app: Application = useApp();
-    const scriptName: string = toLowerCamelCase(scriptConstructor.name);
+    const scriptName: string = scriptConstructor.scriptName || toLowerCamelCase(scriptConstructor.name);
     const scriptRef = useRef<Script | null>(null);
     const scriptComponentRef = useRef<ScriptComponent | null>(null);