Fireblade ECS (Entity-Component-System)

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.

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

• Swift Package Manager (SPM)
• Swiftlint for linting - (optional)
• Jazzy for documentation - (optional)

Installing

Fireblade ECS is available for all platforms that support Swift 4 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:4.0

import PackageDescription

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

Code Example

A 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 hold up to 4294967295 Entities at a time. You may use more than one Nexus.

Initialize a nexus with

let nexus = Nexus()

then create entities by letting the Nexus generate them.

let myEntity = nexus.create(entity: "myEntity")

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

myEntity.assign(Movement())

This ECS uses a grouping approach for entities with the same component types to optimize and ease up access to these. Entities with the same component types may be accessed via a so called 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], any: [Name.self])

These entities are cached in the nexus for efficient access and iteration. Iterate family members by calling .iterate on the family you want to iterate over. iterate provides a closure whose parameters start with the entity identifier (entityId) of the current entity, followed by the typesafe component instances of the current entity that you may provide in your desired order.

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

	func update() {
		family.iterate { (_, mov: Movement!, input: PlayerInput!, name: Name?) in
			
			// position & velocity for the current entity
			// we know that we will have this component so we force unwrap the component instance parameter already for easy handling inside the closure
			
			// 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
			...
			
			// optional name component that may or may not be part of the current entity
			_ = name?.name
			...
			
		}
	}
}

Versioning

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

Authors

• Christian Treffs - Initial work
• Manuel Weidmann

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

• Ashley
• Entitas
• EntitasKit