Skip to content
C# Entity-Component-System library.
C#
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Guts
.hgignore
readme.md

readme.md

Overview

Guts is a small and simple entity-component system for C#. Entities and components are pooled objects. It can be used in a way that does not generate any garbage, which may be useful on certain platforms (e.g. Xbox 360).

While entities have a unique ID, they are class objects allocated during initialization of a GutsRoot instance. Care must be taken when keeping references to entities outside of EntitySystems. If an entity is released, it will be returned to the entity pool during the next update. Any references to it would refer to the recycled entity. Keeping logic inside of EntitySystems and accessing components through nodes is a good way to prevent references to expired entities.

http://en.wikipedia.org/wiki/Entity_component_system

Entity - Entities are simple containers of components. The components define the aspects of the entity and systems perform logic on components they have an interest in.

Component - You can add components to entities to extend them. Only one component of each type can be added.

System - Performs actions on entities that have the components required of the system. When a system is notified by GutsRoot that a component was added, it checks if the entity contains all the components it requires. If the entity does have the requisite components, the system will create a node. Each update, the system can iterate through the list of accepted entities and perform logic on them. Other methods can access the node list and perform operations as needed.

GutsRoot - A GutsRoot instance contains entities and their components, as well as entity systems and their nodes.

Usage

GutsRoot gutsRoot = new GutsRoot(100);

Register Component Types (Optional)

Normally a pool is created when a component of a specific type is aquired for the first time. When a pool is created, all of the components (equal to the number of max entities in GutsRoot) are allocated. Registering a component type ahead of time will cause the pool to be created immediately and might be useful to avoid allocations later.

gutsRoot.RegisterComponentType<SampleComponent>();

Entity Systems

BeforeNodeReleased

Derived entity systems should override BeforeNodeReleased if any references to a node need to be removed before the node is released. For example: any other nodes in the system that are holding a reference to the releasing node should remove that reference.

Entity systems expose the INodeEvents interface, which allows subscription to node creation and removal events. Toolsets and editors needing access to an entity system can use these to monitor when entities are released and recycled back into the entity pool.

Sample

//  Create a new GutsRoot instance with the maximum number
//  of entities you will need.
GutsRoot gutsRoot = new GutsRoot(100);

//  When the first component of a type is acquired, a pool
//  will be created. You can create pools ahead of time if
//  you want to avoid creating them later.
gutsRoot.RegisterComponentType<SampleComponent>();

//  Initialize GutsRoot. This will allocate the entity pool.
gutsRoot.Initialize();

//  Create a new EntitySystem.
SampleSystem system = new SampleSystem(gutsRoot);

//  Acquire an entity from the pool.
Entity entity = gutsRoot.AcquireEntity();

//  Add a component to the entity.
entity.AddComponent<SampleComponent>();

//  AddComponent returns the recycled component it added.
//  You can also use GetComponent at any time, but if the Entity
//  does not contain a component of that type, GetComponent
//  will throw an exception. Check with HasComponent first.
if (entity.HasComponent<SampleComponent>())
{
	SampleComponent component = entity.GetComponent<SampleComponent>();

	//  Do whatever you need with the component.
	component.X = 0;
	component.Y = 3;
	component.FooList.Add(new Foo() { LifeTime = 5 });
}

bool quit = false;

//  In a game loop, you might have the number of elapsed seconds
//  since the last update available. In XNA this is available in
//  the GameTime class. For this example, an arbitrary value is used.
float elapsedSeconds = 0.016f;

while (quit == false)
{
	//  Update GutsRoot every frame. This will add new entities to
	//  systems and release entities marked for release.
	gutsRoot.Update();

	//  Update the entity system. This is only necessary if the
	//  system has implemented UpdateNode.
	system.Update(elapsedSeconds);
}
You can’t perform that action at this time.