Actors.unity
🚀Actors is a framework empowering developers to make better games faster on Unity.
Install / Use
/learn @PixeyeHQ/Actors.unityREADME
Actors is a framework empowering developers to make better games faster on Unity.
[Due our shifting from Unity, not actively supported]
⭐ Why Actors ?
The framework favors simplicity and doesn't try to "abstract away" Unity workflows bringing first-class support for combining ECS with classic Unity component system.
- Deterministic workflow.
- ECS with clean syntax and no codegen.
- ECS integration with Unity gameobjects via Actor components.
- Logic Layers.
- Object Pooling.
- Multiscene editing.
- Reactive variables.
- Fast coroutines working in any class.
- Update methods working in any class.
| How To Install - Projects - About - Changelog| :----------------------------------------------------------: |
📖 ECS Overview
🔖 Entities are containers for components. Entity ID is represented by ent structure.
💬 How to create an entity?
// Bare entity
ent e = Entity.Create();
Entities can hold information about unity objects as well!
// New entity with a new GO ( GameObject ).
// The GO prefab will be taken from the Resources folder by string ID.
ent e = Entity.Create("Obj Fluffy Unicorn");
// Access to the transform of Obj Fluffy Unicorn gameobject.
e.transform.position = new Vector3(0,0,0) ;
You can pool gameobject by adding true variable in the end of the method.
public GameObject prefabFluffyUnicorn;
// New entity with a new GO ( GameObject ).
// The GO will be created from the provided prefab.
// The GO will be pooled.
ent e = Entity.Create(prefabFluffyUnicorn, true);
// Access to the transform of Obj Fluffy Unicorn gameobject.
e.transform.position = new Vector3(0,0,0) ;
// New entity with a new GO ( GameObject ).
// The GO prefab will be taken from the Resources folder by string ID.
// The GO will be pooled.
ent e = Entity.Create("Obj Fluffy Unicorn", true);
// Access to the transform of Obj Fluffy Unicorn gameobject.
e.transform.position = new Vector3(0,0,0) ;
Entity API is layer specific. You will find more info about layers below. If you want to create an entity on a different layer you need to use slightly different approach:
// we use LayerApp API to create entity inside of the LayerApp.
ent e = LayerApp.Entity.Create("Obj Fluffy Unicorn", true);
// Access to the transform of Obj Fluffy Unicorn gameobject.
e.transform.position = new Vector3(0,0,0) ;
🔖 Components are containers for data.
sealed class ComponentAlpaca
{
public int fluffiness;
}
💡 For comfortable workflow a component is created together with special helper class. While you can live without that helper all examples are provided with use of it.
💬 How to add components?
There are several ways to add components depending on the context of your code.
In case you want to setup your new entity use Set method. Use Set method only with newly created entities.
public void SomeMethod()
{
ent e = Entity.Create("Obj Bunny");
// Add components
var cCute = e.Set<ComponentCute>();
var cJumping = e.Set<ComponentJumping>();
var cConsumable = e.Set<ComponentConsumable>();
var cPoo = e.Set<ComponentCanPoo>();
// Component Cute
cCute.attractivness = float.PositiveInfinity;
// Component Jumping
cJumping.power = 100;
}
Use Get method when you unsure if entity has particular component. This method will check and add component if it doesn't exist.
public void SomeMethod()
{
// where e is some entity.
// Add components
var cCute = e.Get<ComponentCute>();
var cJumping = e.Get<ComponentJumping>();
var cConsumable = e.Get<ComponentConsumable>();
var cPoo = e.Get<ComponentCanPoo>();
// Component Cute
cCute.attractivness = float.PositiveInfinity;
// Component Jumping
cJumping.power = 100;
}
🔖 Systems in Actors are called Processors. Processors execute game logic with groups. Groups are containers for entities filtered by components mask.
public class ProcessorAlpaca : Processor, ITick
{
// All entities that have ComponentAlpaca will be in this group.
readonly Group<ComponentAlpaca> alpacas = default;
public void Tick(float dt)
{
// iterate through entities in the group
foreach (var alpaca in alpacas)
{
// retrieve a component
var cAlpaca = alpaca.ComponentAlpaca();
}
}
}
🔖 Layers are containers for your processors and entry point of the scene. You can think about layers as ECS worlds, but they are much more then that. In fact, everything in Actors controlled by layers. Every unity scene must hold no more than one layer.
using Pixeye.Actors;
public class LayerGame : Layer<LayerGame>
{
protected override void Setup()
{
// the order affects on execution
Add<ProcessorAlpaca>();
Add<ProcessorDamage>();
Add<ProcessorAnimations>();
}
}
📖 Scenes Overview
The framework favors multiscene architecture in Unity. The concept is simple: you have one main scene that can be only changed for another scene and subscenes that can be added/removed when needed. Normally scene will have a logic layer of the framework. This will be explained further.
💡 The main (or it's also called active in Unity) scene name font style is bold inside the Hierarchy window.
- Scene API
- SceneMain: API for changing the main scene.
- SceneSub : API for adding/removing a subscenes.
public class ProcessorAlpaca : Processor, ITick
{
public void Tick(float dt)
{
// Example of how to change the main scene.
if (Input.GetKeyDown(KeyCode.Alpha1))
SceneMain.ChangeTo(1); // by index
if (Input.GetKeyDown(KeyCode.Alpha2))
SceneMain.ChangeTo("Scene Alpaca Fields"); // by name
// Example of how to work with subscenes.
if (Input.GetKeyDown(KeyCode.Alpha1))
{
SceneSub.Add("Alpaca Shop"); // by name
SceneSub.Add(2); // by index
}
if (Input.GetKeyDown(KeyCode.Alpha2))
{
SceneSub.Remove("Alpaca Shop"); // by name
SceneSub.Remove(2); // by index
}
}
}
💡 Don't forget to add scene in the build settings of your game.
Note that you can have only one copy of each scene. In case you try to add scene twice the framework will ignore the call.
📖 Layers Overview
As already said, layers are very important part of the framework. Each layer represents a unity scene and holds several important modules of the framework. When the layer is removed or changed everything that is inside of the layer will be cleaned up. Another important thing is that any actor or monocached components will start working only after initialization and setup of the layer. The concepts of actor and monocached will be discussed further.
-
Public Layer Modules
- Engine : Core module that controls all other updates.
- ECS : API for specific ECS stuff like events.
- Entity : API for creating new entities on the layer.
- Actor : API for creating new actors on the layer.
- Observer : Reactive observer for any variable.
- Time : API for custom timing on the layer.
- Obj : API for instantiating prefabs on the layer.
-
Private Layer Modules
- Pool : Module that controls GameObject pooling.
- Signals : Module that controls signals, a global event dispatcher.
- Routines : Module that controls routines, custom coroutines.
-
Who are aware of Layers?
- Processors : Created in the layer and get the reference of it.
- Monocached : Base monobehavior classes in the framework. They get the reference of a layer when initialized.
- Actors : Inherited from monocache class. They represent entity view.
📘 Obj
Obj is a module that controls gameobject instantiating. Entities and actors with prefabs are created through obj module.
💬 How to instantiate gameobjects?
🔖 From string: the pref
