Creating Entities

Destination Sol uses the Gestalt framework for creating entities. See its wiki for more details.

Components

The first step of creating an entity is defining the components that it can posses. This is done for each respective component in a new class that implements Component<?>. Your component should have private fields defined and public getters/setters for any externally relevant values. See this example component:

public final class TextInformation implements Component<TextInformation> {

    private String information = "Default information string";

    public String getInformation() {
        return information;
    }

    public void setInformation(String value) {
        information = value;
    }

    @Override
    public void copy(TextInformation other) {
        this.information = other.information;
    }
}

The copy method is very important - gestalt entity system copies components into its entity stores and then copies them back out when requested, so any value that isn't copied will be lost.

Prefabs

Now that you've defined your component, you can use a prefab to define an entity with the desired component datum. Using our example component:

{
  "entity": {
    "TextInformation": {
      "information": "Hello from my first prefab!"
    }
  }
}

The prefab specifies a recipe for an entity with the specific component values. It should be in the prefabs folder of your module with either the.prefab or .json file extension.

Entity Creation

With your components and prefab, you now have everything you need to create your entity. In your module code, create the entity defined by your prefab with entityManager.createEntity(Assets.getPrefab("module:prefab"));

For example, this class creates a new entity from the notepad.prefab in the notepad module at the start of the game, if one doesn't already exist:

public class TextInformationSystem extends ComponentSystem {

    @In
    private EntitySystemManager entitySystemManager;

    @Override
    public void preBegin() {
        EntityIterator iterator = entitySystemManager.getEntityManager().iterate(new TextInformation());
        while (iterator.next()) {
            if (iterator.getEntity().getComponent(TextInformation.class).isPresent()) {
                return;
            }
        }
        entitySystemManager.getEntityManager().createEntity(Assets.getPrefab("notepad:notepad"));
    }
}

Querying Entity Data:

Getting data from entities is as easy as 1-2-3:

1. Iterate through all entities with the desired component by using entityManager.iterate(new MyComponent());
2. Use entity.getComponent(MyComponent.class); to return an Optional with that component, if it is still present.
3. Use any public methods that are on the component (ie. your getter/setters).

This example command gets each entities Information value and returns a string with the results appended together:

@RegisterCommands
public class EditTextInformationCommand {

    @In
    private EntitySystemManager entitySystemManager;

    @Command(shortDescription = "Displays the text stored under Notepad entity.")
    public String getTextInformation() {
        StringBuilder response = new StringBuilder();
        EntityIterator iterator = entitySystemManager.getEntityManager().iterate(new TextInformation());
        while (iterator.next()) {
            if (iterator.getEntity().getComponent(TextInformation.class).isPresent()) {
                response.append(iterator.getEntity().getComponent(TextInformation.class).get().getInformation());
            }
        }
        return response.toString();
    }
}