Swiftpack.co - Package - fireblade-engine/ecs

Fireblade ECS (Entity-Component System)

Build Status license swift version platforms platforms

This is a dependency free, lightweight, fast and easy to use Entity-Component System implementation in Swift. It is developed and maintained as part of the Fireblade Game Engine project.

See the Fireblade ECS Demo App to get started.

๐Ÿš€ Getting Started

These instructions will get you a copy of the project up and running on your local machine and provide a code example.

๐Ÿ“‹ Prerequisites

๐Ÿ’ป Installing

Fireblade ECS is available for all platforms that support Swift 5.0 and higher and the Swift Package Manager (SPM).

Extend the following lines in your Package.swift file or use it to create a new project.

// swift-tools-version:5.0

import PackageDescription

let package = Package(
    name: "YourPackageName",
    dependencies: [
        .package(url: "https://github.com/fireblade-engine/ecs.git", from: "0.10.0")
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: ["FirebladeECS"])
    ]
)

๐Ÿ“ Code Example

๐Ÿ›๏ธ Nexus

The core element in the Fireblade-ECS is the Nexus. It acts as a centralized way to store, access and manage entities and their components. A single Nexus may (theoretically) hold up to 4294967295 Entities at a time.
You may use more than one Nexus at a time.

Initialize a Nexus with

let nexus = Nexus()

๐Ÿ‘ค Entities

then create entities by letting the Nexus generate them.

let myEntity = nexus.createEntity()

You can define Components like this

class Movement: Component {
	var position: (x: Double, y: Double) = (0.0, 1.0)
	var velocity: Double = 0.1
}

and assign instances of them to an Entity with

let movement = Movement()
myEntity.assign(movement)

๐Ÿ‘ช Families

This ECS uses a grouping approach for entities with the same component types to optimize cache locality and ease up access to them.
Entities with the same component types may belong to one Family. A Family has entities as members and component types as family traits.

Create a family by calling .family with a set of traits on the nexus. A family that containts only entities with a Movement and PlayerInput component, but no Texture component is created by

let family = nexus.family(requiresAll: Movement.self, PlayerInput.self,
                          excludesAll: Texture.self)

These entities are cached in the nexus for efficient access and iteration. Families conform to the Sequence protocol so that members (components) may be iterated and accessed like any other sequence in Swift.
Access a familiy's components directly on the family instance. To get family entities and access components at the same time call family.entityAndComponents. If you are only interested in a family's entities call family.entities.

class PlayerMovementSystem {
	let family = nexus.family(requiresAll: Movement.self, PlayerInput.self,
                              excludesAll: Texture.self)

	func update() {
		family
			.forEach { (mov: Movement, input: PlayerInput) in
			
			// position & velocity component for the current entity
			
			// get properties
			_ = mov.position
			_ = mov.velocity
			
			// set properties
			mov.position.x = mov.position.x + 3.0
			...
			
			// current input command for the given entity
			_ = input.command
			...
			
		}
	}

	func update2() {
		family
			.entityAndComponents
			.forEach { (entity: Entity, mov: Movement, input: PlayerInput) in
			
			// the currenty entity instance
			_ = entity

			// position & velocity component for the current entity
			
			// get properties
			_ = mov.position
			_ = mov.velocity
			
			
		}
	}

	func update3() {
		family
			.entities
			.forEach { (entity: Entity) in
			
			// the currenty entity instance
			_ = entity
		}
	}
}

๐Ÿง‘ Singles

A Single on the other hand is a special kind of family that holds exactly one entity with exactly one component for the entire lifetime of the Nexus. This may come in handy if you have components that have a Singleton character. Single components must conform to the SingleComponent protocol and will not be available through regular family iteration.

final class GameState: SingleComponent {
    var quitGame: Bool = false
}
class GameLogicSystem {
    let gameState: Single<GameState>
    
    init(nexus: Nexus) {
        gameState = nexus.single(GameState.self)
    }
    
    func update() {
        // update your game sate here
        gameState.component.quitGame = true
        
        // entity access is provided as well
        _ = gameState.entity
    }
}

๐Ÿ‘ซ Relatives

This ECS implementation provides an integrated way of creating a directed acyclic graph (DAG) hierarchy of entities by forming parent-child relationships. Entities can become children of a parent entity. In family terms they become relatives. Families provide iteration over these relationships.
The entity hierachy implementation does not use an additional component therefore keeping the hierarchy intact over different component-families. This feature is especially useful for implenting a scene graph.

// create entities with 0 to n components
let parent: Entity = nexus.createEntity(with: Position(x: 1, y: 1), SomeOtherComponent(...))
let child: Entity  = nexus.createEntity(with: Position(x: 2, y: 2))
let child2: Entity = nexus.createEntity(with: Position(x: 3, y: 3), MySpecialComponent(...))

// create relationships between entities
parent.addChild(child)
child.addChild(child2)
// or remove them
// parent.removeChild(child)

// iterate over component families descending the graph
nexus.family(requires: Position.self)
     .descendRelatives(from: parent) // provide the start entity (aka root "node")
     .forEach { (parent: Position, child: Position) in
        // parent: the current parent component
        // child: the current child component
        
        // update your components hierarchically
        child.x += parent.x
        child.y += parent.y
     }

๐Ÿงช Demo

See the Fireblade ECS Demo App to get started.

๐Ÿท๏ธ Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

โœ๏ธ Authors

See also the list of contributors who participated in this project.

๐Ÿ” License

This project is licensed under the MIT License - see the LICENSE file for details

๐Ÿ™ Acknowledgments

Inspired by

Github

link
Stars: 16
Help us keep the lights on

Dependencies

Used By

Total: 1

Releases

0.10.0 - Oct 1, 2019

New

  • Introduce Relatives, a directed acyclic graph integration

Add

  • Gitlab-ci config
  • Makefile for convenience actions
  • Conform EntityIdentifier to Codable

Update

  • Swiftlint rules

Fix

  • Swiftlint warnings
  • Cleanups

0.9.1 - Aug 22, 2019

  • Add Linux to travis.ci

0.9.0 - Aug 21, 2019

  • rework family implementation
    • removed TypedFamily*
    • introduced: Family<Requires*<*>>
  • minor changes to NexusEventDelegate
  • optimisations
  • cleanups

0.8.0 - Aug 20, 2019

Optimisations

  • Entity creation: nexus.create(entity:) is now nexus.createEntity()
  • Drop per entity name (may be added as name component instead)
  • Family member update iteration
  • rework EntityIdentifier
  • rework ComponentIdentifier
  • nexus storage

Cleanups

  • nexus event delegate handling
  • remove unnecessary typealiases

0.7.0 - May 21, 2019

  • Swift 5
  • Fix CI pipeline
  • Cleanups