Getting Started

Getting the Library

Either download the latest core (and/or network) release from here: Releases

Or configure your build tool to pull them automatically (gradle/maven/etc.). The Zay-ES jars are available in the jcenter public repository.

Here is an example section from a build.gradle file that includes both Zay-ES core as well as the network library:

dependencies {
    compile "com.simsilica:zay-es:1.2.1"
    compile "com.simsilica:zay-es-net:1.2.1"
}

Required Dependencies

If you are not using a modern build tool that automatically resolves dependencies then you will also need to download some additional jars:

• Guava version 12 or later
• slf4j version 1.7.5 or later, plus an adapter for your preferred logging framework. (At minimum, you will need the API jar, something like: slf4j-api-1.7.5.jar)

Create the main EntityData object

EntityData is the main class that will hold all of the components. To instantiate a basic 'in memory' version is as easy as:

    EntityData ed = new DefaultEntityData();

Create an Entity

Creating an entity is really just generating a new EntityId to which components can be attached.

    EntityId myEntity = ed.createEntity();

Set a Component

Usually an application will create its own EntityComponent implementation classes but Zay-ES comes with a couple standard ones. The following code illustrates setting a Name on the previously created entity.

    ed.setComponent(new Name("My Entity"));

Watching for Changes (the game loop)

One of the main differences between Zay-ES and other ECS frameworks is that you are not forced into a particular 'system' model. How you write your systems and how you use the entities is more or less up to you. So instead of an https://en.wikipedia.org/wiki/Inversion_of_control approach where you implement some system class and the framework calls you, you can simply query the entities you want when you want them. Zay-ES provides internal mechanisms to make this efficient.

A basic polling loop:

    EntitySet namedEntities = ed.getEntities(Name.class);
    while( true ) {
        namedEntities.applyChanges();
        for( Entity e : namedEntities ) {
            // do something every frame
        }
    }

A more efficient polling loop where code is run only when entities change:

    EntitySet namedEntities = ed.getEntities(Name.class);
    while( true ) {
        if( namedEntities.applyChanges() ) {
            // do something with newly matching entities
            addSomeStuff(namedEntities.getAddedEntities());

            // do something with entities that are no longer matching
            removeSomeStuff(namedEntities.getRemovedEntities());

            // do something with the entities that have merely changed
            changeSomeStuff(namedEntities.getChangedEntities());
        }
    }

For further reading see:

• Documentation
• Core API Javadoc
• Network API Javadoc