*| JavaECS*
# JavaECS Docs

### [View the Documentation](./docs/overview.md)

## *About Entity-Component-Systems*
An Enity-Component-System comprises of four main parts
1.  The [entity](./docs/entity/Entity.md) which is essentially just a unique ID *i.e. an integer value*
2.  The [component](./docs/entity/Component.md) 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](./docs/system/System.md) 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](./docs/Engine.md), 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:
``` java
Engine gameEngine = new Engine(/* desired number of entities */);
```
Next, the known components should be added.

Use the reflective component type:
``` java
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.*
``` java
ExampleSystem exampleSystem = new ExampleSystem(gameEngine);
gameEngine.registerSystem(ExampleSystem.class, exampleSystem);
```

Next, create the entities that are needed as required.
``` java
Entity newEntity = gameEngine.createEntity();
```

Assign the components to the entity:
``` java
gameEngine.addComponent(newEntity, ExampleComponent.class, new ExampleComponent());
```

Be sure to call `init()` on each system, before the logical loop of the program
``` java
exampleSystem.init();
```

Finally, the engine is ready to enter the logical loop, e.g.:
``` java
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](https://docs.oracle.com/javase/8/docs/api/java/util/BitSet.html). 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](/BrychanD/JavaECS-Examples/src/branch/master/demo1/src/main/java/nz/ac/massey/javaecs/examples/App.java#line=12-128)