{"record":{"id":"237182b97393c0eb","repo":"liabru/matter-js","slug":"composite-add-skipped-adding-a-compound-body-part","errorCode":null,"errorMessage":"Composite.add: skipped adding a compound body part (you must add its parent instead)","messagePattern":"Composite\\.add: skipped adding a compound body part \\(you must add its parent instead\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/body/Composite.js","lineNumber":104,"sourceCode":"     * @method add\n     * @param {composite} composite\n     * @param {object|array} object A single or an array of body(s), constraint(s) or composite(s)\n     * @return {composite} The original composite with the objects added\n     */\n    Composite.add = function(composite, object) {\n        var objects = [].concat(object);\n\n        Events.trigger(composite, 'beforeAdd', { object: object });\n\n        for (var i = 0; i < objects.length; i++) {\n            var obj = objects[i];\n\n            switch (obj.type) {\n\n            case 'body':\n                // skip adding compound parts\n                if (obj.parent !== obj) {\n                    Common.warn('Composite.add: skipped adding a compound body part (you must add its parent instead)');\n                    break;\n                }\n\n                Composite.addBody(composite, obj);\n                break;\n            case 'constraint':\n                Composite.addConstraint(composite, obj);\n                break;\n            case 'composite':\n                Composite.addComposite(composite, obj);\n                break;\n            case 'mouseConstraint':\n                Composite.addConstraint(composite, obj.constraint);\n                break;\n\n            }\n        }\n","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/liabru/matter-js/blob/acb99b6f8784c809b940f1d2cf745427e088e088/src/body/Composite.js#L86-L122","documentation":"Composite.add refuses to add an individual part of a compound body. Compound parts are internally linked to their parent (part.parent !== part); adding a part directly would corrupt collision and position bookkeeping, so Matter.js warns and skips the add instead. You must add the parent Body created by Body.create({ parts: [...] }).","triggerScenarios":"Iterating over body.parts and calling Composite.add(world, part) for each; accessing body.parts (which includes the parent at index 0 and parts from index 1) and passing any element whose parent !== itself.","commonSituations":"Building multi-shape bodies then copying parts into the world; cloning/serializing bodies by iterating parts; helper utilities that add every body object they find.","solutions":["Add the parent body: Composite.add(world, parentBody).","If iterating, skip parts where part.parent !== part (parts[0] is the parent).","If you actually want separate bodies, create them individually rather than as compound parts."],"exampleFix":"// before\nfor (const part of compoundBody.parts) {\n  Composite.add(world, part); // warns for non-root parts\n}\n// after\nComposite.add(world, compoundBody); // add the parent only","handlingStrategy":"validation","validationCode":"function isRootBody(b) { return b && b.type === 'body' && b.parent === b; }\nif (isRootBody(candidate)) Composite.add(world, candidate);","typeGuard":"function isCompoundPart(body) {\n  return Boolean(body && body.parent && body.parent !== body);\n}","tryCatchPattern":null,"preventionTips":["Always add the parent body returned by Body.create({ parts: [...] })","Remember body.parts[0] is the parent; parts[1..] are children","Skip elements where part.parent !== part when iterating parts","Never serialize/re-add bodies by iterating parts"],"tags":["physics","body","compound","misuse"],"backgroundTag":"compound-body-part-misuse","analyzedSha":"acb99b6f8784c809b940f1d2cf745427e088e088","analyzedAt":"2026-09-02T21:29:27.057Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}