Updating

How to move an existing project to a newer version of Massive Swarm System.

This page is rewritten for each release rather than added to, so it always describes the update in front of you. For the list of what changed in every version, see the changelog online, or the CHANGELOG.txt that ships next to this manual.

Which version do you have

Tools > Massive Swarm System > Welcome shows it in the window footer. So does Edit > Project Settings > Massive Swarm System, under Updates, next to the latest version on the Asset Store.

When a newer version is out

From 1.1.0 on, the editor tells you before you import anything. A one-line strip appears at the top of the Swarm Manager inspector, reading for example MSS 1.2.0 is available, with two buttons:

• View opens the Welcome window on a card for the update. The card says what to do before you update, and has Open in Package Manager and What's New, which opens the online changelog.
• Skip this version hides the strip and the card until a version after that one is released. It is per project. To get the notice back, press Stop Skipping under Updates in the Project Settings page.

How the editor finds out is described under The update check.

After you import one

The first time you open a project after importing a new release, a panel at the top of the Welcome window names the version the project was on and the version it is on now. It carries a button for the changelog and a button for this page. It shows for that one editor session, then stays quiet until the next release.

It says nothing on a first install, because there is no earlier version to compare against.

To stop the Welcome window opening by itself, untick Show this window on startup in its footer. The setting is per project. You can still open the window from the menu whenever you want, and if a release has landed since you last looked, the panel is there.

The normal update

1. Back up your project, or commit it if you use source control.
2. If you edited a file inside Assets/CreativeSpore/MassiveSwarmSystem, Assets/CreativeSpore/VatAnimator or Assets/CreativeSpore/Common, copy it somewhere else. The import overwrites all three folders.
3. Open the Package Manager on Massive Swarm System, press Update, then Import. The Welcome window's Open in Package Manager button takes you there.

You do not need to delete anything first. Unity matches each file by its GUID and rewrites it where it already sits, so your scenes, prefabs, materials and settings keep working with nothing to re-assign.

Nothing you bake or author needs to live in those three folders, and we recommend keeping your work outside them. Your Swarm Settings asset is created in Assets/MSS and VAT bakes go to Assets/VAT for that reason, and an update does not touch either folder.

If something is wrong after an update

A package import only adds and overwrites. It never deletes, so a file that a release removed stays on your disk, and a leftover script that references something the new version no longer has can stop your project compiling.

If that happens, delete Assets/CreativeSpore/MassiveSwarmSystem, Assets/CreativeSpore/VatAnimator and Assets/CreativeSpore/Common, then import the same version again. The reimport restores the same GUIDs, so nothing in your scenes loses its links. Check that release's entry in the changelog first: when an update needs more than this, the entry says so in its opening lines.

The update check

This is the only time Massive Swarm System uses the network, and it happens in the editor only.

• What it contacts: the Unity Asset Store, with one request to https://api.assetstore.unity3d.com/package/latest-version/384066. The answer holds the latest version number of Massive Swarm System, and that number is all the editor reads.
• What it sends: the request and nothing else. Nothing about you, your project or how you use the package.
• When: at most once a day, when the editor opens the project or reloads scripts. Never in a build, and never when the editor runs in batch mode, so a build machine does not make the request.
• If it fails: nothing happens. There is no dialog and no console message, and the editor tries again a day later.

To turn it off, open Edit > Project Settings > Massive Swarm System and untick Check For Updates under Updates. No request is made while it is off. The setting applies to that project only, so a second project asks until you untick it there too. It is stored on your computer and not in the project files, which means a teammate who opens the same project has their own switch. Check Now, on the same page, asks straight away.

Updating to 1.1.0

This release is the exception to the normal update: the folder has to be deleted first. Several files and folders moved in this version, and Unity updates a file where it already sits instead of moving it, so importing over 1.0 leaves the code in two places and the project will not compile.

1. Back up your project, or commit it if you use source control.
2. Move out anything of yours that lives inside Assets/CreativeSpore/MassiveSwarmSystem: a demo scene you built a level on, a sample profile you tuned in place, a preset you added to Settings/VAT Presets. The next step deletes the folder, and the import brings back only what shipped.
3. Delete Assets/CreativeSpore/MassiveSwarmSystem.
4. Import 1.1.0 from the Package Manager.

If you already imported over 1.0, delete Assets/CreativeSpore/MassiveSwarmSystem, Assets/CreativeSpore/VatAnimator and Assets/CreativeSpore/Common, then import again.

