Updating Existing Signalia Project from 2.X.X to 3.X.X

📘 Signalia Upgrade Guide

Migrating from 2.X.X → 3.X.X

This guide will help you safely upgrade your project to Signalia 3.X.X. Please follow the steps carefully to avoid broken references or conflicts.

🔒 1. Save and Back Up Everything

Before doing anything, back up your project.

• If you’re using version control (Git, SVN, etc.), commit your current state and create a tag or branch.

Why: Signalia 3.X.X includes breaking changes. If something goes wrong, you’ll need a safe restore point.

🗒️ 2. Open an Empty Scene

• Create or open a new empty scene.

• Do not have any prefabs open or selected.

Why: Unity might lock objects or references if they’re active while removing old Signalia files. A blank scene ensures nothing breaks during cleanup.

🗑️ 3. Exit Unity and Delete the Signalia Folder

1. Close Unity completely.

2. Navigate to your project folder on disk:

   Assets/AHAKuo Creations/Signalia
   

3. Delete this folder entirely (including its .meta).

4. Reopen Unity.

5. Enter Safe Mode when Unity prompts you.

Why: Deleting while Unity is running can leave cached references or lock files. Doing this step outside of Unity ensures a clean removal.

⚠️ 4. Ignore the Errors

After reopening Unity in Safe Mode, you will see many console errors.
This is expected since all Signalia scripts are currently missing.

📥 5. Download the Latest 3.X.X

• Open Package Manager.

• Download the most recent Signalia 3.X.X package.

📦 6. Import 3.X.X

• Import the new Signalia package into Unity.

• Let Unity fully recompile.

🛠 7. Fixing Compilation Issues (If Unity Fails to Exit Safe Mode)

If Unity fails to compile after import, your project may still reference old game system tools such as Pooling, Saving, or Instancer. Apply the following fixes:

Pooling

// First compilation only
using AHAKuo.Signalia.Framework.Packages.PackageSkeleton.PoolingSystem;

// After compilation, change to
using AHAKuo.Signalia.GameSystems.PoolingSystem;

Saving

// First compilation only
using AHAKuo.Signalia.Framework.Packages.PackageSkeleton.SaveSystem;

// After compilation, change to
using AHAKuo.Signalia.GameSystems.SaveSystem;

Instancer

using AHAKuo.Signalia.Utilities;

⚠️ Note: These temporary Skeleton namespaces apply only to your own scripts that reference these systems. Do not remove or modify the Skeleton references inside the Signalia package itself, as those are required by the framework.

🖥️ 8. Refresh the IDE Project (If Namespaces Are Not Recognized)

In some cases, your IDE (e.g., Rider, Visual Studio, VS Code) may not properly refresh its references after import. This can cause issues where even adding the temporary Skeleton namespaces doesn’t work or where Signalia as a whole isn’t recognized.

To fix this:

1. Close your IDE.

2. In Unity, go to:

   Assets → Open C# Project
   

3. Unity will regenerate the IDE project files and reopen your IDE with Signalia properly recognized.

After this, continue applying the necessary fixes.

🔍 9. Verify Project Integrity

Open your game’s main scenes and check that:

• UI components still work.

• Custom scripts referencing Signalia have no broken namespaces. If they do, update them to match the new structure.

• The Settings Window (Signalia → Settings) works as expected.

✅ 10. Done

Once you confirm everything works:

• Commit your project again or create a new backup.

• Ensure your own scripts no longer contain temporary Skeleton references after compilation succeeds.