JavaECS-Docs/README.md

| JavaECS

JavaECS Docs

View the Documentation

About Entity-Component-Systems

An Enity-Component-System comprises of four main parts

1. The entity which is essentially just a unique ID i.e. an integer value
2. The component which is a struct (class in Java). Typically contains data, but can be empty (to be used as a flag for certain systems) or contain function definitions.
3. The system which defines two main functions: init() and update(). Systems define a filter that is used to maintain a current and relevant list of entities that the system will act on.
4. The engine, which ties everything together. It exposes the functions that should be called, and methods for retrieving data correctly. The initialisation of everything required also takes place here

About the implementation

The JavaECS project is a Maven project targeting Java SE 1.8. It is released under the MIT licence. It is intended to be compiled and packed into a .jar and referenced and imported into a project. The Maven build script will produce a javadoc .jar with the library.

Getting started with JavaECS

Initialise the library like so:

Engine gameEngine = new Engine(/* desired number of entities */);

Next, the known components should be added.

Use the reflective component type:

gameEngine.registerComponent(ExampleComponent.class);

Next, register the systems that are required. Each system must be constructed, and passed as a parameter to the Engine.

• If the system shall be invoked elsewhere, then you can petition the engine for the instance of the system.

ExampleSystem exampleSystem = new ExampleSystem(gameEngine);
gameEngine.registerSystem(ExampleSystem.class, exampleSystem);

Next, create the entities that are needed as required.

Entity newEntity = gameEngine.createEntity();

Assign the components to the entity:

gameEngine.addComponent(newEntity, ExampleComponent.class, new ExampleComponent());

Be sure to call init() on each system, before the logical loop of the program

exampleSystem.init();

Finally, the engine is ready to enter the logical loop, e.g.:

while (true){
    exampleSystem.update();
}

• note systems are not required to perform their update() in the normal logical loop.
• the update can also be performed at a factored rate. E.g. physics can be performed at a different rate to the renderer, in order to improve physics accuracy
• when using your own implmentation of a system, you may leave init() empty. Therefore, it isn't necessary to call init() before the game loop. However, It is recommended that you call init() to maintain consistency with all systems in the engine.
• Entities, components, and systems can be created at any time in the program lifecycle.
  • Entities can be destroyed.
  • Components and systems cannot be destroyed.
  • Be aware that component registrations are contained via BitSet. As the array is extended as bits are needed, note that the order of the set bits may impact performance with a large number of component types.

Example:

App.java