Bone & Socket Rename Surgeon - UE5 plugin

You renamed hand_r_socket to Blade_R in the Skeleton Tree. Unreal renamed the socket object and its preview attachments, and nothing else. The Blueprint component attached to that socket, the variable that names it, the Spawn Emitter Attached pin, the Play Sound notify: every one of them still holds the old name, which now resolves to nothing. No error, no warning. The sword spawns at the character's origin. Bones do the same after a re-import: a physics asset built for Hips on a skeleton whose root is pelvis.

Bone & Socket Rename Surgeon finds every stored bone and socket name in the assets that use a skeleton, lists each one that resolves to no bone and no socket with every place that holds it, and carries a rename through all of those places at once. Journalled, reversible, re-checked after saving, and runnable in CI.

What it does

Audit, writes nothing. The asset registry names every asset that references the skeleton or its skeletal meshes. Each one in the folders you name is opened and every field that holds a bone or socket name is read: Blueprint components attached to a socket, Blueprint variables, unconnected Name pins on Blueprint and Anim Blueprint nodes, Anim Blueprint bone references (Modify Bone and the rest), class based animation notifies (Play Particle Effect, Play Sound, your own notify classes), physics asset bodies and constraints. Each name is judged against the bones and sockets that really exist, and the closest existing name is suggested when one shares a word.

Renames everywhere at once. -Rename=Old:New -Apply. When Old is a live socket, the socket itself is renamed on the skeleton or mesh that owns it, together with every place that holds it. When Old no longer exists (renamed in the Skeleton Tree, or gone in a re-import), every place still holding it is moved to New. Several pairs in one run. Each touched Blueprint is compiled once, physics assets are re-indexed, every package is saved, then the whole scan runs again from scratch and counts what still holds an old name.

Refuses before it writes. A new name that is already a bone or socket, an old name that is still a live bone (it never edits a bone hierarchy), an asset that also references a prop mesh with its own socket of the same name, a component attached to another component that has its own socket of that name, a read-only file, a socket rename while referencers sit outside the scope: each is named, and nothing is written. Undo byte for byte from the journal. CI gate: -FailOnDangling exits 5 while any stored name resolves to nothing. An HTML report on every run.

Measured on Epic's own template mannequin (Unreal Engine 5.8)

• A test project made from the Third Person template's mannequin (its skeleton, both meshes, its animations, its Anim Blueprint and its physics asset), plus three Blueprints that attach to sockets three ways (a component, a variable, a node pin), an Anim Blueprint with a bone reference and a socket pin, two notifies on a template animation and a second physics asset.
• The audit opened 111 assets and read 687 stored names; Epic's template plus the healthy fixture read 0 dangling.
• One run renamed the live socket hand_r_socket to Blade_R: 9 places in 5 packages, 3 Blueprints compiled, and a fresh scan found 0 places on the old name. -Undo put 5 packages back byte for byte.
• Then the damage Unreal's own tools leave: the socket renamed in the Skeleton Tree, and a physics asset authored for a Hips root. The audit found hand_r_socket dangling in 8 places (Blueprint, Anim Blueprint, Animation) and Hips in 6; 14 dangling places in all.
• One repair run moved 14 places to Blade_R and pelvis, re-indexed 1 physics asset, and the re-check read 0 places on an old name. Final audit: 0 dangling.
• 8 refusal cases each wrote nothing (every fixture file compared by sha256 before and after). 30 editor runs, 146 checks, all passing.
• Epic's template taught it three things before release: the UE5 mannequin already has a weapon_r bone, so Weapon_R is refused as a new socket name; its physics asset carries constraints named UserConstraint, which are the constraints' own names and not bones; and the Third Person character's camera hangs on the spring arm's SpringEndpoint socket. Installed into a brand new Third Person project, the audit reads 578 stored names and 0 dangling.

Requirements

• Unreal Engine 5.8, Windows (Win64), editor only. Only 5.8 has been built and run.
• Run as a commandlet: UnrealEditor-Cmd.exe <Project>.uproject -run=BoneSocketRename -Help.

Limits

Version 1.0 does not open maps, World Partition actor packages or Control Rig assets; every one that references the skeleton is listed by name in the report, never skipped silently. A bone or socket pin wired to another node is computed at runtime: it is counted, never judged. A name inside a map or set field is not read. It never edits a bone hierarchy: rename the bone first (Skeleton Editing or a re-import), then run the repair.

Full documentation: Bone & Socket Rename Surgeon README

More Unreal tools from the same studio: AnimNotify Event Rebinder (rename a notify and rebind every Anim Blueprint event), Retarget Relinker (re-point the whole project at a retargeted animation library) and Row Rename Surgeon (rename a DataTable row and carry every reference). Everything else: csaf.itch.io

AI disclosure: the code and the store images were produced with AI assistance.