Instancing

Some scenes make use of a paradigm dubbed Instancing. In most cases, when swapping between instances, the developer iterates through the entities in the scene and removes the entities not needed for the next instance, or those being used in the transition.

The best practice to maintain stable analytics when switching instances is to let the atlasAnalytics entity persist when changing instances. In order to help the developer during scene deletion, we've created a custom component called AtlasAnalyticsFlag that is added to the atlasAnalytics entity during instantiation that allows it to be identified in downstream business logic.

// This code is inside atlas-analytics-service.ts
@Component("atlasAnalyticsFlag")
export class AtlasAnalyticsFlag {}

// This code can be used in any file that imports the atlasAnalytics 
// entity and returns a boolean that identifies the entity
entity.hasComponent(AtlasAnalyticsFlag)

In addition, we've provided a function within the AtlasAnalytics class called updateBranchName that can be used to tag the analytics going foward with the name of the new instance.

import { atlasAnalytics } from "./atlas-analytics-service";

atlasAnalytics.updateBranchName("Instance Name");

Here is an example of code that is representative of deleting all of the entities from the scene when changing instances and how to maintain stable analytics.

import { atlasAnalytics, AtlasAnalyticsFlag } from "./atlas-analytics-service";

// delete all entities except the atlas analytics entity
for(let entity of engine.entities){
    // check if entity is not atlas analytics entity
    if(!entity.hasComponent(AtlasAnalyticsFlag)){
        engine.removeEntity(entity);
    }
}

// rename the branch to the new instance name
atlasAnalytics.updateBranchName("New Instance Name");