Dominion ECS Java

To get started, create a Dominion instance, define your components (as classes or records), create entities, and run systems using a Scheduler.

Key steps:

1. Initialize: Use Dominion.create() to create your world.
2. Create Entities: Use hello.createEntity(name, components...) to add entities with specific data.
3. Define Systems: Systems are typically implemented as Runnable tasks that use findEntitiesWith(Class... componentTypes) to retrieve entities and their associated components.
4. Schedule and Run: Create a Scheduler via hello.createScheduler(), schedule your system, and start the loop with tickAtFixedRate(rate).

public class HelloDominion {

    public static void main(String[] args) {
        // creates your world
        Dominion hello = Dominion.create();

        // creates an entity with components
        hello.createEntity(
                "my-entity",
                new Position(0, 0),
                new Velocity(1, 1)
        );

        // creates a system
        Runnable system = () -> {
            //finds entities
            hello.findEntitiesWith(Position.class, Velocity.class)
                    // stream the results
                    .stream().forEach(result -> {
                        Position position = result.comp1();
                        Velocity velocity = result.comp2();
                        position.x += velocity.x;
                        position.y += velocity.y;
                        System.out.printf("Entity %s moved with %s to %s\n",
                                result.entity().getName(), velocity, position);
                    });
        };

        // creates a scheduler
        Scheduler scheduler = hello.createScheduler();
        // schedules the system
        scheduler.schedule(system);
        // starts 3 ticks per second
        scheduler.tickAtFixedRate(3);
    }

    // component types can be both classes and records

    static class Position {
        double x, y;

        public Position(double x, double y) {/*..."}

        @Override
        public String toString() {/*..."}
    }

    record Velocity(double x, double y) {
    }
}

The Results class is the output of search methods like findEntitiesWith or findCompositionsWith. It acts as a container for entities that match your criteria (component types and optional states).

Results supports:

• Filtering: Use .without(Class<?>...) to exclude specific component types or .withAlso(Class<?>...) to further refine the search. Use .withState(S state) to filter by an entity's Enum state.
• Iteration: Use .stream() for functional-style operations or .iterator() for sequential access.

// Find all entities with both Position and Velocity
Results<Entity> movingEntities = dominion.findEntitiesWith(Position.class, Velocity.class);

// Filter results further
Results<Entity> activeMovingEntities = movingEntities
    .without(GhostComponent.class)
    .withState(EntityState.ACTIVE);

// Process results
activeMovingEntities.stream().forEach(e -> {
    Position p = e.get(Position.class);
    // ...
});

The Scheduler class is responsible for managing the lifecycle and execution order of systems. Systems are defined as Runnable types (such as lambda expressions) and are executed on every tick.

Key Execution Models

• Sequential Execution: Use schedule(Runnable system) to ensure systems run one after another. No more than one task will be active at any given time.
• Parallel Execution: Use parallelSchedule(Runnable... systems) to run multiple systems concurrently within a single execution slot. These slots are then executed sequentially relative to other slots.
• Fork-Join Pattern: A system can spawn sub-tasks to run in parallel and wait for them to complete using forkAndJoin or forkAndJoinAll.

Lifecycle Management

• Suspension: You can pause a scheduled system using suspend(Runnable system) without losing its position in the execution order. Use resume(Runnable system) to restart it.
• Shutdown: Use shutDown() to initiate an orderly shutdown. This allows currently submitted systems to finish executing but prevents any new systems from being accepted.

// Example of scheduling sequential and parallel systems
Scheduler scheduler = new Scheduler();

scheduler.schedule(() -> System.out.println("System A"));
scheduler.parallelSchedule(() -> System.out.println("System B"), () -> System.out.println("System C"));

// Start the execution loop
scheduler.tickAtFixedRate(60);

Entities are unique integer identifiers within a Dominion. You can create them in several ways:

1. Directly: Pass zero or more POJO components to createEntity.
2. Prepared: Use a Composition to pre-define the component structure for efficient creation via createPreparedEntity.
3. Prefab: Use an existing entity as a template via createEntityAs.

Once created, you can dynamically add/remove components, check for component presence, get component instances, or manage the entity's enabled state and Enum-based state.

// Direct creation
Entity entity = dominion.createEntity(new Position(0, 0), new Velocity(1, 1));

// Component management
entity.add(new Health(100));
boolean hasHealth = entity.has(Health.class);
Health h = entity.get(Health.class);
entity.removeType(Velocity.class);

// State and lifecycle
entity.setEnabled(false);
entity.setState(EntityState.ACTIVE);