Page is very WIP
Entities are the main attraction (apart from the voxel themselves !). Entities are persistent objects that don't need to be aligned on the grid. They can represent a great deal of thing, so it's hard to define them precisely. Examples of entities could be projectiles, living creatures, player models, dropped items, vehicles, physics-enabled objects etc. Entities are replicated and kept in sync from the server to the client.
Entities are actually a very complicated thing. Because they can have so many aspects to them and hold a good chunk of the gameplay code, they call for smart design patterns to keep their logic sane and somewhat readable. In Chunk Stories this is accomplished through the use of composition, entities delegate large aspects of themselves to smaller classes that are instanced once per entity and added to it at constructor time.
These constitutive elements are of two classes: Traits or EntityComponents. Traits are as the name hints, an object that represent a specific aspect of an entity, a property it has. Traits are not replicated or saved with the entity, they cannot hold long-term state and information.
This is the responsibility of EntityComponents: these are just like traits with the difference being in that they are also data containers, with functions for reading and saving their data in a byte stream. EntityComponents are saved with entities ( actually they define almost everything about the entity but it's UUID and entity definition ). They are also replicated to online players, with the ability to customize what player receives what information.
Entities are defined in .entities files. The syntax is always the same in those files, and it's very simple:
entity zombie class: io.xol.chunkstories.core.entity.EntityZombie collidesWithEntities: true startHealth: 50 maxHealth: 100 end
The most important things here are the entity name and the class property. The entity name is the name that will be given to the entity definition/type that you can use to instanciate the entity in your code later. The class property tells the engine the exact name of the Java class to create to build one such entity. The other properties are actually passed to that
new EntityXXX() constructor so you can parse them yourself.
TODO: add simple pseudocode examples for template entities
To learn more about anything in programming, the best thing might always be to read the code. Chunk Stories's default entities are a part of the chunkstories-core project on GitHub ( click here ), and reading them and understanding what everything do will put you on the right path to start programming your own.
Also there is an official blog post on the chunkstories blog about the recent redesign of entities and motivations behind the traits/components pattern we use, here it is