title: ECS Overview #
ECS Overview #
Entity Component System (ECS) is a framework for modeling data for objects in a game world. All of the simulations in Thorium Nova are built around ECS. ECS entities and components also serve as the primary database for flights.
The most basic unit of ECS is an entity, which is used to represent a single object in the game world. An entity could be a ship, a projectile weapon, a sound effect, or a person on a ship.
Of course, entities aren't anything but unique IDs until components are added to
them. Components provide state to entities and indicate that they should have
certain behaviors. identity is a component that gives an entity a name and
description. position and velocity provide those properties. isShip
indicates that an entity is a spaceship, and contains properties that are unique
to ships, such as the registry number and ship class.
Entities shouldn't have any properties or state assigned directly to them, other
than their unique ID. All state is handled by components which are assigned to
the entity. Likewise, components shouldn't have any behavior - other than their
constructor and a static serialize function which prepares them to be stored
in the database. Components only store the state that they were designed to
store.
Inputs (mutation messages from the client to the server) will most often find a specific entity or group of entities and either add or remove components or update the properties of existing components.
Systems are the piece that provides all of the behavior for entities. Systems
include a test function to determine which entities the system should be run on,
and an update function which is called for each entity to update its components.
Systems could include VelocityPositionSystem which updates the position of an
entity based on its velocity, TimerSystem, which counts down a timer, or the
DataStreamSystem which sends high-frequency updates to connected clients.
Since one system might depend on the results of another system's update, the
order that systems run matters.
Each flight has its own ECS world. When a flight is created, it will pull the list of systems from "/server/src/systems/index.ts" and instantiate them, and create any initial entities and assign them their components.
Note: Thorium Nova's ECS framework is currently only used on the server side, not the client side. This could change in the future, but for now it makes more sense to use React state, the useFrame hook from React Three Fiber, and the useAnimationFrame hook to update the UI.
Adding new data structures or simulations usually looks like this:
- Create a new component or add properties to an existing component.
- Assign the component to the appropriate entities, either through Systems updates or input mutations.
- Factory functions can be created for common entity types.
- Create a new system or change the test function or update function of an existing system.
- Make sure any new systems are listed in "/server/src/systems/index.ts"