Dominion strives to have a minimal API surface to ease the learning curve for users.
With a bunch of well-organized classes, the library is capable of providing all the functionality implemented by the engine. This documentation will focus on these few interfaces.
As per tradition, Java projects come with a standard Javadoc site for API documentation. Dominion breaks tradition by putting all API references into this README to provide seamless navigation within the repository.
| Class | Description |
|---|---|
| Dominion | A Dominion is an independent container for all ECS data. |
| Composition | A Composition is the aggregation of components of which an entity can be made of. |
| Entity | An Entity identifies a single item and is represented as a unique integer value within a Dominion. |
| Results | A Results is a container of all entities that match a set of components and, optionally, have a specified state. |
| Scheduler | A Scheduler provides methods to submit/suspend/resume systems that are executed on every tick. |
A Dominion is an independent container for all ECS data. The User Application can create more than one Dominion with different names. It is the entry point for using the library and provides methods for creating, finding, and deleting items required by the user application.
| Method | Description |
|---|---|
| static Dominion create() | Creates a new Dominion with an automatically assigned name. |
| static Dominion create(String name) | Creates a new Dominion with the provided name. |
| String getName() | Returns the Dominion name. |
| Entity createEntity(Object... components); | Creates an Entity by adding zero or more POJO components. |
| Entity createPreparedEntity(Composition.OfTypes withValues); | Creates a new Entity by passing a prepared composition of one or more POJO components. |
| Entity createEntityAs(Entity prefab, Object... components); | Creates an Entity by using another Entity as prefab and adding zero or more POJO components. |
| boolean deleteEntity(Entity entity); | Delete the entity by freeing the id and canceling the reference to all components, if any |
| <T extends Entity> Results<T> findAllEntities(); | Finds all entities. |
| Results<With1> findEntitiesWith(Class<T> type); | Finds all entities with a component of the specified type. |
| Results<WithN> findEntitiesWith(Class<T1> type1,..) | Finds all entities with components of the specified types. |
| Results<With1> findCompositionsWith(Class<T> type); | Finds all compositions with a component of the specified type. |
| Results<WithN> findCompositionsWith(Class<T1> type1,..) | Finds all compositions with components of the specified types. |
A Composition is the aggregation of components of which an entity can be made of. Provides methods to prepare for entity creation with a certain component type composition or to prepare for entity change by specifying which component type is to be added and / or removed.
Dominion dominion = Dominion.create();
Composition composition = dominion.composition();
// prepared entity creations
var compositionOf1 = composition.of(Comp.class);
Entity entity1 = dominion.createPreparedEntity(compositionOf1.withValue(new Comp(0)));
Entity entity2 = dominion.createPreparedEntity(compositionOf1.withValue(new Comp(1)));
// prepared entity changes
var modifyAdding1 = composition.byAdding1AndRemoving(Comp2.class);
dominion.modifyEntity(modifyAdding1.withValue(entity1, new Comp2()));
dominion.modifyEntity(modifyAdding1.withValue(entity2, new Comp2()));
| Method | Description |
|---|---|
| Of1<T> of(Class<T> type); | Provides a prepared composition of a single component type. |
| OfN<T1,..,TN> ofN(Class<T1> type1, .., Class<TN> typeN); | Provides a prepared composition of N component types. |
| ByRemoving byRemoving(Class<?>... removedCompTypes); | Provides a prepared modifier to remove one or more component types. |
| ByAdding1AndRemoving<T> byAdding1AndRemoving(Class addedCompType, Class<?>... removedCompTypes); | Provides a prepared modifier to add one component type and optionally remove one or more component types. |
| ByAddingNAndRemoving<T1,..,TN> byAddingNAndRemoving(Class addedCompType1, .., Class addedCompTypeN, Class<?>... removedCompTypes); | Provides a prepared modifier to add N component types and optionally remove one or more component types. |
An Entity identifies a single item and is represented as a unique integer value within a Dominion. Entities can have a name and contain zero or more components that are POJOs with no behavior. Entities can change components dynamically, can be disabled and re-enabled and can have a given Enum value to optionally set a state.
| Method | Description |
|---|---|
| String getName() | Returns the entity name. |
| Entity add(Object component) | Adds one component that is a POJO with no behavior. |
| boolean remove(Object component) | Removes a component if present. |
| boolean removeType(Class<?> componentType) | Removes a component if there is a component of the specified type. |
| boolean has(Class<?> componentType) | Checks if there is a component of the specified type. |
| boolean contains(Object component) | Checks if the specified component is present. |
| <T> T get(Class<T> componentType) | Gets the component of the specified type if any. |
| <S extends Enum<S>> Entity setState(S state) | Sets a state to the entity or remove the current state by passing a null value. |
| boolean isEnabled() | Checks if the entity is enabled. |
| Entity setEnabled(boolean enabled) | Enable/Disables the entity. |
A Results instance is the output of the Dominion::findCompositionWith and ::findEntitiesWith methods and represents a simple container of all compositions that match a set of components and, optionally, the related entities. Results can be filtered by specifying one or more component types to include or exclude in the select list. Both iterator and stream methods are available to retrieve the results.
| Method | Description |
|---|---|
| Iterator<T> iterator(); | Provides an iterator to retrieve found entities in sequence. |
| Stream<T> stream(); | Creates a sequential stream to supports functional-style operations on found entities. |
| Results<T> without(Class<?>... componentTypes); | Provides a filtered Results without one or more component types to exclude. |
| Results<T> withAlso(Class<?>... componentTypes); | Provides a Results also considering one or more types of components as a filter. |
| Results<T> withState(S state); | Provides a filtered Results with only entities having the required state. |
A Scheduler provides methods to submit/suspend/resume systems that are executed on every tick. Systems are defined as a plain old Java Runnable type, so they can be provided as lambda expressions and are guaranteed to run sequentially. Parallel systems run concurrently in the same slot, which is scheduled sequentially in a guaranteed order. Systems, even if running parallel, can be suspended and resumed at any time, maintaining the order of execution. A system can fork by creating several subsystems for immediate parallel executions and "join" while waiting for all subsystems to execute. Schedulers can start a periodic tick that becomes enabled immediately and subsequently with the given fixed rate. A deltaTime method provides the time in seconds between the last tick and the current tick.
schedule(A)
parallelSchedule(B,C)
schedule(D)
tickAtFixedRate(1)
system A ---#---------------|*------|*------|*------|*----------
system B --------#----------|-*-----|-*-----|-*-----|-*---------
system C --------#----------|-*-----|-*-----|-*-----|-*---------
system D -------------#-----|--*----|--*----|--*----|--*--------
| | | tick0s tick1s tick2s tickNs
+A +B,C +D |>
suspend(B)
suspend(D)
system A -|*--------------|*--------------|*-------
system B -|-*----X--------|---------------|--------
system C -|-*-------------|-*-------------|-*------
system D -|--*-------X----|---------------|--------
tickNs | | tickN+1s tickN+2s
-B -D
resume(B)
system A -|*----------|*-----------|*-------
system B -|------#----|-*----------|-*------
system C -|-*---------|-*----------|-*------
system D -|---------- |------------|--------
tickNs | tickN+1s tickN+2s
+B
systemA.forkAndJoinAll(subsystemA1, subsystemA2)
system A -|*_*--------|*_*--------|*_*--------|
sub A1 -|-*---------|-*---------|-*---------|
sub A2 -|-*---------|-*---------|-*---------|
system B -|---*-------|---*-------|---*-------|
system C -|---*-------|---*-------|---*-------|
| | |
*A1,A2 *A1,A2 *A1,A2
| Method | Description |
|---|---|
| Runnable schedule(Runnable system); | Submits a system that becomes enabled immediately and executed on every tick. Scheduled systems are guaranteed to execute sequentially, and no more than one task will be active at any given time. |
| Runnable[] parallelSchedule(Runnable... systems); | Submits systems that become enabled immediately and executed on every tick. Parallel systems run concurrently in the same slot, which is scheduled sequentially in a guaranteed order. |
| void suspend(Runnable system); | Suspends an already scheduled system preserving its execution order. |
| void resume(Runnable system); | Resumes an already suspended system in the original execution order. |
| void forkAndJoin(Runnable subsystem); | A system can fork by creating a subsystem for immediate execution and "join" while waiting for the subsystem to execute. |
| void forkAndJoinAll(Runnable... subsystems); | A system can fork by creating several subsystems for immediate parallel executions and "join" while waiting for all subsystems to execute. |
| void tick(); | Starts running all scheduled systems sequentially in a guaranteed order. Systems sent in parallel run concurrently in the same slot, which is scheduled sequentially in a guaranteed order. |
| void tickAtFixedRate(int ticksPerSecond); | Starts a periodic tick that becomes enabled immediately and subsequently with the given fixed rate. |
| double deltaTime(); | DeltaTime is the time in seconds between the last tick and the current tick. |
| boolean shutDown(); | Initiates an orderly shutdown in which previously submitted systems are executed, but no new systems will be accepted. |
If you want to support Dominion project, consider giving it a Star ⭐️