OctopusKit Architecture

  1. Folder Organization
  2. Control Flow & Object Hierarchy
  3. Game Coordinator and Game States
  4. Scenes
  5. User Interface
  6. Entities
  7. Components
  8. State Machines
  9. Further Reading

Folder Organization

Control Flow & Object Hierarchy

📲 AppDelegate + SceneDelegate
🎬 YourGameCoordinator: OKGameCoordinator ¹
🚦 YourGameState: OKGameState ²
🎛 YourUI: SwiftUI.View ³
🏞 YourScene: OKScene ³
👾 OKEntity
🚥 YourEntityState: OKEntityState
🧩 YourComponent: OKComponent

¹ OKGameCoordinator must be initialized before any other OctopusKit objects.

² Every game must have at least one OKGameState.

³ SwiftUI presents a UI overlay on top of the OKScene gameplay. UI controls or the scene may tell the game coordinator to enter different states and transition to other scenes. A scene itself is also represented by an entity which may have components of its own. A scene may be comprised entirely of components only, and need not necessarily have sub-entities.

OKEntity is optional; a simple scene may directly add sprites and other child nodes to itself.

OKEntityState is optional. An entity need not necessarily have states.

OKComponent may tell its entity to enter a different state, and it can also signal the scene to remove/spawn entities.

OKComponentSystem is used by scenes to group each type of component in an ordered array which determines the sequence of component execution for every frame update cycle.

The objects that actually present your game on screen:

SwiftUI View Hierarchy
📲 AppDelegate + SceneDelegate
📦 OKContainerView
🎛 OKUIOverlay
📦 OKViewControllerRepresentable
🎥 OKViewController ¹
🎥 SpriteKit.SKView


AppKit / UIKit Storyboard / XIB
📲 AppDelegate + SceneDelegate
📦 Main.storyboard
🎥 OKViewController ¹
🎥 SpriteKit.SKView

¹ OKViewController displays the OKGameCoordinator.currentScene and may be subclassed for custom game-specific presentation management.

Game Coordinator and Game States

🎬 OKGameCoordinator:GKStateMachine
🚦 OKGameState:GKState


🏞 OKScene:SKScene

🌠 OKSubscene:SKNode

TODO: OKScene API overview

Scenes should:

User Interface

🎛 YourGameStateUI:SwiftUI.View


👾 OKEntity:GKEntity
🚥 OKEntityState:GKState

The Scene Entity

The Game Coordinator Entity

Entities should not:

TODO: OKEntity API overview


🧩 OKComponent:GKComponent


Component Categories

A component may be conceptually classified under one or more of the following categories:

Components should:

What should be Entities and what should be Components?

TODO: OKComponent API overview

State Machines

TODO: Incomplete section
TODO: OKGameState/OKEntityState API overview

State classes should:

Further Reading

For details on the non-OctopusKit-specific concepts used here, see Apple’s documentation and Wikipedia:

OctopusKit © 2021 Invading OctopusApache License 2.0