Custom Entity Migration

[jkeon]

Unity will automatically remap Entity references on Components and in DynamicBuffers when Entities move from one World to another.

Entities that exist in TaskDrivers or EntityPersistentData however will not.

This PR gives functionality to provide a framework for allowing anything to be remapped and implements it for TaskDrivers and EntityPersistentData

What is the current behaviour?

No way to provide custom remapping.

What is the new behaviour?

Framework

Anything can implement the IMigrationObserver and register with the WorldEntityMigrationSystem to receive a notification when Entities have migrated to a new World.

The callback will provide the necessary information to perform the custom logic to remap Entity references.

MigrationUtil provides the functionality to actually do the remapping via RegisterTypeForEntityPatching and then the call to PatchEntityReferences.

All changes to the world should happen through WorldEntityMigrationSystem.MigrateTo. If you use the EntityManager.MoveEntitiesFrom vanilla function, we won't know and custom migration won't happen.

TaskDrivers and EntityPersistentData

I've handled both of these systems to automatically register their types and patch references. Everything is jobified so that we can use Burst and in practice ends up being pretty quick.

• TaskDrivers now can have a unique migration suffix to identify them if you happen to have two or more of the same type of TaskDriver located at the same place in the heirarchy.

Tag-Alongs

• Fixed ENABLE_UNITY_COLLECTIONS_CHECKS to ANVIL_DEBUG_SAFETY where I found them.
• Changed some type restrictions from struct to unmanaged
• Added a GetKeyValueArrays to EntityPersistentDataWriter

What's Next

• 233 There are still some ways you can miss Entities. If you have an EPD then you have a relationship of Key: Entity to Value: Something.

  • The Key can be remapped no problem
  • The Something might be a Collection like UnsafeParallelHashMap. If the key or something in that collection's value has an Entity reference, there's no way right now for us to know.
  • I think I can scan this an account for it, but I might have to add the check for each type of Unsafe Collection.

• 234 Integrity.

  • As we talked about, we should be able to build a lookup of all Entity references before the Migration occurs. After the Migration, we can run through that lookup and see if anything of our references were broken.
  • Either A) We referred to something that left us behind.
  • Or B) We referred to something that we left behind.
  • We can then alert the developer who didn't clean up before the migration.

What issues does this resolve?

• Resolves #42

What PRs does this depend on?

• None

Does this introduce a breaking change?

• [x] Yes - If you were changing Worlds through EntityManager, you should use WorldEntityMigrationSystem now instead.
• [ ] No

[jkeon]

@mbaker3 Ready for re-review.

Also contains changing the name of the Task Driver System to the outside to be System and the internal one to be TaskDriverSystem instead of the flip-flop it was before.

[mbaker3]

All addressed. Some discussions to sort out but this is looking good!