UnitySerializedShield for Visual Studio Code

UnitySerializedShield helps Unity developers safely rename serialized C# fields from Visual Studio Code without losing values already assigned in the Unity Inspector, prefabs, scenes, or ScriptableObjects.

When you rename a Unity field marked with [SerializeField], Unity normally needs [FormerlySerializedAs] to understand that the old serialized data belongs to the new field name. UnitySerializedShield adds that migration attribute automatically when you use VS Code's real Rename Symbol command.

Why Use It

Unity stores serialized values by field name. If a serialized field is renamed without migration metadata, Unity can lose the connection to existing Inspector values.

UnitySerializedShield helps protect:

• Inspector values on scene objects.
• Prefab references and tuned prefab values.
• ScriptableObject configuration data.
• Serialized gameplay, UI, enemy, level, and balancing fields.

Important Unity Migration Notice

This VS Code extension protects the C# rename step, but Unity serialized data still needs to be migrated inside Unity.

Do not manually remove all [FormerlySerializedAs] attributes before Unity has migrated the data. Removing them too early can cause Unity Inspector values, prefab references, scene references, or ScriptableObject data to be lost.

For the safest workflow, also install the UnitySerializedShield Unity package from the GitHub repository:

unity-extension/UnitySerializedShield/package.json

Install it in Unity:

1. Open your Unity project.
2. Go to Window > Package Manager.
3. Click the + button.
4. Choose Add package from disk....
5. Select unity-extension/UnitySerializedShield/package.json.

You can also install the Unity package from Git:

https://github.com/AlphaBoysLab/unity-serialized-shield.git?path=unity-extension/UnitySerializedShield

After renaming fields, open Unity and run the SerializedShield migration workflow. The Unity package migrates serialized data and can remove completed [FormerlySerializedAs] attributes after references are preserved.

For full setup and migration instructions, visit the GitHub repository: AlphaBoysLab/unity-serialized-shield

How It Works

Rename a serialized field in VS Code using Rename Symbol from the menu or F2.

Before rename:

using UnityEngine;

public sealed class EnemySensor : MonoBehaviour
{
    [SerializeField] private float maxDistance = 100f;
}

After renaming maxDistance to attackDistance, UnitySerializedShield updates the script:

using UnityEngine;
using UnityEngine.Serialization;

public sealed class EnemySensor : MonoBehaviour
{
    [FormerlySerializedAs("maxDistance")]
    [SerializeField] private float attackDistance = 100f;
}

Unity can now reconnect the old serialized value to the new field name.

Features

• Detects safe Unity [SerializeField] field renames.
• Adds [FormerlySerializedAs("oldName")] above the renamed field.
• Adds using UnityEngine.Serialization; when needed.
• Avoids duplicate migration attributes.
• Ignores normal typing and only reacts to real VS Code rename edits.
• Skips ambiguous cases instead of guessing.

Recommended Workflow

1. Install this VS Code extension.
2. Install the UnitySerializedShield Unity package in your Unity project.
3. Rename serialized fields in VS Code with Rename Symbol or F2.
4. Let the extension add [FormerlySerializedAs("oldName")].
5. Open Unity and run the SerializedShield migration workflow.
6. Let the Unity package migrate serialized assets and clean completed migration attributes.

Supported Field Patterns

UnitySerializedShield focuses on common Unity field declarations:

[SerializeField] private float maxDistance = 100f;

[SerializeField]
private float maxDistance = 100f;

[Header("Movement")]
[SerializeField] private float maxDistance = 100f;

Safe Skip Behavior

The extension intentionally skips ambiguous cases rather than adding a wrong migration attribute.

Skipped examples include:

• Non-serialized fields.
• Static fields.
• Const fields.
• Multi-field declarations such as private int a, b;.
• Cases where the field type, initializer, and name all change at the same time.

Status Command

Run UnitySerializedShield: Show Status from the Command Palette to confirm the extension is active.

Learn More

Documentation, source code, Unity package instructions, and issue tracking are available on GitHub:

AlphaBoysLab/unity-serialized-shield

License

UnitySerializedShield is released under the MIT License.