{"record":{"id":"c2fdb3aca33a9f37","repo":"phaserjs/phaser","slug":"supplied-items-must-be-elements-of-the-same-array-c2fdb3","errorCode":null,"errorMessage":"Supplied items must be elements of the same array","messagePattern":"Supplied items must be elements of the same array","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/utils/array/Swap.js","lineNumber":33,"sourceCode":" * @param {array} array - The input array.\n * @param {*} item1 - The first element to swap.\n * @param {*} item2 - The second element to swap.\n *\n * @return {array} The input array.\n */\nvar Swap = function (array, item1, item2)\n{\n    if (item1 === item2)\n    {\n        return array;\n    }\n\n    var index1 = array.indexOf(item1);\n    var index2 = array.indexOf(item2);\n\n    if (index1 < 0 || index2 < 0)\n    {\n        throw new Error('Supplied items must be elements of the same array');\n    }\n\n    array[index1] = item2;\n    array[index2] = item1;\n\n    return array;\n};\n\nmodule.exports = Swap;\n","sourceCodeStart":15,"sourceCodeEnd":43,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/utils/array/Swap.js#L15-L43","documentation":"Thrown by Phaser.Utils.Array.Swap when either of the two items is not found in the array (indexOf returns -1). Swap exchanges the positions of two elements by reference, so both must be members of the same array. The identical-reference shortcut (item1 === item2) returns early without error; only genuinely missing elements throw. Same invariant and message as MoveAbove/MoveBelow.","triggerScenarios":"Calling Swap(arr, a, b) where arr.indexOf(a) < 0 or arr.indexOf(b) < 0. Commonly when one element was removed, when a and b come from different arrays, or when comparing objects that are equal by value but not by reference (indexOf uses ===).","commonSituations":"Swapping z-order of two sprites where one was destroyed between frames. Drag-to-swap UIs where the dragged item is temporarily detached from the list. Using deep-cloned items while swapping against the originals. Race conditions in event-driven reordering where a remove event fires before the swap.","solutions":["Pre-check both: `if (arr.includes(a) && arr.includes(b)) Swap(arr, a, b);`.","Operate on references obtained directly from the array (e.g., group.getChildren()[i]) rather than cached copies.","If items may be transiently absent, defer the swap until both are confirmed present.","For index-based swapping where you know positions, swap via `var t = arr[i]; arr[i] = arr[j]; arr[j] = t;` after bounds-checking i and j."],"exampleFix":"// before\nPhaser.Utils.Array.Swap(children, spriteA, spriteB); // spriteB detached\n\n// after\nif (children.indexOf(spriteA) !== -1 && children.indexOf(spriteB) !== -1) {\n  Phaser.Utils.Array.Swap(children, spriteA, spriteB);\n}","handlingStrategy":"validation","validationCode":"function safeSwap(arr, a, b) {\n  if (arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1) {\n    return Phaser.Utils.Array.Swap(arr, a, b);\n  }\n  return arr;\n}","typeGuard":"function areSameArrayMembers(arr, a, b) {\n  return arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1;\n}","tryCatchPattern":"try {\n  Phaser.Utils.Array.Swap(arr, a, b);\n} catch (e) {\n  if (e.message !== 'Supplied items must be elements of the same array') throw e;\n  // graceful no-op: one side missing\n}","preventionTips":["Verify both items exist in the array with indexOf before swapping.","For index-based swaps, bounds-check i and j then assign directly rather than using Swap.","Re-fetch array elements at call time rather than relying on cached references.","Avoid swapping during async handlers that may fire after a removal."],"tags":["array","swap","membership","indexof","utils"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}