Clone EntityStore

[DruidOwl]

Hello!

What is the intended/recommended way to clone the entire EntityStore (world) besides the round-trip JSON serialization?
I found no clues in API or docs. The only method is EntityStore.CloneEntity() which clones an entity within the same EntityStore.

The case: the world is relatively small and I need some snapshotting functionality for branched calculations.

[friflo]

This feature is currently not present.
This method should be called EntityStore.CopyEntity(Entity source). Maybe you can suggest a better name.
The copied entity would have the same entity Id as the source entity.

I will give it a try if its not too complicated.

[friflo]

Remarks

• Current state CloneEntity() always creates a new entity. An alternative name would be DuplicateEntity().
• The new functionality CopyEntity() will require two entity parameters: source & target.
  So its easier to distinguish this functionality from CloneEntity(). Also when reading the source.

So I will need to create new store and create the exact amount of entities as in the source, assuming Ids are assigned consequently, and the do one by one "copy" of entities in a loop?

Yes, this would be the case if the intension is to clone the entire source store.
Now I am sure there are use cases to "clone" only a subset of entities.
E.g. to clone only "network-work" entities for client / server environments.

Given that during copy within the same store Entity.Id is irrelevant (as it must be unique within the single store), why we need to force its equality with different stores?

Copy entity (source -> target) components and tags within the same store requires source and target entity ids to be different. So the entity ids are relevant in this case. Maybe I misunderstood.
Naming this "Duplicate" is misleading. The meaning implies an implicit entity creation.
This functionality is already present with CloneEntity().

When copying entities to a different store the typical use-case is to have the same entity ids in both stores.
But there may be exceptions wanting different ids of the "same" (same components & tags) entity.

I may add an instance method Entity.CopyEntityTo(Entity target) later for convenience.

[DruidOwl]

Thanks for the detailed answer.

Now I am sure there are use cases to "clone" only a subset of entities.

Yes, my case requires removing some entities from the cloned store (the cleaned store will be cloned further). Instead, I could copy only needed entities using Query or another filter.

I agree that "duplicate" and "clone" implies creation of a new object when "copy" can be understood as "content copy" to an existing target instance. In my example suggestion it's an entity instance method to copy to target store, in one of variations always creating a new entity, so I used terms as synonyms.

Btw, current CloneEntity() works strangely when passing in entity from another store. I can open an issue about this if needed to keep this topic focused.

[DruidOwl]

Regarding Ids. What will the expected result be in the following case (like your network comps example):

• Source store: entities with id: 1, 2, 3, 4, 5.
• Entities 2 and 4 are network and should be copied.
  What Ids will these network entities have in the target (different) store after copying? Will they be [1,2] or [2,4]?

In other words, how do I preserve [2,4] ids without creating 5 empty entities in advance in target store?

[friflo]

Example

• Source store: entities with id: 1, 2, 3, 4, 5.
• Copy (clone) only tagged entities [2,4] to target store.

Here a code snippet which preserves the ids [2,4] in the target store.

    var store       = new EntityStore();
    var targetStore = new EntityStore();
    
    store.CreateEntity(new Position(1,1,1));                        // 1
    store.CreateEntity(new Position(2,2,2), Tags.Get<TestTag>());   // 2
    store.CreateEntity(new Position(3,3,3));                        // 3
    store.CreateEntity(new Position(4,4,4), Tags.Get<TestTag>());   // 4
    store.CreateEntity(new Position(5,5,5));                        // 5
    
    // Query will copy only entities [2, 4]
    var query = store.Query().AnyTags(Tags.Get<TestTag>());
    foreach (var entity in query.Entities) {
        // preserve same entity ids in target store
        if (!targetStore.TryGetEntityById(entity.Id, out Entity targetEntity)) {
            targetEntity = targetStore.CreateEntity(entity.Id);
        }
        EntityStore.CopyEntity(entity, targetEntity);
    }
    AreEqual(new Position(2,2,2), targetStore.GetEntityById(2).GetComponent<Position>());
    AreEqual(new Position(4,4,4), targetStore.GetEntityById(4).GetComponent<Position>());

[friflo]

btw: Did you joined the Discord server?
I think your input could be valuable there.
This discussion is better placed here on GitHub - its a little too complex - but in general.

[friflo]

Just published v3.2.0
This version introduced EntityStore.CopyEntity(Entity source, Entity target)

class EntityStore {
    /// <summary>
    /// Copy all components, tags and scripts of the <paramref name="source"/> entity to the <paramref name="target"/> entity.<br/>
    /// The <paramref name="source"/> and <paramref name="target"/> entities can be in the same or different stores.
    /// </summary>
    /// <remarks>
    /// Child entities of the passed <paramref name="source"/> are not copied to the <paramref name="target"/> entity.<br/>
    /// If doing this these child entities would be children of both entities.
    /// </remarks>
    public static void CopyEntity(Entity source, Entity target)
}

[DruidOwl]

Awesome! Thank you for the quick update.
Just tested and it worked as intended!

It completely slipped my mind that entities can be created with a specific passed id. I missed that constructor, my bad. So half of this discussion has been answered by it )

Regarding Discord server: I'm not there yet, but will consider.
I thought topic about cloning is a good fit there, although, yeah, the discussion eventually got a bit complex.

[friflo]

👍
A note to performance.
CopyEntity() is highly optimized for performance.
It performance zero or one structural change (move an entity between archetypes).

When re-using the target EntityStore there is usually no structural change.
Assuming that the set of components and tags added to entity are not changing very often.
In case the set is different for both entities CopyEntity() will do a structural change.

Made a small performance test: Test_CopyEntity_Perf()
Copying 100.000 entities - each with 5 components - into a re-used target store takes ~6.2 ms.

[friflo]

hi @DruidOwl,

just published v3.2.1 with a simplified API and added documentation.
See Docs - Clone / Copy entity

Fixed also the issue you mentioned above.

Btw, current CloneEntity() works strangely when passing in entity from another store. I can open an issue about this if needed to keep this topic focused.

If passing now an entity from another store an exception will be thrown.
InvalidOperationException: entity is owned by a different store (Parameter 'entity')