70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
*| 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)
|