Get SpatialOS

Sites

Menu

How to 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
InterestTemplate.Create()
    .AddQueries<Position.Component>(query1, query2);

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

Add queries

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

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

// Enumerable
var queryList = new List() { query1, query2 };
InterestTemplate.Create()
    .AddQueries<Position.Component>(queryList);

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
InterestTemplate.Create(basicInterestTemplate)
    .ReplaceQueries<Position.Component>(query1);

// Enumerable
var queryList = new List() { query1 };
InterestTemplate.Create(basicInterestTemplate)
    .ReplaceQueries<Position.Component>(queryList);

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
basicInterestTemplate.ClearQueries<Position.Component>();

// Removes all queries
basicInterestTemplate.ClearAllQueries();

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.

Snapshot

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);

ComponentInterest

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();
});

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums