API Syntax: Renaming Entity.Repace?

Isssue

In Entitas the proper way to change component values is to replace the component entirely with a new component containing different values using the entity.Replace[ComponentName](values) helper method.

entity.ReplacePosition(10, 100);
entity.ReplaceHealth(entity.health.value - 1);

This makes sense due to the immutable nature of components, however, it’s not very intuitive for beginners. Anyone not familiar with the system would wonder why the Position and Health components in the above example must be replaced. Why not just modify the values directly instead? This exact scenario has actually already happened and was discussed in the chat and inspired this possible solution.

Solution 1

Rename entity.Replace to either entity.Update, entity.Set or something similar to better indicate it’s purpose rather than function and minimize confusion for newcomers. So we would instead have something like this:

entity.UpdatePosition(10, 100);
entity.UpdateHealth(entity.health.value - 1);

Solution 2

bleedingpixels in the chat suggested the possibility of replacing both entity.Add and entity.Replace with entity.Set. So both adding and “modifying” components would look exactly the same.

entity.SetPosition(10, 100);
entity.SetHealth(entity.health.value - 1);

However, I’m not sure if this would be as intuitive as only renamingReplace itself.

Now the main issue with renaming Replace to something like “Update” is that it now suggests the data is mutable when it is actual not, but is that really an issue? Experienced users will already know it’s not and newcomers will be more likely to use it instead of just editing component values directly.

Update: as KumoKairo quoted below, we already have entity.isFlag = true/false which violates the entity.Replace rule.

[IsaiahKelly]

@zoujyjs Don’t know of any good references here, sorry. It’s something that’s really lacking at the moment with Entitas. As for your use case, my first guess would be that your component is probably too big and you just need to create a new separate smaller component and system to handle this one type of data.

However, as far as I understand it, you should always use entity.replace whenever you want to change any value on a component because modifying the values directly will not update other systems that work on them. Causing them to become outmoded and/or preventing them from reacting to state changes. Now if you don’t really need other systems to know about the changes then I guess you can get away with it, but it’s very likely to cause you problems later on if you need to know about these changes.

“Immutable”

The Entitas API treats component data as if it’s immutable, but components are actually recycled behind the scenes to avoid garbage collection. I think the logic behind this facade is to force people to use entity.replace whenever they want to change values, so systems can always get notified of changes, but I’m wondering now if this is actually having the opposite effect. Since the concept of replacing things you want to update seems strange and sometimes a little annoying, so people just end up modifying the values directly because it feels more natural or easier.

However, forcing you to replace components entirely, every time you want to change a value, does make people think about what data their components store a might help encourage them to follow the single responsibility principle more often.

Again in my mind just calling it set or update instead of replace seems like it might resolve some of these issues, but who knows, this might ultimately be just a personal preference.

In any case we probably need a dedicated section on this subject in the wiki because it seems to be a topic discussed in the chat often and is not very well understood or explained to newcomers.

[sschmid]

I like talking about details. In this case I don’t really see an issue, but I might be biased since we called it Replace since the beginning 4 years ago 😃 In my opinion Replace makes still sense as it also explains why entities leave a group and re-entering it (well at least in the mental model) when you change a component. By now we probably are all familiar with Groups and Reactive Systems, but in the beginning I managed to explain the functionality by talking about really replacing immutable components.

@IsaiahKelly

Unity ECS system uses Set

Afaik, they are actually setting the component. So it makes sense

@nbreum15

Microsofts C# naming conventions

Welcome to Unity gameObject.transform.position.x 😉

As a result of #508 I plan to expose the code generation templates, so everyone can make tweaks without adding a custom code generator. That means you can easily change method names (e.g. UpdateX) and change upper or lowercase.