{"record":{"id":"3d288784ece3ec60","repo":"phaserjs/phaser","slug":"supplied-items-must-be-elements-of-the-same-array-3d2887","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/MoveBelow.js","lineNumber":34,"sourceCode":" * @param {array} array - The input array.\n * @param {*} item1 - The element to move below the base element.\n * @param {*} item2 - The base element.\n *\n * @return {array} The input array.\n */\nvar MoveBelow = function (array, item1, item2)\n{\n    if (item1 === item2)\n    {\n        return array;\n    }\n\n    var currentIndex = array.indexOf(item1);\n    var baseIndex = array.indexOf(item2);\n\n    if (currentIndex < 0 || baseIndex < 0)\n    {\n        throw new Error('Supplied items must be elements of the same array');\n    }\n\n    if (currentIndex < baseIndex)\n    {\n        // item1 is already below item2\n        return array;\n    }\n\n    //  Remove\n    array.splice(currentIndex, 1);\n\n    //  Add in new location\n    if (baseIndex === 0)\n    {\n        array.unshift(item1);\n    }\n    else\n    {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/utils/array/MoveBelow.js#L16-L52","documentation":"Thrown by Phaser.Utils.Array.MoveBelow when either item1 or item2 is absent from the array (indexOf returns -1). MoveBelow relocates item1 to immediately before item2 (toward the start of the array), so both must be present. Same invariant and same message as MoveAbove/Swap; the guard is identical across these three utilities.","triggerScenarios":"Calling MoveBelow(arr, a, b) with arr.indexOf(a) < 0 or arr.indexOf(b) < 0. Same family of causes as MoveAbove: stale references, value-vs-reference mismatches, items removed by a prior operation, or items belonging to a different array instance.","commonSituations":"Reordering z-order in a container or group where a child was destroyed between frames. Drag-and-drop reordering where the drop target was unmounted. Comparing Phaser Game Objects by a deep-equal helper while indexOf uses reference equality. Async scene transitions that null out references.","solutions":["Guard membership first: `if (arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1) MoveBelow(arr, a, b);`.","Cache the actual array elements (not look-alikes) before reordering.","If the array is a Phaser group's children, use group.getChildren() at call time rather than a cached snapshot.","Use MoveTo with an explicit index if you only know the target slot."],"exampleFix":"// before\nPhaser.Utils.Array.MoveBelow(list, nodeA, nodeB); // nodeA not in list\n\n// after\nvar list = group.getChildren();\nif (list.indexOf(nodeA) !== -1 && list.indexOf(nodeB) !== -1) {\n  Phaser.Utils.Array.MoveBelow(list, nodeA, nodeB);\n}","handlingStrategy":"validation","validationCode":"function safeMoveBelow(arr, a, b) {\n  if (arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1) {\n    return Phaser.Utils.Array.MoveBelow(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.MoveBelow(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\n}","preventionTips":["Use the live array (group.getChildren() or scene.children) at call time.","Confirm both items survived the current frame before reordering.","Centralize reorder calls behind a membership-checking wrapper.","Remember indexOf uses === : pass identical references, not deep-equal clones."],"tags":["array","reorder","membership","indexof","utils"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}