Use InterestTemplate

Before reading this document, make sure you have read:

An InterestTemplate is a wrapper around the Interest component, providing intuitive methods to add, replace and clear queries from the underlying interest map.

Create a template

You create an empty InterestTemplate by calling InterestTemplate.Create(). This is useful when defining a set of interest queries for the first time, for example when defining entity templates.

var basicInterestTemplate = InterestTemplate.Create();

You can also construct this from an existing InterestTemplate or a set of interest queries. This creates a deep copy of the InterestTemplate, to allow you to modify the queries without affecting the original set.

var advancedInterestTemplate = InterestTemplate.Create(basicInterestTemplate);

Modify a template

When modifying an InterestTemplate, you must specify which particular component's queries you are modifying. You can either:

  • provide the component as a type argument
  • provide the component ID as the first argument
// Component identified by type argument
    .AddQueries<Position.Component>(query1, query2);

// Component identified by ID given as first argument
    .AddQueries(Position.ComponentId, query1, query2);

Add queries

When adding queries, you can either provide the queries as parameters or an enumerable set.

// Parameters
    .AddQueries<Position.Component>(query1, query2);

// Enumerable
var queryList = new List() { query1, query2 };

Replace queries

This operation replaces all the existing queries for the given component ID with the new queries you pass in. In a similar way to adding queries, you can provide the queries as parameters or an enumerable set.

// Parameters

// Enumerable
var queryList = new List() { query1 };

Note: At least one query must be provided, otherwise this operation does not remove the existing queries for a given authoritative component.

Clear queries

You can either clear queries for a given authoritative component or clear all queries in the InterestTemplate.

// Removes all queries added for the Position component

// Removes all queries

Get Interest from the template

After adding, removing or modifying a set of queries, there are two ways to get Interest out of the InterestTemplate.


To return a Snapshot of the Interest component that can be used when defining entity templates, call ToSnapshot() on the InterestTemplate.

// Create an interest template
var interestTemplate = InterestTemplate.Create()
    .AddQueries<Position.Component>(query1, query2);

// Create an entity template and add components to it
var entityTemplate = new EntityTemplate();

// Add the Interest component to the entity template
entityTemplate.AddComponent(interestTemplate.ToSnapshot(), WorkerUtils.UnityGameLogic);


To update Interest at execution time, you need to modify the underlying Dictionary within the Interest component.

The InterestTemplate class provides the AsComponentInterest method to return this Dictionary. This can be used to update the Interest component.

// Create the new interest template
var newInterestTemplate = InterestTemplate.Create()
    .AddQueries<Position.Component>(query1, query2);

// Require the InterestWriter and update the ComponentInterest field
InterestWriter.SendUpdate(new Interest.Update
    ComponentInterest = newInterestTemplate.AsComponentInterest();

How would I update Interest at runtime with the ECS workflow?

Instead of requiring and writing to an InterestWriter, you need to update an Interest.Component object.

// Some logic to get the Interest component
var interestComponent = someComponentGroup.InterestComponents[i];

// Create the new interest template
var newInterestTemplate = InterestTemplate.Create()
    .AddQueries<Position.Component>(query1, query2);

// Update the ComponentInterest field on the Interest component and write back the component
interestComponent.ComponentInterest = newInterestTemplate.AsComponentInterest();
someComponentGroup.InterestComponents[i] = interestComponent;

Updated about a year ago

Use InterestTemplate

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.