Nexus

Nexus

public final class Nexus

Inheritance

CustomDebugStringConvertible

Initializers

init()

public convenience init()

Properties

numComponents

var numComponents: Int

numEntities

Number of entities in nexus.

var numEntities: Int

numFamilies

var numFamilies: Int

entityIdGenerator

The entity identifier generator responsible for providing unique ids for entities during runtime.

var entityIdGenerator: EntityIdentifierGenerator

Provide a custom implementation prior to entity creation. Defaults to DefaultEntityIdGenerator.

codingStrategy

The coding strategy used to encode/decode entities from/into families.

var codingStrategy: CodingStrategy

Provide a custom implementation prior to encoding/decoding. Defaults to DefaultCodingStrategy.

delegate

var delegate: NexusEventDelegate?

debugDescription

var debugDescription: String

Methods

family(requires:excludesAll:)

Create a family of entities (aka members) having 1 required components.

public func family<Comp1>(requires comp1: Comp1.Type, excludesAll excludedComponents: Component.Type) -> Family1<Comp1> where Comp1: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 1 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requires: Comp1.self)
// iterate each entity's components
family.forEach { (comp1) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 1 required components each.

family(requiresAll:_:excludesAll:)

Create a family of entities (aka members) having 2 required components.

public func family<Comp1, Comp2>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, excludesAll excludedComponents: Component.Type) -> Family2<Comp1, Comp2> where Comp1: Component, Comp2: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 2 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self)
// iterate each entity's components
family.forEach { (comp1, comp2) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 2 required components each.

family(requiresAll:_:_:excludesAll:)

Create a family of entities (aka members) having 3 required components.

public func family<Comp1, Comp2, Comp3>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, _ comp3: Comp3.Type, excludesAll excludedComponents: Component.Type) -> Family3<Comp1, Comp2, Comp3> where Comp1: Component, Comp2: Component, Comp3: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 3 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self, Comp3.self)
// iterate each entity's components
family.forEach { (comp1, comp2, comp3) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• comp3: Component type 3 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 3 required components each.

family(requiresAll:_:_:_:excludesAll:)

Create a family of entities (aka members) having 4 required components.

public func family<Comp1, Comp2, Comp3, Comp4>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, _ comp3: Comp3.Type, _ comp4: Comp4.Type, excludesAll excludedComponents: Component.Type) -> Family4<Comp1, Comp2, Comp3, Comp4> where Comp1: Component, Comp2: Component, Comp3: Component, Comp4: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 4 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self, Comp3.self, Comp4.self)
// iterate each entity's components
family.forEach { (comp1, comp2, comp3, comp4) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• comp3: Component type 3 required by members of this family.
• comp4: Component type 4 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 4 required components each.

family(requiresAll:_:_:_:_:excludesAll:)

Create a family of entities (aka members) having 5 required components.

public func family<Comp1, Comp2, Comp3, Comp4, Comp5>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, _ comp3: Comp3.Type, _ comp4: Comp4.Type, _ comp5: Comp5.Type, excludesAll excludedComponents: Component.Type) -> Family5<Comp1, Comp2, Comp3, Comp4, Comp5> where Comp1: Component, Comp2: Component, Comp3: Component, Comp4: Component, Comp5: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 5 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self, Comp3.self, Comp4.self, Comp5.self)
// iterate each entity's components
family.forEach { (comp1, comp2, comp3, comp4, comp5) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• comp3: Component type 3 required by members of this family.
• comp4: Component type 4 required by members of this family.
• comp5: Component type 5 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 5 required components each.

family(requiresAll:_:_:_:_:_:excludesAll:)

Create a family of entities (aka members) having 6 required components.

public func family<Comp1, Comp2, Comp3, Comp4, Comp5, Comp6>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, _ comp3: Comp3.Type, _ comp4: Comp4.Type, _ comp5: Comp5.Type, _ comp6: Comp6.Type, excludesAll excludedComponents: Component.Type) -> Family6<Comp1, Comp2, Comp3, Comp4, Comp5, Comp6> where Comp1: Component, Comp2: Component, Comp3: Component, Comp4: Component, Comp5: Component, Comp6: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 6 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self, Comp3.self, Comp4.self, Comp5.self, Comp6.self)
// iterate each entity's components
family.forEach { (comp1, comp2, comp3, comp4, comp5, comp6) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• comp3: Component type 3 required by members of this family.
• comp4: Component type 4 required by members of this family.
• comp5: Component type 5 required by members of this family.
• comp6: Component type 6 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 6 required components each.

family(requiresAll:_:_:_:_:_:_:excludesAll:)

Create a family of entities (aka members) having 7 required components.

public func family<Comp1, Comp2, Comp3, Comp4, Comp5, Comp6, Comp7>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, _ comp3: Comp3.Type, _ comp4: Comp4.Type, _ comp5: Comp5.Type, _ comp6: Comp6.Type, _ comp7: Comp7.Type, excludesAll excludedComponents: Component.Type) -> Family7<Comp1, Comp2, Comp3, Comp4, Comp5, Comp6, Comp7> where Comp1: Component, Comp2: Component, Comp3: Component, Comp4: Component, Comp5: Component, Comp6: Component, Comp7: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 7 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self, Comp3.self, Comp4.self, Comp5.self, Comp6.self, Comp7.self)
// iterate each entity's components
family.forEach { (comp1, comp2, comp3, comp4, comp5, comp6, comp7) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• comp3: Component type 3 required by members of this family.
• comp4: Component type 4 required by members of this family.
• comp5: Component type 5 required by members of this family.
• comp6: Component type 6 required by members of this family.
• comp7: Component type 7 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 7 required components each.

family(requiresAll:_:_:_:_:_:_:_:excludesAll:)

Create a family of entities (aka members) having 8 required components.

public func family<Comp1, Comp2, Comp3, Comp4, Comp5, Comp6, Comp7, Comp8>(requiresAll comp1: Comp1.Type, _ comp2: Comp2.Type, _ comp3: Comp3.Type, _ comp4: Comp4.Type, _ comp5: Comp5.Type, _ comp6: Comp6.Type, _ comp7: Comp7.Type, _ comp8: Comp8.Type, excludesAll excludedComponents: Component.Type) -> Family8<Comp1, Comp2, Comp3, Comp4, Comp5, Comp6, Comp7, Comp8> where Comp1: Component, Comp2: Component, Comp3: Component, Comp4: Component, Comp5: Component, Comp6: Component, Comp7: Component, Comp8: Component

A family is a collection of entities with uniform component types per entity. Entities that are be part of this family will have at least the 8 required components, but may have more components assigned.

A family is just a view on (component) data, creating them is cheap. Use them to iterate efficiently over entities with the same components assigned. Families with the same requirements provide a view on the same collection of entities (aka members). A family conforms to the LazySequenceProtocol and therefore can be accessed like any other (lazy) sequence.

General usage

let family = nexus.family(requiresAll: Comp1.self, Comp2.self, Comp3.self, Comp4.self, Comp5.self, Comp6.self, Comp7.self, Comp8.self)
// iterate each entity's components
family.forEach { (comp1, comp2, comp3, comp4, comp5, comp6, comp7, comp8) in
  ...
}

Caveats

• Component types must be unique per family

• Component type order is arbitrary

Parameters

• comp1: Component type 1 required by members of this family.
• comp2: Component type 2 required by members of this family.
• comp3: Component type 3 required by members of this family.
• comp4: Component type 4 required by members of this family.
• comp5: Component type 5 required by members of this family.
• comp6: Component type 6 required by members of this family.
• comp7: Component type 7 required by members of this family.
• comp8: Component type 8 required by members of this family.
• excludedComponents: All component types that must not be assigned to an entity in this family.

Returns

The family of entities having 8 required components each.

has(componentId:entityId:)

public final func has(componentId: ComponentIdentifier, entityId: EntityIdentifier) -> Bool

count(components:)

public final func count(components entityId: EntityIdentifier) -> Int

assign(component:to:)

@discardableResult public final func assign(component: Component, to entity: Entity) -> Bool

assign(component:to:)

@discardableResult public final func assign<C>(component: C, to entity: Entity) -> Bool where C: Component

assign(components:to:)

@discardableResult public final func assign<C>(components: C, to entity: Entity) -> Bool where C: Collection, C.Element == Component

get(safe:for:)

@inlinable public final func get(safe componentId: ComponentIdentifier, for entityId: EntityIdentifier) -> Component?

get(unsafe:for:)

@inlinable public final func get(unsafe componentId: ComponentIdentifier, for entityId: EntityIdentifier) -> Component

get(safe:for:)

@inlinable public final func get<C>(safe componentId: ComponentIdentifier, for entityId: EntityIdentifier) -> C? where C: Component

get(safe:)

@inlinable public final func get<C>(safe entityId: EntityIdentifier) -> C? where C: Component

get(unsafe:)

@inlinable public final func get<C>(unsafe entityId: EntityIdentifier) -> C where C: Component

get(components:)

@inlinable public final func get(components entityId: EntityIdentifier) -> Set<ComponentIdentifier>?

remove(component:from:)

@discardableResult public final func remove(component componentId: ComponentIdentifier, from entityId: EntityIdentifier) -> Bool

removeAll(components:)

@discardableResult public final func removeAll(components entityId: EntityIdentifier) -> Bool

createEntity(using:)

Create an entity assigning one component.

@discardableResult public func createEntity(using builder: () -> Component) -> Entity

Usage:

let newEntity = nexus.createEntity {
   Position(x: 1, y: 2)
}

Parameters

• builder: The component builder.

Returns

The newly created entity with the provided component assigned.

createEntity(using:)

Create an entity assigning multiple components.

@discardableResult public func createEntity(using builder: () -> [Component]) -> Entity

Usage:

let newEntity = nexus.createEntity {
   Position(x: 1, y: 2)
   Name(name: "Some name")
}

Parameters

• builder: The component builder.

Returns

The newly created entity with the provided components assigned.

createEntities(count:using:)

Create multiple entities assigning one component each.

@discardableResult public func createEntities(count: Int, using builder: (ComponentsBuilder.Context) -> Component) -> [Entity]

Usage:

let newEntities = nexus.createEntities(count: 100) { ctx in
   Velocity(a: Float(ctx.index))
}

Parameters

• count: The count of entities to create.
• builder: The component builder providing context.

Returns

The newly created entities with the provided component assigned.

createEntities(count:using:)

Create multiple entities assigning multiple components each.

@discardableResult public func createEntities(count: Int, using builder: (ComponentsBuilder.Context) -> [Component] = { _ in [] }) -> [Entity]

Usage:

let newEntities = nexus.createEntities(count: 100) { ctx in
   Position(x: ctx.index, y: ctx.index)
   Name(name: "\(ctx.index)")
}

Parameters

• count: The count of entities to create.
• builder: The component builder providing context.

Returns

The newly created entities with the provided components assigned.

createEntity()

@discardableResult public func createEntity() -> Entity

createEntity(with:)

@discardableResult public func createEntity(with components: Component) -> Entity

createEntity(with:)

@discardableResult public func createEntity<C>(with components: C) -> Entity where C: Collection, C.Element == Component

makeEntitiesIterator()

Creates an iterator over all entities in the nexus.

public func makeEntitiesIterator() -> EntitiesIterator

Entity order is not guaranteed to stay the same over iterations.

exists(entity:)

public func exists(entity entityId: EntityIdentifier) -> Bool

entity(from:)

public func entity(from entityId: EntityIdentifier) -> Entity

destroy(entity:)

@discardableResult public func destroy(entity: Entity) -> Bool

destroy(entityId:)

@discardableResult public func destroy(entityId: EntityIdentifier) -> Bool

canBecomeMember(_:in:)

public func canBecomeMember(_ entity: Entity, in traits: FamilyTraitSet) -> Bool

members(withFamilyTraits:)

public func members(withFamilyTraits traits: FamilyTraitSet) -> UnorderedSparseSet<EntityIdentifier, EntityIdentifier.Identifier>

isMember(_:in:)

public func isMember(_ entity: Entity, in family: FamilyTraitSet) -> Bool

isMember(_:in:)

public func isMember(_ entityId: EntityIdentifier, in family: FamilyTraitSet) -> Bool

isMember(entity:inFamilyWithTraits:)

public func isMember(entity entityId: EntityIdentifier, inFamilyWithTraits traits: FamilyTraitSet) -> Bool

clear()

public final func clear()

single(_:)

public func single<S>(_ component: S.Type) -> Single<S> where S: SingleComponent