diff --git a/.jazzy.yaml b/.jazzy.yaml index 7398070..99267c5 100644 --- a/.jazzy.yaml +++ b/.jazzy.yaml @@ -1,23 +1,22 @@ #author_url: URL -#copyright: Copyright © 2017 Christian Treffs. All rights reserved. #docset_icon: /path/to/icon.png -#exclude: [Packages] +#exclude: [Tests] #theme: fullwidth -author: Christian Treffs +author: "Christian Treffs" clean: true -documentation: docs/*.md -github_url: https://github.com/ctreffs/FirebladeECS/ +documentation: "docs/*.md" +github_url: "https://github.com/ctreffs/FirebladeECS/" hide_documentation_coverage: false min_acl: "public" -module: FirebladeECS -module_version: 0.1.0 -output: docs -readme: README.md +module: "FirebladeECS" +module_version: 0.4.0 +output: "docs" +readme: "README.md" skip_undocumented: false #source_directory: Sources -swift_version: "4.0.3" -theme: apple -xcodebuild_arguments: [-project, FirebladeECS.xcodeproj, -target, FirebladeECS, LIBRARY_SEARCH_PATHS=.build/debug] +swift_version: "4.2" +theme: fullwidth +#xcodebuild_arguments: [-project, FirebladeECS.xcodeproj, -target, FirebladeECS, LIBRARY_SEARCH_PATHS=.build/debug] #custom_categories: #- name: Guides # children: diff --git a/Gemfile b/Gemfile index d067005..124c022 100644 --- a/Gemfile +++ b/Gemfile @@ -7,3 +7,6 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" } # gem "rails" gem "xcodeproj", "~> 1.5" + +# Added at 2018-06-07 11:21:22 -0700 by treffs: +gem "jazzy", "~> 0.9.3" diff --git a/Gemfile.lock b/Gemfile.lock index 94523e0..ef21516 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -2,10 +2,89 @@ GEM remote: https://rubygems.org/ specs: CFPropertyList (3.0.0) + activesupport (4.2.10) + i18n (~> 0.7) + minitest (~> 5.1) + thread_safe (~> 0.3, >= 0.3.4) + tzinfo (~> 1.1) atomos (0.1.2) claide (1.0.2) + cocoapods (1.5.3) + activesupport (>= 4.0.2, < 5) + claide (>= 1.0.2, < 2.0) + cocoapods-core (= 1.5.3) + cocoapods-deintegrate (>= 1.0.2, < 2.0) + cocoapods-downloader (>= 1.2.0, < 2.0) + cocoapods-plugins (>= 1.0.0, < 2.0) + cocoapods-search (>= 1.0.0, < 2.0) + cocoapods-stats (>= 1.0.0, < 2.0) + cocoapods-trunk (>= 1.3.0, < 2.0) + cocoapods-try (>= 1.1.0, < 2.0) + colored2 (~> 3.1) + escape (~> 0.0.4) + fourflusher (~> 2.0.1) + gh_inspector (~> 1.0) + molinillo (~> 0.6.5) + nap (~> 1.0) + ruby-macho (~> 1.1) + xcodeproj (>= 1.5.7, < 2.0) + cocoapods-core (1.5.3) + activesupport (>= 4.0.2, < 6) + fuzzy_match (~> 2.0.4) + nap (~> 1.0) + cocoapods-deintegrate (1.0.2) + cocoapods-downloader (1.2.1) + cocoapods-plugins (1.0.0) + nap + cocoapods-search (1.0.0) + cocoapods-stats (1.0.0) + cocoapods-trunk (1.3.0) + nap (>= 0.8, < 2.0) + netrc (~> 0.11) + cocoapods-try (1.1.0) colored2 (3.1.2) + concurrent-ruby (1.0.5) + escape (0.0.4) + ffi (1.9.25) + fourflusher (2.0.1) + fuzzy_match (2.0.4) + gh_inspector (1.1.3) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jazzy (0.9.3) + cocoapods (~> 1.0) + mustache (~> 0.99) + open4 + redcarpet (~> 3.2) + rouge (>= 2.0.6, < 4.0) + sass (~> 3.4) + sqlite3 (~> 1.3) + xcinvoke (~> 0.3.0) + liferaft (0.0.6) + minitest (5.11.3) + molinillo (0.6.5) + mustache (0.99.8) nanaimo (0.2.5) + nap (1.1.0) + netrc (0.11.0) + open4 (1.3.4) + rb-fsevent (0.10.3) + rb-inotify (0.9.10) + ffi (>= 0.5.0, < 2) + redcarpet (3.4.0) + rouge (3.1.1) + ruby-macho (1.2.0) + sass (3.5.6) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sqlite3 (1.3.13) + thread_safe (0.3.6) + tzinfo (1.2.5) + thread_safe (~> 0.1) + xcinvoke (0.3.0) + liferaft (~> 0.0.6) xcodeproj (1.5.9) CFPropertyList (>= 2.3.3, < 4.0) atomos (~> 0.1.2) @@ -17,6 +96,7 @@ PLATFORMS ruby DEPENDENCIES + jazzy (~> 0.9.3) xcodeproj (~> 1.5) BUNDLED WITH diff --git a/README.md b/README.md index 1932782..bbfdde4 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,158 @@ -# Fireblade +# Fireblade ECS (Entity-Component-System) +[![version 0.4.0](https://img.shields.io/badge/version-0.4.0-brightgreen.svg)](releases/tag/v0.4.0) +[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE) +[![swift version](https://img.shields.io/badge/swift-4-brightgreen.svg)](#) +[![platforms](https://img.shields.io/badge/platform-macOS%20|%20iOS%20|%20linux-brightgreen.svg)](#) -A description of this package. +This is a **dependency free**, **lightweight**, **fast** and **easy to use** [Entity-Component-System](https://en.wikipedia.org/wiki/Entity–component–system) implementation in Swift. It is developed and maintained as part of the [Fireblade Game Engine project](https://github.com/fireblade-engine). + +See the [Fireblade ECS Demo App](https://github.com/fireblade-engine/ecs-demo) 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 + +* [Swift Package Manager (SPM)](https://github.com/apple/swift-package-manager) +* [Swiftlint](https://github.com/realm/SwiftLint) for linting - (optional) +* [Jazzy](https://github.com/realm/jazzy) for documentation - (optional) + +### Installing + +Fireblade ECS is available for all platforms that support [Swift 4](https://swift.org/) and the [Swift Package Manager (SPM)](https://github.com/apple/swift-package-manager). + +Extend the following lines in your `Package.swift` file or use it to create a new project. + +```swift +// swift-tools-version:4.0 + +import PackageDescription + +let package = Package( + name: "YourPackageName", + dependencies: [ + .package(url: "https://github.com/fireblade-engine/ecs.git", from: "0.4.0") + ], + targets: [ + .target( + name: "YourTargetName", + dependencies: ["FirebladeECS"]) + ] +) + +``` + +## Code Example + + + +A core element in the Fireblade-ECS is the [Nexus](https://en.wiktionary.org/wiki/nexus#Noun). +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 + +```swift +let nexus = Nexus() +``` + +then create entities by letting the `Nexus` generate them. + +```swift +let myEntity = nexus.create(entity: "myEntity") +``` + +You can define `Components` like this + +```swift +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 + +```swift +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 + +```swift +let family = nexus.family(requiresAll: [Movement.self, PlayerInput.self], + excludesAll: [Texture.self], + needsAtLeastOne: [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. + +```swift +class PlayerMovementSystem { + let family = nexus.family(requiresAll: [Movement.self, PlayerInput.self], + excludesAll: [Texture.self], + needsAtLeastOne: [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 + ... + + } + } +} +``` +See the [Fireblade ECS Demo App](https://github.com/fireblade-engine/ecs-demo) to get started. + + + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](tags). + +## Authors + +* [Christian Treffs](https://github.com/ctreffs) - *Initial work* +* [Manuel Weidmann](https://github.com/vyo) + +See also the list of [contributors](project/contributors) who participated in this project. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details + +## Acknowledgments + +Inspired by +- [Ashley](https://github.com/libgdx/ashley) +- [Entitas](https://github.com/sschmid/Entitas-CSharp) +- [EntitasKit](https://github.com/mzaks/EntitasKit)