From 1.1.0 on the folders stay where they are, so later updates import in place.

If you are on 1.0 and something does not come back after this, write to us. There are very few of you, this release is the one big reorganisation, and we would rather fix your project by hand than leave you with it.

Everything you baked still works

Your baked assets, materials, prefabs and scenes carry on exactly as they were. Unity tracks those links by GUID, not by class name or file path, and no GUID changed. There is nothing to re-bake and nothing to re-assign.

C# that references the VAT classes needs its using lines updated

This reaches only your own scripts. The types were renamed along with the folder.

1.0.0	1.1.0
MassiveSwarmSystem.Runtime.Visuals.SwarmVatAnimation	CreativeSpore.Vat.Runtime.VatAnimator
MassiveSwarmSystem.Runtime.Visuals.SwarmVatAsset	CreativeSpore.Vat.Runtime.VatAsset
MassiveSwarmSystem.Runtime.Visuals.SwarmVatBatch	CreativeSpore.Vat.Runtime.VatBatch
MassiveSwarmSystem.Runtime.Visuals.SwarmVatTargetPlatformTier	CreativeSpore.Vat.Runtime.VatTargetPlatformTier

Four shared types moved to Assets/CreativeSpore/Common and changed namespace with it. A manager you derived from MonoSingleton<T>, as SwarmPoolManager in the Starter Kit does, needs using CreativeSpore.Common;.

1.0.0	1.1.0
MassiveSwarmSystem.Runtime.MonoSingleton<T>	CreativeSpore.Common.MonoSingleton<T>
MassiveSwarmSystem.Runtime.IMonoSingleton	CreativeSpore.Common.IMonoSingleton
MassiveSwarmSystem.Runtime.SingletonNoAutoCreate	CreativeSpore.Common.SingletonNoAutoCreateAttribute
MassiveSwarmSystem.Runtime.SwarmObjectCompat	CreativeSpore.Common.UnityObjectCompat

UnityObjectCompat.GetObjectId returns a ulong where SwarmObjectCompat.GetObjectId returned an int, so a dictionary keyed on it needs its key type changed.

If your scripts have their own assembly definition

Add CreativeSpore.Common to its Assembly Definition References, beside MassiveSwarmSystem.Runtime. SwarmManager derives from MonoSingleton<T>, which lives in that assembly now, so a script that touches the manager at all stops compiling without it. The error is CS0012 and it names the assembly. Add CreativeSpore.VatAnimator.Runtime too if the script names a VAT type.

Scripts with no assembly definition of their own need neither. Unity references every assembly for them.

Where the VAT tools went

The vertex-animation baker, its shaders and its runtime component now live in Assets/CreativeSpore/VatAnimator, with their own assemblies and their own namespace. Nothing was removed.

• The baker stays where it was, at Tools > Massive Swarm System > VAT Baker, and the form is the one you already know. The window is now called MSS VAT Animator Baker.
• A new project bakes into Assets/VAT. If you had already chosen an output folder, the baker keeps writing there.
• The three render shaders are listed under VAT Animator in the shader menu instead of Massive Swarm System / Swarm VAT. Your materials are unaffected, because Unity links a material to a shader by GUID. Only a script that looks one up by name needs the new string.
• Shared code now sits in Assets/CreativeSpore/Common.

Starter Kit projectiles stop at walls

A projectile fired by ProjectileWeapon used to stop only at something it could damage, and flew through everything else. In 1.1.0 it also stops at any solid collider on a layer in the weapon's Projectile Collision Mask. Trigger colliders still let it through unless they can take damage.

The mask starts as Everything. A weapon you set up in 1.0 and never narrowed now includes the ground, the walls and every prop, so shots can end early: on the floor when the muzzle sits low, or on a crate between the player and the target. Open the weapon and leave in the mask only the layers that should stop a shot. The Egypt bow and turret shipped on Everything and are on the Enemy layer in 1.1.0.

Where the demo samples went

Samples/FullDemo is gone. What was one folder is three, so a file's folder tells you what it is for.

Where it is now	What lives there
Samples/Shared	the layer every demo builds on: player, XP, respawn, HUD, VFX, audio, and every sample script
Samples/Egypt	the Egypt art set and the four scenes that run on it
Samples/Templates	small playable games to start your own from, one folder each
Samples/StarterKit	the combat kit, which did not move

