Best Practices

Some conventions and best practices while using odb.

Entity best practices

• Use int entities and API calls, instead of the legacy Entity API calls.
• Beware the intricacies of the entity lifecycle.
  • Subscriptions are frozen during system processing and do not reflect deleted or new entities.
• Consider using Fluid-Entities, but only if you hate typing.

Components best practices

• Put data in components, behavior in entity systems.
• Strive for reusable components.
  • Limit the amount of component fields. A component with position, rotation, sprite limits the use cases of the component.
  • Avoid repeating the same information across multiple components.
• Use entity references judiciously. They go stale when you delete them elsewhere and cause bugs.
  • Consider letting odb manage entity references for you.
  • Consider referring to entities via identifiers like tag or group.
  • Or manage the references via a system or manager by listening in on the EntitySubscription.
• Use prefabs or Entity-Transmuter for high volume creation of entities, like particles.
• Prefer component mappers over Entity-Transmuter in other cases.
• Consider using IDE Code Templates for adding component mappers quickly.
• Consider skipping the Component class name suffix. You'll be typing component names a lot.
• Strive for primitives, strings and simple data as component fields. This is easier to persist and network.
• Mark components with unserializable information with @Transient.
• Beware altering deleted entities.

System best practices

• Favor small systems over less systems.
• Avoid initializing in system constructors.
• Avoid a deep system hierarchy, keep it flat.
• Operate on entity subscriptions using IteratingSystem.
• Implement supporting services using BaseSystem.

Decoupling systems

Always look for ways to decouple systems.

• Put code with multiple call sites in dedicated utility Pojo's or systems.
• Avoid coupling systems whenever possible.
• Avoid coupling systems that operate on entities.
• Consider decoupling systems using singleton components or events. (pass data, don't chain behavior).

Aspects

• Beware the performance of creating aspects at runtime.
• Avoid creating aspects in tight loops.
• Use the aspect annotations over Aspect.all builder whenever possible.

Iterating entities best practices

Fastest (and verbose) way to iterate entity identifiers:

IntBag entities = subscription.getEntities();
int[] ids = entities.getData();
for (int i = 0, s = entities.size(); s > i; i++) {
     // do something with ids[i]
}