/// <summary>
/// Before to start a review of Svelto.ECS terminologies:
/// - Entity:
/// it must be a real and concrete entity that you can explain
/// in terms of game design. The name of each entity should reflect
/// a specific concept from the game design domain
/// - Engines (Systems):
/// Where all the logic lies. Engines operates on EntityViews or EntityStructs
/// - EntityViews and EntitiyViewStructs:
/// EntityViews maps Entity Components. The Engines can't
/// access directly to each entity (as a single set of components), but
/// through component sets defined by the EntityView.
/// They act as component filters and expose only the entity components
/// that the Engine is interested in.
/// EntityViews are actually defined with the Engine so they
/// come together with the engine and in the same namespace of the engine.
/// EntityViewStructs should always be used, while EntityViews as
/// class use should be considered an exception.
/// - Component Interfaces:
/// Components must be seen as data holders. There may be implementation
/// exceptions, but the interface must declare a group
/// of readable and/or writeable data.
/// In Svelto.ECS components are always interfaces declaring
/// Setters and Getters of Value Types. DispatchOnSet
/// and DispatchOnChange must not be seen as events, but
/// as pushing of data instead of data polling, similar
/// to the concept of DataBinding.
/// - Implementors:
/// Being components interfaces, they must be implemented through
/// Implementors. The relation Implementors to Components
/// is not 1:1 so that you can group several
/// components into fewer implementors. This allows to easily
/// share data between components. Implementors also act
/// as bridge between the platform and Svelto.ECS.
/// Since Components can hold only value types, Implementors
/// are the objects that can interact directly with the platform
/// objects, I.E.: RigidBody, Transform and so on.
/// Note: IComponents must hold only valuetypes for
/// code design purposes and not optmization purposes.
/// The reason is that all the logic must lie in the engines
/// so Components cannot hold references to instances that can
/// expose functions with logic.
/// - EntityStructs:
/// In order to write Data Oriented Cache Friendly and allocation 0 code, Svelto.ECS
/// also supports EntityStructs.
/// - EntityDescriptors:
/// Gives a way to formalize your Entity in svelto.ECS, it also
/// defoines the EntityViews, EntityStructs and EntityViewStructs that must be generated once the
/// Entity is built
/// </summary>
void SetupEngines()
{
//The Engines Root is the core of Svelto.ECS. You must NEVER inject the EngineRoot
//as it is, therefore the composition root must hold a reference or it will be
//GCed.
//the UnitySumbmissionEntityViewScheduler is the scheduler that is used by the EnginesRoot to know
//when to inject the EntityViews. You shouldn't use a custom one unless you know what you
//are doing or you are not working with Unity.
_enginesRoot = new EnginesRoot(new UnityEntitySubmissionScheduler());
//Engines root can never be held by anything else than the context itself to avoid leaks
//That's why the EntityFactory and EntityFunctions are generated.
//The EntityFactory can be injected inside factories (or engine acting as factories)
//to build new entities dynamically
_entityFactory = _enginesRoot.GenerateEntityFactory();
//The entity functions is a set of utility operations on Entities, including
//removing an entity. I couldn't find a better name so far.
var entityFunctions = _enginesRoot.GenerateEntityFunctions();
//the ISequencer is one of the 2 official ways available in Svelto.ECS
//to communicate. They are mainly used for two specific cases:
//1) specify a strict execution order between engines (engine logic
//is executed horizontally instead than vertically, I will talk about this
//in my articles). 2) filter a data token passed as parameter through
//engines. The ISequencer is also not the common way to communicate
//between engines
PlayerDeathSequencer playerDeathSequence = new PlayerDeathSequencer();
EnemyDeathSequencer enemyDeathSequence = new EnemyDeathSequencer();
//wrap non testable unity static classes, so that
//can be mocked if needed.
IRayCaster rayCaster = new RayCaster();
ITime time = new Time();
//Player related engines. ALL the dependencies must be solved at this point
//through constructor injection.
var playerShootingEngine = new PlayerGunShootingEngine(rayCaster, time);
var playerMovementEngine = new PlayerMovementEngine(rayCaster, time);
var playerAnimationEngine = new PlayerAnimationEngine();
var playerDeathEngine = new PlayerDeathEngine(playerDeathSequence, entityFunctions);
//Enemy related engines
var enemyAnimationEngine = new EnemyAnimationEngine(time, enemyDeathSequence, entityFunctions);
var enemyAttackEngine = new EnemyAttackEngine(time);
var enemyMovementEngine = new EnemyMovementEngine();
//GameObjectFactory allows to create GameObjects without using the Static
//method GameObject.Instantiate. While it seems a complication
//it's important to keep the engines testable and not
//coupled with hard dependencies references (read my articles to understand
//how dependency injection works and why solving dependencies
//with static classes and singletons is a terrible mistake)
GameObjectFactory factory = new GameObjectFactory();
//Factory is one of the few patterns that work very well with ECS. Its use is highly encouraged
IEnemyFactory enemyFactory = new EnemyFactory(factory, _entityFactory);
var enemySpawnerEngine = new EnemySpawnerEngine(enemyFactory, entityFunctions);
var enemyDeathEngine = new EnemyDeathEngine(entityFunctions, enemyDeathSequence);
//hud and sound engines
var hudEngine = new HUDEngine(time);
var damageSoundEngine = new DamageSoundEngine();
var scoreEngine = new ScoreEngine();
//The ISequencer implementation is very simple, but allows to perform
//complex concatenation including loops and conditional branching.
//These two sequencers are a real stretch and are shown only for explanatory purposes.
//Please do not see sequencers as a way to dispatch or broadcast events, they are meant only and exclusively
//to guarantee the order of execution of the involved engines.
//For this reason the use of sequencers is and must be actually rare, as perfectly encapsulated engines
//do not need to be executed in specific order.
//a Sequencer can:
//- ensure the order of execution through one step only (one step executes in order several engines)
//- ensure the order of execution through several steps. Each engine inside each step has the responsibility
//to trigger the next step through the use of the Next() function
//- create paths with branches and loop using the Condition parameter.
playerDeathSequence.SetSequence(
new Steps //sequence of steps, this is a dictionary!
{
{
/*from: */ playerDeathEngine, //when the player dies
/*to: */ new To <PlayerDeathCondition>
//all these engines in the list will be called in order (which in this
//case was not important at all, so stretched!!)
{
{ PlayerDeathCondition.Death, playerMovementEngine, playerAnimationEngine, enemyAnimationEngine, damageSoundEngine, hudEngine }
}
}
}
);
enemyDeathSequence.SetSequence(
new Steps
{
{ //first step
enemyDeathEngine,
new To <EnemyDeathCondition>
{
//TIP: use GO To Type Declaration to go directly to the Class code of the
//engine instance
{ EnemyDeathCondition.Death, scoreEngine, enemyAnimationEngine }
}
},
{ //second step
enemyAnimationEngine, //after the death animation is actually finished
new To <EnemyDeathCondition>
{
{ EnemyDeathCondition.Death, enemySpawnerEngine } //call the spawner engine
}
}
}
);
//All the logic of the game must lie inside engines
//Player engines
_enginesRoot.AddEngine(playerMovementEngine);
_enginesRoot.AddEngine(playerAnimationEngine);
_enginesRoot.AddEngine(playerShootingEngine);
_enginesRoot.AddEngine(new PlayerInputEngine());
_enginesRoot.AddEngine(new PlayerGunShootingFXsEngine());
_enginesRoot.AddEngine(playerDeathEngine);
//enemy engines
_enginesRoot.AddEngine(enemySpawnerEngine);
_enginesRoot.AddEngine(enemyAttackEngine);
_enginesRoot.AddEngine(enemyMovementEngine);
_enginesRoot.AddEngine(enemyAnimationEngine);
_enginesRoot.AddEngine(enemyDeathEngine);
//other engines
_enginesRoot.AddEngine(new ApplyingDamageToTargetsEngine());
_enginesRoot.AddEngine(new CameraFollowTargetEngine(time));
_enginesRoot.AddEngine(new CharactersDeathEngine());
_enginesRoot.AddEngine(damageSoundEngine);
_enginesRoot.AddEngine(hudEngine);
_enginesRoot.AddEngine(scoreEngine);
}
/// <summary>
/// Before to start, let's review some of the Svelto.ECS terms:
/// - Entity:
/// it must be a real and concrete entity that you can explain in terms of game design. The name of each
/// entity should reflect a specific concept from the game design domain
/// - Engines (Systems):
/// Where all the logic lies. Engines operates on EntityViewStructs and EntityStructs
/// - EntityStructs:
/// EntityStructs is the preferred way to store entity data. They are just plain structs of pure data (no
/// objects)
/// - EntityViewStructs:
/// EntityViewStructs are used to wrap Objects that come from OOP libraries. You will never use it unless
/// you are forced to mix your ECS code with OOP code because of external libraries or platforms.
/// The Objects are known to svelto through Component Interfaces.
/// - Component Interfaces:
/// Components must be seen as data holders. In Svelto.ECS components are always interfaces declaring
/// Setters and Getters of Value Types coming from the Objects they wrap
/// - Implementors:
/// The components interfaces must be implemented through Implementors and the implementors are the
/// Objects you need to wrap.
/// - EntityDescriptors:
/// Gives a way to formalise your Entity, it also defines the EntityStructs and EntityViewStructs that must
/// be generated once the Entity is built
/// </summary>
void SetupEngines()
{
//The Engines Root is the core of Svelto.ECS. You shouldn't inject the EngineRoot,
//therefore the composition root must hold a reference or it will be GCed.
//the UnitySumbmissionEntityViewScheduler is the scheduler that is used by the EnginesRoot to know
//when to submit the entities. Custom ones can be created for special cases.
_unityEntitySubmissionScheduler = new UnityEntitySubmissionScheduler();
_enginesRoot = new EnginesRoot(_unityEntitySubmissionScheduler);
//The EntityFactory can be injected inside factories (or engine acting as factories) to build new entities
//dynamically
_entityFactory = _enginesRoot.GenerateEntityFactory();
//The entity functions is a set of utility operations on Entities, including removing an entity. I couldn't
//find a better name so far.
var entityFunctions = _enginesRoot.GenerateEntityFunctions();
//Sequencers are the official way to guarantee order between engines, but may not be the best way for
//your product.
var playerDeathSequence = new PlayerDeathSequencer();
var enemyDeathSequence = new EnemyDeathSequencer();
//wrap non testable unity static classes, so that can be mocked if needed.
IRayCaster rayCaster = new RayCaster();
ITime time = new Time();
//Player related engines. ALL the dependencies must be solved at this point through constructor injection.
var playerShootingEngine = new PlayerGunShootingEngine(rayCaster, time);
var playerMovementEngine = new PlayerMovementEngine(rayCaster, time);
var playerAnimationEngine = new PlayerAnimationEngine();
var playerDeathEngine = new PlayerDeathEngine(playerDeathSequence, entityFunctions);
//Enemy related engines
var enemyAnimationEngine = new EnemyAnimationEngine(time, enemyDeathSequence, entityFunctions);
var enemyAttackEngine = new EnemyAttackEngine(time);
var enemyMovementEngine = new EnemyMovementEngine();
//GameObjectFactory allows to create GameObjects without using the Static method GameObject.Instantiate.
//While it seems a complication it's important to keep the engines testable and not coupled with hard
//dependencies
var gameObjectFactory = new GameObjectFactory();
//Factory is one of the few patterns that work very well with ECS. Its use is highly encouraged
var enemyFactory = new EnemyFactory(gameObjectFactory, _entityFactory);
var enemySpawnerEngine = new EnemySpawnerEngine(enemyFactory, entityFunctions);
var enemyDeathEngine = new EnemyDeathEngine(entityFunctions, enemyDeathSequence);
//hud and sound engines
var hudEngine = new HUDEngine(time);
var damageSoundEngine = new DamageSoundEngine();
var scoreEngine = new ScoreEngine();
//The ISequencer implementation is very simple, but allows to perform
//complex concatenation including loops and conditional branching.
//These two sequencers are a real stretch and are shown only for explanatory purposes.
//Please do not see sequencers as a way to dispatch or broadcast events, they are meant only and exclusively
//to guarantee the order of execution of the involved engines.
//For this reason the use of sequencers is and must be actually rare, as perfectly encapsulated engines
//do not need to be executed in specific order.
//a Sequencer can:
//- ensure the order of execution through one step only (one step executes in order several engines)
//- ensure the order of execution through several steps. Each engine inside each step has the responsibility
//to trigger the next step through the use of the Next() function
//- create paths with branches and loop using the Condition parameter.
playerDeathSequence.SetSequence(playerDeathEngine, playerMovementEngine, playerAnimationEngine,
enemyAnimationEngine, damageSoundEngine, hudEngine);
enemyDeathSequence.SetSequence(enemyDeathEngine, scoreEngine, damageSoundEngine, enemyAnimationEngine,
enemySpawnerEngine);
//All the logic of the game must lie inside engines
//Player engines
_enginesRoot.AddEngine(playerMovementEngine);
_enginesRoot.AddEngine(playerAnimationEngine);
_enginesRoot.AddEngine(playerShootingEngine);
_enginesRoot.AddEngine(new PlayerInputEngine());
_enginesRoot.AddEngine(new PlayerGunShootingFXsEngine());
_enginesRoot.AddEngine(playerDeathEngine);
_enginesRoot.AddEngine(new PlayerSpawnerEngine(gameObjectFactory, _entityFactory));
//enemy engines
_enginesRoot.AddEngine(enemySpawnerEngine);
_enginesRoot.AddEngine(enemyAttackEngine);
_enginesRoot.AddEngine(enemyMovementEngine);
_enginesRoot.AddEngine(enemyAnimationEngine);
_enginesRoot.AddEngine(enemyDeathEngine);
//other engines
_enginesRoot.AddEngine(new ApplyingDamageToTargetsEngine());
_enginesRoot.AddEngine(new CameraFollowTargetEngine(time));
_enginesRoot.AddEngine(new CharactersDeathEngine());
_enginesRoot.AddEngine(damageSoundEngine);
_enginesRoot.AddEngine(hudEngine);
_enginesRoot.AddEngine(scoreEngine);
}