Scene names did not change, only their folder. MSS Pyramid Level now opens from Assets/CreativeSpore/MassiveSwarmSystem/Samples/Egypt/Scenes/.

Deleting the demo samples by hand now means deleting Shared, Egypt and Templates together. The Welcome window's Remove Full Demo button takes all three and lists them before it does. See Samples and cleanup.

The Out-of-Sight Fallback moved to the Perception Profile

Whether an agent can see its target, and what it does once it cannot, is one asset's job now. In 1.0 the Behavior Profile answered it, under Lost Target Behavior > Out-of-Sight Fallback. In 1.1.0 the Perception Profile answers it, under Following The Crowd, and the old block is gone from the Behavior Profile.

If you never switched Use Out-of-Sight Fallback on, there is nothing to do here. It shipped off, and while it was off sight distance read as infinite, so every agent always saw its target. This move leaves your swarms as they were.

If you did switch it on, rebuild it in three steps. The numbers do not carry across by themselves, because the two blocks sit on different assets.

1. Create a profile with right-click in the Project window > Create > Massive Swarm System > Agents > Perception Profile.
2. Drop it into the Perception Profile slot on the archetype that used the fallback.
3. Turn Following The Crowd on and copy your old values over, using the table below.

1.0.0, on the Behavior Profile	1.1.0, on the Perception Profile
Use Out-of-Sight Fallback	Following The Crowd > Enabled
Sight Distance	Sight > Range
Follow Nearby Agents	Following The Crowd > Follow Strength
Neighbor Follow Radius	Following The Crowd > Neighbor Radius
Neighbor Samples	Following The Crowd > Max Neighbors
Memory Time	Following The Crowd > Heading Memory Time
Keep Moving Toward Target	Following The Crowd > Target Pull

Every default on the right is the number it was on the left, so an archetype that ran the block at its defaults needs the profile and the toggle and nothing else.

One of them does something a little different under its new name. Keep Moving Toward Target pulled toward wherever the target actually was, walls included. Target Pull pulls toward the last position the agent itself knew about, which is what the rest of perception is built on.

Scripts that read the deleted fields

ApproachAndPressSettings lost seven constructor parameters and the seven properties that read them: OutOfSightFallbackEnabled, SightDistance, LostTargetFollowWeight, LostTargetFollowRadius, LostTargetMaxNeighbors, LostTargetFollowMemoryTime and LostTargetSeekBias. What replaced them lives on SwarmPerceptionProfile, in its SightSenseSettings and CrowdFollowSettings. Code that reads Weight, ArrivalDistance, CombatStandoff or the chase wander fields is untouched.

Movement and Attack Profile values can differ per agent

The six Movement Profile fields that already varied per agent, and the four Attack Profile times, are now MSS's own per-agent values. Your profiles keep every number, and there is nothing to redo by hand. What you will notice:

• Linked values. Every agent now rolls one number when it spawns, and each field reads it by default, so a profile with a Max Speed range and a Max Turn Speed range makes its slow agents the slow turners. Each field keeps the spread it had; only which agent gets which value changes. To get the 1.0 behaviour back on a field, click the link icon beside it. The agent roll
• Four attack times renamed. The editor moves your values across the first time it opens the project and logs one line: [Massive Swarm System] Updated N Attack and Movement Profile(s) to the 1.1 fields. Their values did not change. N counts Attack and Movement Profiles together.

1.0.0	1.1.0
Swing Windup Seconds	Swing Windup
Swing Recovery Seconds	Swing Recovery
Swing Cooldown Seconds	Swing Cooldown
Contact Interval	Contact Hit Interval

• Curve Multiplier is gone. A Movement Profile field in Curve or Band mode now holds its real values. The editor multiplies each curve's keys by its old multiplier the first time it opens the project, so nothing changes for your agents; the curve just shows the numbers they get.

Scripts that read these fields

The six Movement Profile properties (MaxSpeed, MaxAcceleration, BrakingAcceleration, SteeringResponse, MaxTurnSpeed, MaxTurnAcceleration) return a SwarmAgentValue instead of a ParticleSystem.MinMaxCurve. Evaluate(roll, blend), GetRange and Representative replace the MinMaxCurve calls. On SwarmAttackProfile, SwingWindupSeconds, SwingRecoverySeconds, SwingCooldownSeconds and ContactInterval became SwingWindup, SwingRecovery, SwingCooldown and ContactHitInterval, each a SwarmAgentValue.