Initial commit of the Package folder as a separate repository

To publish on GitHub separately from the master project folder (also to remove any potentially embarrassing commits as this is my first public open-source project 💧^^)

Author: ShinryakuTako

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+/.build
+/Packages
+/*.xcodeproj

Documentation/Coding Conventions & Design Decisions.md

@@ -0,0 +1,43 @@
+# OctopusKit Coding Conventions & Design Decisions
+
+[Developer Diary](#developer-diary)  
+[Comments Key](#comments-key)
+
+- Git workflow: [http://nvie.com/posts/a-successful-git-branching-model/](http://nvie.com/posts/a-successful-git-branching-model/)
+
+- OctopusKit types are prefixed with the word "Octopus" instead of "OK" because I liked it that way, and it saved me from a lot of refactoring when I had to change the name of the engine a few times.
+
+- Classes are marked `final` where possible to improve performance. If you need to subclass them in a specific project, you could create a copy of the class (or entire engine source) and modify it to suit your project. See: [Increasing Performance by Reducing Dynamic Dispatch](https://developer.apple.com/swift/blog/?id=27)
+
+- When checking a list of conditions in a single `if` or `guard`, check the condition that is the most likely to change each time, without which the operation will not continue, and the conditions that will most likely pass should be checked last, so that you save processing time by exiting early in the checklist instead of later.
+	> In some cases however, it may be best to check the most important condition first. :)
+
+- There are almost no `private` properties and methods in the OctopusKit API, so that you can observe almost everything at runtime, or customize in subclasses. Some may be read-only, however.
+
+- Sometimes a type may have both type methods and instance methods for the same operations, like the `CGFloat+OctopusKit` extension with `distance(between:and:)` and `distance(to:)?` It may usually be more natural to write `distance = CGPoint.distance(between: a, and: b)` than `distance = a.distance(to: b)`, but it wouldn't do to make that method available only on the type and not on instances, so OK provides both. However, to reduce duplication of code, the instance methods are the "primary" code (to improve performance by reducing extra calls, because calling these methods on an instance may be more "idiomatic") and the type methods call the instance versions.
+
+- `for each x in y` is cleaner and self-explanatory compared to `y.forEach { x in ... }` or `$0.z`
+
+- In subclasses, try to prefix properties with `super.` or `self.` if there might be any ambiguity at the use site about where the property is defined.
+    > TODO: example
+
+- Say "player" instead of "user" whenever referring to the person playing the game. (^ ^)
+
+## Developer Diary
+
+- Trying to implement Scene Editor support for components via `@GKInspectable` seems like a waste of effort, as the editor does not show inspectable properties from a component's superclass. 2018-04-18
+
+## Comments Key
+
+- ℹ️ / DESIGN: A design decision or note.
+- ⚠️ A warning about potential undesirable behavior, or a previous undesirable situation that was learned and avoided or fixed. 
+- 💬 General commentary/observations.
+- PERFORMANCE: Related to speed/efficiency/optimization.
+
+----
+
+OctopusKit © 2018 InvadingOctopus.com, github.com/invadingoctopus/octopuskit  
+[Apache License 2.0][license]
+
+[license]: https://www.apache.org/licenses/LICENSE-2.0.html
+

Documentation/TODO & Roadmap.md

@@ -0,0 +1,53 @@
+# OctopusKit Roadmap
+
+> If you'd like to help with the development of the OK project, these are some of the areas that need to be implemented.
+
+1. [Major Missing Features](#major-missing-features)
+2. [To Do](#to-do)
+3. [To Decide](#to-decide)
+
+## Major Missing Features
+
+*More-or-less in order of priority/necessity:*
+
+- Full macOS and tvOS support (currently in a preliminary state as of 2018-06-08.)
+- Components for mouse, keyboard, gamepad/joystick and Siri Remote input.
+- Asset/resource loading system.
+- Saving and loading game/scene/entity/component states via `Codable`.
+- Support for describing scenes/entities/components in HTML/XML/JSON or a  similar format.
+- Networking components.
+- SceneKit support in 2D scenes, and 3D components.
+- Custom Scene Editor & Live Previewer?
+
+## To Do
+
+- Tests.
+- Improve coding conventions.
+- Write tutorials for common tasks.
+- Clarify `super` chaining where applicable – when an overridden method in a subclass *needs* to call the superclass method for the functionality to work correctly – and enforce it when it becomes possible through language support in a future version of Swift.
+- Eliminate the possibility of a `SKNode.physicsBody` being added to a scene more than once.
+- Internationalization/Localization
+- Implement configurable Xcode templates (single files with multiple variations based on options during file creation, e.g. single-state scenes vs. multi-state scenes.) 
+- Add `Codable` support for components and their `init?(coder aDecoder: NSCoder)` where applicable.
+- GitHub Wiki?
+
+### Performance Optimizations
+
+- Replace `Array` with `ContiguousArray` where applicable.
+
+## To Decide
+
+- Shorten the prefix for engine types from "Octopus" to "OK"?
+- Use variadic parameters (`...`) instead of arrays in certain places, like `GKEntity.addComponent(_:)`?
+- Change `public` access to `open` or `internal`?
+- Write standalone documentation for every API unit? (Currently, source comments are the primary API documentation.)
+- Write documentation and tutorials for absolute beginners? i.e. people who have no experience with Xcode or Swift?
+
+----
+
+OctopusKit © 2018 InvadingOctopus.com, github.com/invadingoctopus/octopuskit  
+[Apache License 2.0][license]
+
+[license]: https://www.apache.org/licenses/LICENSE-2.0.html
+
+

Documentation/Tips & Troubleshooting.md

@@ -0,0 +1,82 @@
+# OctopusKit Tips & Troubleshooting
+
+1. [Common Mistakes](#common-mistakes)
+2. [Best Practices](#best-practices)
+3. [Tips & Tricks](#tips-&-tricks)
+4. [Pitfalls & Gotchas](#pitfalls-&-gotchas)
+5. [Conditional Compilation Flags & Debugging Aids](#conditional-compilation-flags-&-debugging-aids)
+
+## Common Mistakes
+
+#### Components not having any effect? 
+- If the component has an `update(deltaTime:)` method, make sure it's registered with a Component System, or is manually updated during the scene's `update(_:)` method, and *is only updated* ***once!*** [TODO: make this automatic]
+
+- Does the entity have all the components that the non-functioning component depends on? A component's dependencies must be added to the entity before the component that depends on them. [TODO: make this automatic]
+
+- Check the log.
+
+#### Components having *too* much effect? 
+- Make sure that a component is updated (if applicable) only once per frame.
+
+- Also make sure that a component *system* is added to a scene only once!
+
+#### Gesture recognizer components not working? 
+- Check their properties for the minimum and maximum number of touches.
+
+#### Scene, subscene or node not receiving input events?
+- Check its `isUserInteractionEnabled` property.
+    
+## Best Practices
+
+- Remember to search the entire source code for `BUG:`, `APPLEBUG:`, `FIXME:` etc. comments for any outstanding bugs and their temporary workarounds, if any.
+
+- In most cases, try to access the object hierarchy from the "bottom up" instead of "top down."
+
+	> TODO: Example
+
+## Tips & Tricks
+
+- You can have multiple "games" within a single project, by using multiple `OctopusGameController`s (each with its own set of `OctopusGameState`s and associated scenes, etc.) and programmatically  choosing between them in `OctopusAppDelegate.configureOctopusEngine()`.
+
+- TODO: Tip for sharing "global" data via `RelayComponent`s.
+    
+## Pitfalls & Gotchas
+
+- Many methods MUST be overridden in a subclass and/or chained to the superclass implementation, by calling `super.method()`. Some methods should call `super` at different points (i.e. beginning or end) in the subclass' implementation. Unfortunately, there is no language-level support for enforcing that, so your best bet is to read the source and comments of the method you're overriding.
+    > 💡 When in doubt, always call `super`, and call it at the top of your overriding method. [TODO: make this chaining automatic/enforced when/if Swift supports it]
+    
+- Components should try to perform their logic only during the `didAdd(...)`, `willRemove(...)`, and `update(deltaTime:)` methods. If a component's behavior must be modified outside of those methods, use flags that are then acted upon in the component's update method.  
+This ensures that a component does not affect anything outside of a frame update and can be reliably paused/unpaused.  
+    > Note that this does not mean that a component should not _define_ any other methods at all.  
+    > TODO: Example
+
+    - Components that respond to asynchronous events, such as a component that moves a node based on input from a gesture recognizer, like `PanControlledRepositioningComponent`, or networking components, MUST perform their function inside their `update(deltaTime:)` method, and just use the event-handling action method to mark a flag to denote that an event was received.  
+This prevents the component from being active outside the frame-update cycle, or when it's [temporarily] removed from the entity or the scene's systems.
+
+    - A SpriteKit scene processes touch and other input events **outside** of its `update(_:)` method; when those event handlers update input-processing components, those components will (should) only be able to act on the input data during the scene's `update(_:)` method.
+
+- OctopusKit components may sometimes cause some "friction" against the SpriteKit API.  
+  e.g.: when adding a `SpriteKitComponent` and a `PhysicsComponent` to an entity; the SpriteKit node may have its own `physicsBody` and the `PhysicsComponent` may have a different `physicsBody`.
+    - As a general rule, adding a component to an entity assumes that the component adds its encapsulated functionality to that entity, replacing any identical functionality that already exists. 
+    
+        > e.g.: If you add a "blank" component, e.g. a `PhysicsComponent` with a `nil` `physicsBody`, then the component attempts to "adopt" any existing properties of the underlying SpriteKit object.  
+        In this example, the blank `PhysicsComponent` will set its property to the `physicsBody`, if any, of the `SpriteKitComponent` node. After that, other components should access the node's physics properties through the `PhysicsComponent` instead of the node's `physicsBody` property.
+
+- Entities and components may not always be the answer to everything. *Sometimes* good old classes and structs may be the better solution. (^ - ^")
+
+- An entity can/should only have one component of a specific type (not counting generic variants.)  
+If an entity needs multiple components of the same type but with different parameters, consider using a "master" component that holds a collection of regular classes/struct.
+    > e.g.: a *ShipEntity* with a *WeaponsSystemComponent* that holds an array of *Gun* classes/structs, to represent multiple guns where each gun is mounted on a different side of the ship.
+    
+## Conditional Compilation Flags & Debugging Aids
+
+> TODO: Instructions on where to enter these in Xcode
+
+* `LOGINPUT` - Logs all input events and related information.
+
+----
+
+OctopusKit © 2018 InvadingOctopus.com, github.com/invadingoctopus/octopuskit  
+[Apache License 2.0][license]
+
+[license]: https://www.apache.org/licenses/LICENSE-2.0.html