Forem: Johan Steen

SpriteKit Safe Area

Johan Steen — Tue, 09 May 2023 07:11:14 +0000

To ensure that no important elements are obstructed on devices with notches or curved corners, the screen's safe area values are available to help with the layout. When building an app with SwiftUI, AppKit, or UIKit, taking safe areas into account is quite simple and straightforward.

As the story usually goes with SpriteKit, it is not as simple out of the box, and we have to take a few extra steps to handle safe areas in a SKScene.

There are many ways to skin a cat, and here's the workflow I've come up with that has worked very well for my SpriteKit projects.

I try to avoid having to make different versions of my code for different devices as much as possible, and that philosophy also applies when it comes to safe areas. To cover any scenario, I like to add collapsing margins combined with the safe areas, to have the content placed where I want it on all devices without any other modifications.

When there is no safe area, we are going to want to use a margin between the screen's edge and the content. On devices with a safe area, the safe area will be used instead of the margin. Basically, we intend to collapse the margin with the safe area, to make the same setup work predictably enough on any device.

Let's study a few examples to narrow it down, we'll pretend that the circle shape represents an important HUD element that we want to place in the top left corner of the screen.

The version to the left illustrates what we'd get if we do nothing and just place the element in the top left corner. On a modern iPhone, a portion of the element will be obstructed by the rounded corner.

Most likely, we'd like to add a margin, and also use the safe area of the screen. If we were to put the element in a container with a margin for left and top edges, and then also use the safe area, we would end up with the middle scenario on a modern iPhone. We have a nice margin from the top, but on the left side we have both the safe area and the margin. In this case, it would most likely look the best to only use the safe area on the left side.

That leaves us with the version to the right, where the left margin is collapsed as there is a safe area, while we still use the margin on the top edge, as there is no safe area there.

On a device with no safe areas, where the content would line up with the edge if we only used the safe area values, the margin will kick in on both the top and the left side.

SKScene Safe Areas

Before we get started, my workflow is based on the assumption that the SpriteKit scene adapts to the size based on the viewport, like I've lined out in a previous article, Multiple Aspect Ratios and Resolutions with SpriteKit. If you use another scaleMode for your projects, you might need to adjust accordingly.

With that out of the way, let's get down to business. The hosting view for the SpriteKit scene, SKView, provides a safeAreaInsets property that inherited from UIView. While this provides all necessary information about the device safe areas, the values are not directly usable, as a SpriteKit scene has its own coordinate system and then scaled inside SKView. To get something usable in SKScene we are going to recalculate these values.

For our convenience, let's extend SKScene and give it its own safeAreaInsets property. We are going to need a struct that can hold the SKScene specific values.

extension SKScene {
  public struct SafeAreaInsets {
    public let top: CGFloat
    public let left: CGFloat
    public let bottom: CGFloat
    public let right: CGFloat

    public static var zero: SafeAreaInsets {
      SafeAreaInsets(top: 0, left: 0, bottom: 0, right: 0)
    }
  }
}

This will allow us to have an API similar to the one provided via SKView, but with more relevant values for working with SpriteKit.

With the struct in place, we will have to figure out how much the SpriteKit SKScene has scaled in relationship to the hosting SKView. Let's add a property that calculates that information.

fileprivate var scaleFactor: CGFloat {
  guard let view = view else { fatalError("Scene has no hosting view") }

  return size.height / view.frame.size.height
}

We can now use the struct and the scaleFactor, to add the final property that will provide us with relevant safe area values for the SKScene.

public var safeAreaInsets: SafeAreaInsets {
  guard let view = view else { return .zero }

  return SafeAreaInsets(
    top: view.safeAreaInsets.top * scaleFactor,
    left: view.safeAreaInsets.left * scaleFactor,
    bottom: view.safeAreaInsets.bottom * scaleFactor,
    right: view.safeAreaInsets.right * scaleFactor)
}

If the scene has not yet been added to a view we return the shorthand static zero property of the SafeAreaInsets struct, else we multiply the view's safe area insets with how much the scene has scaled, to get safe area values that work as-is for the current SpriteKit scene.

To put it all together, we have ended up with this extension.

extension SKScene {
  public struct SafeAreaInsets {
    public let top: CGFloat
    public let left: CGFloat
    public let bottom: CGFloat
    public let right: CGFloat

    public static var zero: SafeAreaInsets {
      SafeAreaInsets(top: 0, left: 0, bottom: 0, right: 0)
    }
  }

  fileprivate var scaleFactor: CGFloat {
    guard let view = view else { fatalError("Scene has no hosting view") }

    return size.height / view.frame.size.height
  }

  public var safeAreaInsets: SafeAreaInsets {
    guard let view = view else { return .zero }

    return SafeAreaInsets(
      top: view.safeAreaInsets.top * scaleFactor,
      left: view.safeAreaInsets.left * scaleFactor,
      bottom: view.safeAreaInsets.bottom * scaleFactor,
      right: view.safeAreaInsets.right * scaleFactor)
  }
}

First Scene Gotcha

When the first scene is presented, SKView has not yet got the SafeAreaInsets and returns 0 for all edges. Once the view is displayed, the inset updates to the correct values.

For every following scene being presented, the view will have the correct values right away. If the first scene presented does not need to care about safe areas, it could likely be a loading scene where safe area play no part, then this gotcha is really nothing to care about.

In the case where the first presented scene needs to care about safe areas, that can be resolved by extending SKView.

extension SKView {
  override open func safeAreaInsetsDidChange() {
    scene?.didChangeSize(scene!.size)
  }
}

Once the system provides the app with the safe area values, safeAreaInsetsDidChange will be triggered in SKView. We hook in to that method to notify the presented scene about the change.

override func didChangeSize(_ oldSize: CGSize) {
  super.didChangeSize(oldSize)
  layoutScene()
}

In the presented scene, we can then use didChangeSize once the SafeAreaInsets becomes available, so the scene has a chance to do its positioning of elements there to ensure the layout for the first presented scene will look correct on all devices.

If the game supports both portrait and landscape mode, this should probably be handled in every scene to adjust the layout if the player rotates the device.

Collapsing Margins

Now, let's take a look at handling margins. Let's say that we have a player card that should be placed in the top left corner. To simplify things, let's say that we have set the anchor points of our scene to have the top left corner at (0, 0).

override func didChangeSize(_ oldSize: CGSize) {
  super.didChangeSize(oldSize)

  let leftOffset = safeAreaInsets.left
  let topOffset = safeAreaInsets.top

  playerCard.position = CGPoint(
    x: leftOffset,
    y: -topOffset
  )
}

By placing the card using the safe area values to offset the asset from the edges of the screen, we are ending up with this as a result.

When we display the scene in portrait mode, we get an offset from the top of the screen, while we have no margin on the left side. When rotating the screen to landscape mode, we instead get an offset on the left edge of the screen, but we now have no margin at the top.

So what we want to do is this:

Portrait mode: Left edge use margin, top edge use safe area.
Landscape mode: Left edge use safe area, top edge use margin.

This can easily be accomplished by using max(), let's expand the layout code from before by adding a margin of 16.0 and then using max to collapse it with the safe area.

override func didChangeSize(_ oldSize: CGSize) {
  super.didChangeSize(oldSize)

  let margin = 16.0
  let leftOffset = max(margin, safeAreaInsets.left)
  let topOffset = max(margin, safeAreaInsets.top)

  playerCard?.position = CGPoint(
    x: leftOffset,
    y: -topOffset
  )
}

With this change we are ending up with something that looks much healthier where we have a margin kicking in when there is no safe area available.

Conclusion

I hope this approach can serve as a start to get a solid foundation for how to handle safe areas and margins for content living near the edges of the screen. See this as a starting point and spur ideas how to take this further to set up a layout and positioning system with SpriteKit. As a first next step, I can definitely see the collapsing of margins being automated into a property or method.

Game Event System with Swift

Johan Steen — Mon, 25 Jul 2022 04:23:40 +0000

A game can usually be broken down into different systems, which are the building blocks of the game's architecture.

One system could manage the on screen HUD, another the player, a third the enemies, and so on, and all these systems need to communicate with each other in one way or another. It is very easy to end up with a dependency nightmare between the different game systems.

Dependency Nightmare

We begin with an example of a problematic architecture, one that we are going to try to avoid by using game events for a more modular approach.

Let's say that we have an enemy entity that we want to test in isolation to save some time. There's really no need to startup the entire game world to see the animations, how the enemy responds to certain interactions, or similar things. So we are going to use a barebone scene where we can drop in an enemy entity and to be able to do some quick tests in a live environment.

We setup the barebone scene and add some initialization code to instantiate our enemy. But it won't compile; the enemy entity depends on the existence of the EnemyManager.

So we also instantiate the EnemyManager in our test scene and give it another go. Won't compile again, the EnemyManager can't find the Player, a dependency that is used to let enemies make their AI decisions.

Okay, so we are adding the player to the test scene too. And let's run it.

Ouch, the Player needs the InventoryManager. Okay, let add that one as well. And go! Nooooooo! The player also needs the HUDManager.

Eventually we've pretty much rebuilt the entire game architecture inside what was supposed to be our lean and mean debug scene.

Game Events

Which brings us to events. By using events to communicate between the game's different systems, we get a much more decoupled architecture. When a system raises an event, it doesn't care who listens to it, and a system that listens for an event doesn't care who raised it.

This makes it very easy to take out any object from the game and drop it in an isolated environment or scene and it will pretty much work right away. And we can decorate our test scene with event triggers so we can trigger any event we want on demand and observe the behavior, without actually having to add the system that would trigger the event in the game.

This architecture helps us get rid of hard dependencies between our game's systems.

And of course, when it comes to the actual gameplay scenes, the more decoupled and isolated our systems are, the more reusable the systems will become for future projects, and as a bonus, way easier to debug and test.

Observers vs Broadcasters

When it comes to handling events, there are primarily two design patterns that are highly popular, either using observers or broadcasters with listeners.

I've implemented and used both approaches in different projects, and while I like many things about the observer pattern, it relies on dependencies between objects in one way or another. Which is what we are trying to avoid.

I've used solutions similar to this.

class HealthComponent: GKComponent, Observable {
  private(set) var health: Int {
    didSet { notifyObservers(with: .entityHealthChanged) }
  }
}

And then, the HUD can observe the health component to instantly update the health bar whenever the player's health changes. But this requires that the HUD is aware of the player object, to register with it, which gives us a hard-wired dependency.

So I personally rarely use this pattern anymore, and instead I most of the time rely on broadcasting events and having listeners, which provides a much more decoupled architecture.

The drawback can be that it can be harder to read and follow the event flow in code when there are no hard connections between the systems. Someone new to the code base would have to spend some time looking up and finding out what is listening to what events, as the compiler can't help with that.

I now handle that by logging events when running the game in debug mode, so I can at any time request the log and see what events that were triggered, and which objects that responded to each event. That more or less take care of that drawback.

Implementation

That was a lot of background and theory, but now when we have decided that we want to broadcast events between systems, let's look at how we can implement that functionality in Swift. We are going to make our own implementation as we want maximum performance. We don't want to rely on NotficationCenter or other built-in solutions that are less performant¹ than what we can build ourselves.

Event Channels

We are going to use event channels that we broadcast on, and pass along any relevant data. Interested parties can listen to channels of interest and react to events.

So we are going to setup an Event class that each event channel that we create will instantiate and be available for systems to broadcast on or listen to.

public class Event<T> {
}

We are going to use Swift generics for this class, when we define an event channel we also determine with the generic what kind of data we will pass along with the event.

let enemyDestroyedEvent = Event<Enemy>()

Here we create an enemyDestroyedEvent channel where we will pass along an instance of an Enemy object. When an enemy is destroyed the enemy will broadcast and pass along itself on this channel just before it removes itself from the game.

A number of other systems might listen to this event; the audio system could take the Enemy object and determine which sound effect to play; the UI system shows a score floating for a short period of time where the enemy was destroyed. The VFX system instantiates an explosion animation on screen at the enemy's last position.

Our Event class is going to need to store a collection of listeners for each channel so the channel knows which objects that should be notified when the event is raised.

public typealias EventAction = (_ subject: T) -> Void

/// Listener wrapper to be able to use a weak reference to the listener.
private struct Listener {
  /// Weak reference to the listener.
  weak var listener: AnyObject?

  /// Action closure provided by the listener.
  var action: EventAction
}

private var listeners: [ObjectIdentifier: Listener] = [:]

We don't want to risk that the event channel keeps the object alive if the object is removed from the game, so we use a Listener struct as a wrapper around the object that listens, so we can have a weak reference to the listener. We are using ObjectIdentifier as the key for the listener, so it's easy to find the listener in the collection if we need to remove it.

The EventAction typealias gives us some sugared syntax.

Now we have a place to store the listeners for an event channel, so let's add some methods so objects can let the channel know that they want to listen for events.

/// Register a new listener for the event.
public func addListener(_ listener: AnyObject, action: @escaping EventAction) {
  let id = ObjectIdentifier(listener)

  listeners[id] = Listener(listener: listener, action: action)
}

// Unregister a listener for the event.
public func removeListener(_ listener: AnyObject) {
  let id = ObjectIdentifier(listener)

  listeners.removeValue(forKey: id)
}

Thanks to the solid structure where we store the listeners, the addListener(), and removeListener() methods become very straightforward. We basically just have to get the ObjectIdentifier for the listener and add/remove it from the collection.

And finally, we are going to need a method to broadcast events to listeners.

/// Raise the event to notify all registered listeners.
public func notify(_ subject: T) {
  for (id, listener) in listeners {
    // If the listening object is no longer in memory,
    // we can clean up the listener for its ID.
    if listener.listener == nil {
      listeners.removeValue(forKey: id)
      continue
    }

    listener.action(subject)
  }
}

Here we raise the event to iterate through the collection of listeners to notify them. As we used a weak reference to the listener to not keep them alive if they are removed from the game, we also check here so the listener is still around. If it's not, we take the opportunity to clean up the collection by removing it.

And that's it; this class gives us everything we need to broadcast and listen to events.

Using Event Channels

That leaves us with how to use the event channels when we need to communicate between the game's different systems. There are many approaches to choose from. I prefer to use a GameEvent singleton as a communication central where I define all channels that the game uses.

class GameEvent {
  static let shared = GameEvent()
  private init() {}

  // Event Channels.
  let scoreChangedEvent = Event<GameData>()
  let livesChangedEvent = Event<GameData>()
  let enemyDestroyedEvent = Event<Enemy>()
  let playerDamagedEvent = Event<HealthComponent>()
}

This is the place where I'm collecting and organizing all event channels that the game will need, and by exposing it as a singleton, I can simply use it from anywhere in the game code.

For an object to register itself as a listener, we would use the addListener() method in the event channel.

class AudioComponent: Component {
  init() {
      GameEvent.shared.playerDamagedEvent.addListener(self) { [weak self] _ in
        self?.onPlayerDamaged()
      }
  }

  func onPlayerDamaged() {
    // Play the sound effect when player is taking damage.
  }
}

We have a component that handles playing sound effects. By having it listen to the playerDamageEvent it can play the appropriate sound effect every time the player is damaged. Also, the health bar in the HUD would listen to this event and maybe also an animation component that would play a damage animation, and possibly emit some particles.

To be useful, events must also be raised.

class HealthComponent: Component {
  func takeDamage() {
      // Do some other damage related things...

      GameEvent.shared.playerDamagedEvent.notify(self)
  }
}

Which is more or less self-explanatory. This would be the health component for the player that raises the event every time the player takes damage, so other systems can react to it. The component passes along itself with the event, so listeners that relies on data in the health component can do so. The HUD most likely is going to check the health percentage for the component when the visuals on screen are updated.

Conclusion

This is my preferred way to pass data between game systems and I find it highly powerful and flexible. The complete decoupling between objects provides possibilities for very interesting solutions. As an object is not aware, care, or even interested in what listens to its events, you can wire up pretty much anything with anything.

With that in mind, each game component can be kept very clean and only focus on one thing. The health component only needs to track health; everything else in the game that depends on health is handled by other systems, more relevant for the separate purpose, and events are the delivery mechanism between them.

The UI is driven by events from the health component; a destroy component is driven by the same events. An audio component can also listen to the event in question. Anything that makes sense can listen to events, without having to introduce a dependency between objects.

But don't forget... With great power comes great responsibility.

Performance Results. Test results of Notification Center performance. ↩

Game Center Achievements with Swift

Johan Steen — Fri, 15 Jul 2022 09:15:19 +0000

I start early on in the development of a game to think about achievements and make notes during the development progress whenever I add something to the game that could also add some sort of additional challenge for the player in one way or another, to make it into a possible candidate to become an achievement.

Implementing achievements in a game is a great way to add some additional fun things to do in the game, and to give players more enjoyment. To be able to collect an achievement is an opportunity to make the players feel good while playing, and not only to keep grinding to collect points towards a new high score.

Achievements can also be used as hints and help to direct the player to try unusual things or to find some hidden area or mechanic they might not have found out about.

As a gamer myself, I do enjoy spending some extra time in games I buy to keep collecting achievements, event after I have beaten the game.

All in all, achievements can help to add some extra playtime to the game and give some extra joy to the players, which makes me feel its worth the extra time to implement some meaningful achievements for the players to collect.

When I did my first implementation, I immediately saw the danger that the logic to check for achievement progress could add some serious code pollution. I wanted to come up with an approach to keep it as decoupled as possible from the actual game code.

Game Center for Progress Storage

Also, I did not want to worry about storing progress myself, but instead delegated that responsibility to Apple and Game Center. By letting Game Center be the only source of truth for the player's progress, players get progress synced between all their devices as a bonus. So a player who progresses towards an achievement on the iPhone, will see the same progress advancement when opening up the game on the Apple TV.

The only drawback with this solution is that Game Center only stores integers, while a custom solution could track floats and have much more fine-grained tracking towards a goal if needing more than 100 steps.

I found the convenience of not having to store things myself and not having to make a custom iCloud-based sync solution more important, than being able to have other value types for more fine-grained progress tracking.

The Achievement Logic

I came up with an approach where I make a class for each achievement in the game, and let the class contain the unique logic to track the progress of that achievement.

Doing it this way, I can keep all the achievement logic code contained completely separate from the rest of the game code. The game code should only need to worry about when to let the achievement know when it's time to run its logic.

To handle this, I'm inheriting from GKAchievement to add some additional logic while still being able to piggyback on the functionality to read from and report back the progress to Game Center using only one object.

class BaseAchievement: GKAchievement {
  /// Determine if the achievement has unreported progress.
  var isDirty: Bool = false

  /// Increase progress towards getting the achievement.
  func progress() {
    // If achievement is already completed, no need to track progress.
    guard !isCompleted else { return }

    // Run the logic to update the percentage.
    updatePercentComplete()

    // Mark it as dirty.
    isDirty = true

    // Report immediately if achievement was completed.
    reportIfCompleted()
  }

  /// Logic to update the percentage completed.
  func updatePercentComplete() {
    fatalError("Should be overriden in subclass")
  }

  /// Report the achievement if it is completed.
  func reportIfCompleted() {
    if isCompleted {
      GameCenter.shared.report(achievement: self)
    }
  }
}

My BaseAchievement class is the base for every achievement I add to the game. It gives us two additional features. First, a location for where to put the logic to track progress towards the achievement; and second, it handles deferred reporting.

Some achievements execute the progress logic quite often; for instance, an achievement to have destroyed maybe 5000 enemies could potentially run the logic in very short intervals. I don't want the game to constantly connect to Game Center servers and report every single enemy. Instead, I defer that report to occur between game levels.

Deferred Reporting

Whenever the game trigger that progress towards an achievement has happened the progress() method is executed. Unless the achievement is already completed, the logic to update the progress happens, and the achievement is marked as isDirty.

By marking achievements that have progress happening as isDirty is how we later can determine which achievements that have had changes, and then batch report all of them in one go, instead of constantly reporting them one by one as progress happens.

The exception is if the progress has completed the achievements. If so, I want the report to happen right away with reportIfCompleted() so the player gets the achievement banner shown on screen at the very moment the achievement was
completed.

Progress Logic

The updatePercentComplete() method is where the unique logic is located for each achievement. So when we make our achievements classes, this is the only method we need to implement for each achievement.

Let's look at an achievement that will be awarded when the player has collected 100 upgrades.

/// Upgrade the Weapon 100 Times.
class UpgradeAchievement: BaseAchievement {
  override func updatePercentComplete() {
    percentComplete += 1.0
  }
}

This class increases progress by 1% each time the player collects an upgrade, and once it reaches 100%, the achievement will be completed. That won't happen until after many game sessions, as one session might just be a few upgrades. But as mentioned, Game Center keeps track of the progress between sessions and also between devices.

As we execute code in this method, we could do any kind of logic required or any kind of conditions or comparisons for different achievement types.

Some achievements are one-shot achievements.

/// Read the rules.
class LibrarianAchievement: BaseAchievement {
  override func updatePercentComplete() {
    percentComplete = 100.0
  }
}

The player gets the librarian achievement for reading the game's instructions page. There's not really any progress to collect, so we set the achievement to 100% right away.

So, what to do when needing more fine grained progress tracking than 1-100?

/// Destroy 1000 Drones.
class WhackDroneAchievement: BaseAchievement {
  override func updatePercentComplete() {
    percentComplete += 0.1
  }
}

The above code could easily be mistaken for a solution, as we progress with 0.1% per event, and GKAchievement uses a double for the progress value, and by that we get 1000 levels. Which is sort of true. That is exactly what will happen locally.

Unfortunately, Game Center only stores integers on the server even though a double is reported. So if reporting 5.4, it will only store a 5.

So we can't use Game Center to track progress with more than 100 steps. If we really needed to store more than 100 steps, we'd have to track locally and then report or track with a custom cloud saving if tracking over devices, and then report each time we reach a reportable progress of the achievement.

What I found, depending on how fast the achievement progresses, is that you many times can get away with tracking with floats locally and reporting the integer at the end of the session; it will work good enough. So, I will track with 0.1 units in the game and just accepts that if the player progress 3.9% only 3% will be recorded.

Progress will be tracked slightly slower than what the player actually does, but I believe it won't be noticeable most of the time. It's been good enough for the games I've been developing so far. It has to be some really major part of the gameplay for me to consider using a custom cloud-synced solution instead, just to get more reportable steps between devices. If not needing sync between devices, it would be a lot simpler to track progress locally between sessions before
reporting progress.

Triggering Achievement Logic

Now we just need to trigger the execution of these classes. I wanted to have an as simple API as I possible could, so there would be a minimum of additional code to add to the game logic. I definitely wanted to use a dot syntax for the achievement names.

So I came up with this, using a singleton combined with a factory for the achievements, which gives us a syntax like this.

// Record the achievement.
GameCenter.shared.progress(achievement: .librarian)

The code that handles the game's instruction page, has the above line of code to ensure the achievement gets handled.

When an enemy is destroyed in the game, when the state machine enters the destroyed state for the enemy, we can run something like this.

// Progress towards achievement.
GameCenter.shared.progress(achievement: .bring_pain)
GameCenter.shared.progress(achievement: .whack_drone)

Which records the progress towards two different achievements that are related to the event of a destroyed enemy. We don't need any conditions on these calls. As soon as an achievement is completed, these calls return immediately.

The Achievement Factory

The GameCenter class is a singleton that we call the progress method on with the achievement in question whenever we need to record progress, using a dot syntax.

GameCenter.shared.progress(achievement: .survivor)

In turn, GameCenter passes on the request to record progress to the relevant achievement.

func progress(achievement: Achievement) {
  Achievement.achievements[achievement]?.progress()
}

To be able to do that with our achievement objects, I am using an enum that also has a factory and holds all achievement instances.

/// Manages available Game Center achievements
enum Achievement: String, CaseIterable {
  case champion, collector, survivor, veteran
  case librarian
}

This is what gives us the dot syntax so we get those clean and beautiful API calls from within our game code.

Moving on, we need our enum to hold instances of all our achievement objects. We need to populate each instance with the current data stored in Game Center and we need them to be ready to track progress happening at any time.

/// Collection of objects for all available achievements.
static var achievements = [Achievement: BaseAchievement]()

/// Factory to make GKAchievement objects for Game Center IDs.
static func factory(achievement: Achievement) -> BaseAchievement {
  let gkAchievement: BaseAchievement
  let id = achievement.rawValue

  switch achievement {
  case .champion: gkAchievement = ChampionAchievement(identifier: id)
  case .collector: gkAchievement = CollectorAchievement(identifier: id)
  case .survivor: gkAchievement = SurvivorAchievement(identifier: id)
  case .veteran: gkAchievement = VeteranAchievement(identifier: id)

  case .librarian: gkAchievement = LibrarianAchievement(identifier: id)
  }

  gkAchievement.showsCompletionBanner = true

  return gkAchievement
}

We call the factory using the enum cases with dot syntax, and we get back an instance of the achievement object for the requested case. I'm pretty sure this could be done more dynamically so we don't have to use a switch statement.

That's something for future enhancements. But for now, when my games don't have more than about ten or so achievements, this has worked out.

This factory is supposed to be called when we have achievement data returned from Game Center so we can populate each underlying GKAchivement with the current progress and the identifier the achievement has in the Game Center database.

I create the achievements in Game Center database using my enum cases as identifiers, so I can simply use the rawValue for each case to set the correct id for each achievement before I get a response from Game Center.

/// Create a local GKAchievement object for each Game Center achievement.
static func initAchievements() {
  for achievement in Self.allCases {
    Self.achievements[achievement] = Self.factory(achievement: achievement)
  }
}

/// Update local achievements with values from Game Center.
static func updateAchievements(_ achievements: [GKAchievement]) {
  for gkAchievement in achievements {
    if let achievement = Achievement(rawValue: gkAchievement.identifier) {
      // Update percent completed.
      Self.achievements[achievement]?.percentComplete = gkAchievement.percentComplete
    }
  }
}

I uses these two methods to handle the collection of achievements. With init I can create achievements at any time without having to wait for a response from Game Center. By having unconnected achievements, makes the code work even if the player does not use Game Center, so I don't need to have conditions for that.

The update method I can pass in an array of achievements and update the local copies in memory at any time with fresh data from Game Center.

Reporting Achievement Progress

During the startup of a game, where all different game systems are initialized, would be a good place to also sync up with Game Center and get the player's stored progress for the game's different achievements.

I use Game Center for other things too, like Leaderboard. So during the game's authentication process with Game Center, I end the authentication by loading the progress, if authentication was successful.

func loadAchievements() {
  Achievement.initAchievements()

  GKAchievement.loadAchievements { (achievements, error) in
    if let error = error {
      os_log(.error, log: .game_center, "Error in loading achievements: %@", String(describing: error))
    }
    if let achievements = achievements {
      // Process the array of loaded achievements.
      Achievement.updateAchievements(achievements)
    }
  }
}

So here is where we use the methods in the enum we created earlier. Before we ask Game Center for the achievement progress, we create an empty set of Achievement objects. The request is asynchronous and it can potentially take some time until we get a response, or maybe no response at all if the player is offline.

But if we have a successful response, we will use the update method from our enum so we have fresh data for the progress. If the player is offline, I've opted to not handle that case, and instead just not count progress for those sessions.

Depending on the game and importance of achievements, one could choose to store progress locally in that case, to sync up once the player is back online. In my case I have decided it's not worth the effort for my more casual games. I might revise that thinking for future titles.

/// Report a single achievement to game center.
func report(achievement: BaseAchievement) {
  report(achievements: [achievement])
}

/// Submit the achievement report to Game Center.
func report(achievements: [BaseAchievement]) {
  guard isEnabled else { return }

  var achievements = achievements

  // To follow best practices, remove achievements that has no new progress.
  achievements = achievements.filter({ (achievement) -> Bool in
    return achievement.isDirty
  })

  // Reset the isDirty flag in achivements with progress.
  achievements.forEach { (achievement) in
    achievement.isDirty = false
  }

  // Submit the report to game center.
  GKAchievement.report(achievements) { (error) in
    if let error = error {
      os_log(.error, log: .game_center, "Error in reporting achievements: %@", String(describing: error))
    }
  }
}

And finally, we need to get updated data back to Game Center. I have two methods that handle reporting. The main one that takes a collection of achievement objects to report, and then for convenience I have a report method that takes a single achievement object and passes it on as a collection to the actual report method.

I use the convenience single achievement report method to report immediately during play time when an achievement completes, so the player gets an immediate response.

And between levels, I pass in the entire achievement collection to report progress on every achievement before the next level begins.

Before the GKAchievement.report() call happens, which is what triggers the communication with the Game Center servers, we do a bit of tidying up. This is all happening in the GameCenter singleton and first we check so the player has Game Center enabled. If Game Center for any reason can not be authenticated this will be set to false, and we will not attempt to report.

If the player uses Game Center and is online, we will move on. Next we check the isDirty flag we set in our achievement objects. So we can filter out any objects that have had no progress. Sending back objects without progress won't cause any issues with the data, but Apple recommends to only report objects that have had changes.

And that pretty much sums it up.

Conclusion

This is the approach I've come up with to interact with Game Center, and to collect my players' progress towards the games different achievements while keeping the logic as separated as possible to avoid polluting the game's code with achievement logic.

I'm always dabbling with and considering new and better approaches for my different game systems, and I'd love to hear if you have any other ideas or thoughts on how to improve on these concepts. Or if you have taken a completely different approach that I haven't even thought of. If so, please let me know, don't be a stranger.

Sprite Component in GameplayKit

Johan Steen — Fri, 01 Jul 2022 11:47:07 +0000

Let's continue our journey to get a few useful core components for GameplayKit built, that almost every game will have use for that we write in Swift and using Apple's game frameworks.

Last time we looked at making a GameplayKit Transform Component, so let's pair that component up with a Sprite Component. A sprite and a transform component complement each other and provide a powerful, yet manageable, system to get things moving on screen.

By having a dedicated component for rendering the visuals of our entities, we get a clear separation of concerns between transformation and the visual representation.

The Sprite Component

To start off the sprite component, we will have an empty node that will serve as a root that holds one or many child nodes that make up the entity's visuals.

/// Handles visual representation of an `Entity`.
class SpriteComponent: GKComponent {
  /// The root node to add children that will be rendered in the scene.
  private let node = SKNode()
}

This makes the sprite component completely stand alone. In my own production code I shared this with my transform component. If you've read my previous article about building a transform component, you might remember that we use an SKNode there to hold the transformation data. As every entity in my setup always has a transform component, my sprite component references the same SKNode.

But for simplicity, in the example we are building here, we will let the sprite have its own. But keep in mind that you can get a very lean and elegant setup by sharing that node between some of the core components.

Sprite Properties

Let's move on to the basic properties, we are using Swift's computed properties to wrap around some of the built-in properties of SKNode, and then we add a few additional properties on top of that.

/// Computed property that manages the name of the root node.
var name: String? {
  get { node.name }
  set { node.name = newValue }
}

/// Computed property that manages the alpha of the root node.
var alpha: CGFloat {
  get { node.alpha }
  set { node.alpha = newValue }
}

/// Computed property that manages the zPosition of the root node.
var zPosition: CGFloat {
  get { node.zPosition }
  set { node.zPosition = newValue }
}

To start it off, we basically wrap some common properties from SKNode that I've found useful to be able to modify from other components that provide the unique behavior for the entity and are by that convenient to have exposed in the component.

Now let's make it a bit more interesting.

/// Determines if the node is visible in camera.
var inCamera: Bool {
  if let camera = scene?.camera {
    if let child = node.children.first {
      return camera.contains(child)
    }
  }

  return false
}

I often need to know if an entity actually is in view or not and can make behavioral decisions for the entity based on that. I've found it incredibly useful to have an inCamera property available to always be able to check the current state for any entity in the game.

The next one is isHidden.

var isHidden: Bool = false {
  didSet {
    node.isHidden = isHidden

    // Disable physicsbody while hidden to not trigger collisions.
    if isHidden {
      node.physicsBody = nil
    } else {
      if let physics = entity?.component(ofType: PhysicsComponent.self) {
        node.physicsBody = physics.physicsBody
      }
    }
  }
}

This could also be a simple wrapper around the property in SKNode as the first 3 properties were. As many of my entities also have a physics component with a physics body attached to them, I've found this to be the best location to handle that too.

Setting a sprite to hidden, does not disable its physics body. So by hooking into didSet in the isHidden property we can handle enabling and disabling the physics for the entity here, so that is taken care of automatically when we need to hide our entities for one reason or another.

PhysicsComponent is part of my core components that I include in every game, so I can pretty much assume in my other core components that the component exists.

Layering the Sprites

Another crucial part of working with sprites is depth sorting to let SpriteKit know, in which order to stack overlapping sprites on screen.

I've learned the hard way that manually assigning values to zPosition for each sprite is a sure way towards losing track of the sorting order. Instead I prefer using a Swift enum to setup predetermined sprite layers.

/// The names and zPositions of layers in the game scene.
enum GameLayer: CGFloat {
  case bullet       = 400
  case pod          = 500
  case enemy        = 600
  case player       = 700
  case fx           = 800
  case hud          = 1000
  case debug        = 1500
  case touchControl = 2000
  case overlay      = 3000
}

By using enum cases for the sprites, I ensure that a certain entity type gets consistent depth positioning, and if I want to reorder the layers, I can simply update the enum instead of having to go through every single affected entity.
I might want to move bullets to be in front instead of being behind the player, which I can do directly in the enum.

The constructor of the sprite component takes GameLayer as its signature.

init(layer: GameLayer) {
  super.init()
  node.zPosition = layer.rawValue
}

We use that when we instantiate a sprite component in an entity.

let sprite = SpriteComponent(layer: .fx)

We pass in the game layer, using Swift's dot syntax, to determine which layer the entity will be rendered on in our gameplay scene.

The Life Cycle

We are using the built-in life cycle of GKComponent that is called when the component is added and removed from an entity, to be able to do some relevant setup and cleanup.

override func didAddToEntity() {
  super.didAddToEntity()

  // Assign the entity to the node's entity property.
  node.entity = entity

  // Set the sprite root as the entity's node for transformations.
  (entity as? Entity)?.transform.set(node: node)
}

SKNode has an entity property that takes a reference to a GKEntity. To be able to get a reference to the entity directly from the sprite node is very convenient and useful.

So we use this location to assign our entity to SKNode so we can take advantage of that reference through the property.

Optionally, if planning to share the SKNode with the transform component, this would be a good place to handle that. In this example I update the transform component to use the node from the sprite component as the root for all transformations.

override func willRemoveFromEntity() {
  super.willRemoveFromEntity()

  node.entity = nil
  node.removeAllActions()
  node.removeAllChildren()
  node.removeFromParent()
}

Once it's time to remove the entity and its components from the game, we are good citizens and clean up after ourselves. We remove the entity reference as we don't want to cause any reference retain cycles. And then we stop any actions and clean up the sprite hierarchy.

That should let us leave the game world in the same pristine condition as when we entered.

Sprite Component Methods

With the sprite properties setup, and the life cycle management and initialization in place, we can start adding some useful methods to interact with the component.

First, we have the add() methods.

/// Adds a node as a child to the Sprite's root node.
func add(node: SKNode) {
  self.node.addChild(node)
}

This is the essential method to actually get some visuals assigned to the sprite component. I use this method to pass in the sprite to render in the component.

You can keep calling this method to stack up the visuals in side the component.

let sprite = SpriteComponent(layer: .fx)
sprite.add(node: debris)
sprite.add(node: flame)
sprite.add(node: sparks)
addComponent(sprite)

In the example above, when I define an entity for an explosion effect, I push in 3 different layers to my sprite node to build the entity's visuals.

Then I've recently come to like to have an additional add(to:) method.

/// Adds the sprite as a child to provided node.
func add(to node: SKNode) {
  node.addChild(self.node)
}

The essential add method doesn't build a hierarchy, and I've had a few cases where I need to keep nesting, and then this method does the trick of adding that option to the component.

And finally, we need to be able to adjust the hierarchy during runtime.

/// Moves provided node from its previous parent to be a child of this root node.
func move(child node: SKNode) {
  node.move(toParent: self.node)
}

/// Moves the root node to be a child of the provided new parent node.
func move(to parent: SKNode) {
  node.move(toParent: parent)
}

/// Moves the root node to be a child of the root node in another entity.
func move(to parent: Entity) {
  // Get the SpriteComponent of the Entity to move to.
  if let sprite = parent.component(ofType: SpriteComponent.self) {
    // Move this root node to be a child of the other entity's root node.
    sprite.move(child: node)
  }
}

The first two move methods are simply wrapping around the move method in SKNode which are useful to change the hierarchy on demand.

Then we have our own more unique move method where we can move the visuals to another Entity. So we pass in the other entity, get a reference to that entity's sprite component, and then move our complete visual hierarchy to that entity instead.

I initially thought this was a special case scenario when I needed it in one game. But when I've started new projects, I've kept reaching for this method, so I've decided to make it a permanent member of the sprite component.

Conclusion

To place the game visuals in a dedicated sprite component helps separate concerns and keep the code decoupled.

Theoretically we should be able to add a Swift protocol for rendering, RenderingProtocol, that the sprite component would conform to and we should then be be able to implement a mesh component and swap the game play over to using 3D meshes instead of sprites, without having to modify any other logic in our game entities. Well, theoretically.

Anyway, to have a dedicated component for the sprite, we get a logical place where to house things like the in camera property.

Continuing on, the sprite component would pair up nicely with an animation component that would manage animating the textures or handling flip book like animations on top of the sprite component.

And of course, a physics component that manages the physics properties of the entity and that grabs a reference to the sprite component to add and remove itself to the physicsBody property of the root node of the sprite component.

Game Input System in Swift

Johan Steen — Sat, 28 May 2022 09:48:23 +0000

Handling player input can be disproportionally difficult. One could think writing complex game algorithms would be the biggest challenge when it comes to game development. Writing an input system that can handle anything from touch to game controllers, mouse and keyboards combined with different devices and operating systems can be a whole mess of edge cases, gray hair, and trial and error.

I decided to come up with a system once and for all that I could simply drop in to new game projects together with a configuration for how I want the input to work for that game, and then be done with it.

These are the goals I wanted to achieve with the input system.

Completely decoupled from the game code.
Highly reusable, preferably a separate package.
Handle any kind of input device or screen.
Work for both UI and Gameplay.
Game code should not depend on which input is currently being used.
Handle game controllers with relevant related events.
Not be tied to a specific game framework.
Have a "swifty" feel when configuring a game's input.
Layout system to define touch input virtual controller.
Apply custom artwork for thumbsticks and buttons in the virtual controller.

We want to achieve a system that under the hood takes care of all the input handling and completely abstracts it away from the game.

That is an end to switch or if conditions that checks for keypresses, mouse buttons, touch input and other devices wired up in the actual game code. It should also automatically handle game controller detection and all related events.

And of course, we are also going to want to ensure that the input system handles everything required to have the Game Controllers supported badge in Apple's App Store.

Game Input Actions

After trying some different concepts and ideas, I ended up going with an action-based approach. The concept is that the game polls or listens to actions instead of directly having to check for device input.

Examples of actions can be "Jump" or "Move". The game only has to care about if a "Jump" action happened, and does not need to know what button or device that triggered the action to happen.

The game defines a list of actions it needs for its gameplay and then the input system generates the actions for the game.

When setting up a new game, each device the game supports is configured how it triggers the actions in the appropriate way for that kind of device.

Once implemented, I've found this to be a solid approach for a highly decoupled system that ends up with very clean and easy maintainable code when used in a game project.

Game Input Groups

With the concept of Input Actions for a game, we have immediately solved many of the initial list of bullet points that I wanted to achieve.

We have decoupled the input code from the game code so it can be reused and not tied specifically to a certain game framework. As the game only cares about actions, it does no longer depend on which device is currently generating the input.

Next, we want to solve different input scenarios. A thumbstick or a D-pad on a game controller might need to be associated with more than one action. During gameplay it is associated with a "Move" action, while when we are displaying a UI to the player we want it to be associated with a "Navigation" action.

This is the requirement that the system should work for both the UI and Gameplay. We handle that by introducing Input Groups.

Each action will belong to a group, and only one group can be active at a time. And by switching which input group that is currently active, we can immediately change the input behavior of the game.

We can have one group of actions for the UI and one group of actions for the gameplay. Then we can simply switch between the UI and Gameplay groups depending on which state the game is in.

I like to use an approach where I have a finite state machine that tracks the overall game state. By default I set the input system to UI and then I use the enter and exit transitions for my Gameplay state to change the input group. Whenever the game enters GameplayState I enable the Gameplay input group and whenever it exits GameplayState I enable the UI input group.

Configure the Input System

Now we have an idea of how the input system should work. Now it's time to deal with the "Swifty" configuration. It was very important for me to come up with an API that I felt comfortable with. Maybe one of the most important aspects of the system, as I wanted it to feel logical and easy to setup the input for each new game.

I decided on using one struct, InputConfig, that I will add to each game and this strict will hold the entire input configuration for the game by binding devices with actions.

So during the game's initialization, preferably when my GameManager starts up, I'll simply have to create the config, and then the game is ready to use the actions.

final class GameManager {
  init() {
    // Configure input mapping.
    InputConfig()
  }
}

We'll keep it simple, all right.

Then let's take a look at how we define the struct with all the game input mappings. I start by defining the input groups and input actions the game will use.

/// Registers all input actions for the game.
struct InputConfig {
    // `Input Group` identifiers.
    static let gameplay: String = "Gameplay"
    static let ui: String = "UI"

    // `Input Action` identifiers.
    static let moveAction = "move"
    static let fireAction = "fire"
    static let jumpAction = "jump"
    static let pauseAction = "pause"

    static let menuNavigate = "menu navigate"
    static let menuSelect = "menu select"
    static let menuExit = "menu exit"

    #if DEBUG
    static let debugKill = "debug kill"
    static let debugNextLevel = "debug next level"
    static let debugDropItem = "debug drop item"
    #endif
}

I initially wanted to be able to use an enum for the identifiers, but I couldn't come up with a solid solution when the config also needs to be accessible and parsed by the separate input package. By using static let we overcome that while still being able to reference them by dot syntax, so we can for instance listen to .moveAction.

In the above example we define two groups that we are going to use, then four different gameplay actions, three UI actions, and finally some additional actions only included in DEBUG builds that can be useful during play testing.

This covers everything this example game is supposed to be able to do.

Up next, we are going to map our actions to different devices. Let's check out the .moveAction bindings.

let moveAction = InputAction(name: Self.moveAction, type: .stick, bindings: [
    GamepadBinding(.leftStick),
    CompositeKeyBinding(keySet: .wasd)
])

InputAction is a core class of my game input system and it does most of the heavy lifting to be the bridge between the game and the input devices. So the InputAction takes three parameters; we need an identifier, a type, and the bindings.

By identifying it with the static let name we defined earlier, we get an association between the input action and that name, so we later on always can refer to it with .moveAction syntax. Then we need to let the action know what kind of input control this is.

I've added four different types of control to my InputAction class at this time.

.stick : A analog stick control like the thumbsticks on gamepads.
.button : A button expressed as a floating-point value.
.d-pad : A digital button control like the D-pad on gamepads.
.cursor : A position on the screen like a mouse pointer or Apple Pencil.

Then we have the bindings, which I provide as an array. In this example I provide bindings for Game controllers and keyboards. Each binding type adopts to an InputBinding protocol and has its own custom set of possible controller elements relevant for that device binding.

The GamepadBinding has elements like .leftStick, .rightStick, .buttonNorth and so on.

While the keyboard has bindings for different keys like p or shift. For convenience I added a CompositeKeyBinding on top of KeyBinding as I found myself often needing that setup. So above I use a composite key binding and pass in the .wasd keys.

And of course, as it is an array, we can use multiple bindings from the same device type for one action. So to expand on the .moveAction.

let moveAction = InputAction(name: Self.moveAction, type: .stick, bindings: [
  GamepadBinding(.leftStick),
  CompositeKeyBinding(keySet: .wasd),
  CompositeKeyBinding(keySet: .cursor)
])

We now have a second composite binding with the cursor keys, so the player can use any of those keys, according to what they prefer. I use this in other places too, like the .pauseAction.

let pauseAction = InputAction(name: Self.pauseAction, type: .button, bindings: [
  GamepadBinding(.buttonMenu),
  KeyBinding(key: "p"),
  KeyBinding(key: Character(UnicodeScalar(0x1b)))
])

Here we assign pause to both the p key and to the esc key.

Another example with multiple bindings would be the UI navigation.

let navigateAction = InputAction(name: Self.menuNavigate, type: .dpad, bindings: [
  GamepadBinding(.leftStick),
  GamepadBinding(.dpad),
  CompositeKeyBinding(keySet: .wasd),
  CompositeKeyBinding(keySet: .cursor)
])

Here we are giving the player four different options that all work at the same time to navigate the game's menu screens. And the system also handles using an analog left thumb stick as a directional pad input type, like in this case.

With all the different actions for the game configured, all that remains is to group them.

// Assign the actions to an input group.
Input.shared.add(inputGroup:
  InputGroup(name: Self.gameplay, actions: [
    moveAction,
    jumpAction,
    fireAction,
    pauseAction
  ])
)

The input system is at its core a singleton, so we easily can access it without having to create an instance. We use that to our advantage, so when the configuration adds its groups to the input system, the system gets automatically initialized and brought alive to start listening for input and invoking actions.

The game does not need to track an instance of its own for input handling. Setting up the config is all the game needs to do.

Handling Touch Input

In the previous example I didn't touch on the subject of assigning any bindings for touch controls, no pun intended.

Binding actions to touch controllers works just the same. In the most basic setup, using the built-in default flat shapes as art, it would be added exactly like any other binding, with the addition of positioning the button on screen.

let fireAction = InputAction(name: Self.fireAction, type: .button, bindings: [
  TouchButtonBinding(
    position: Position(
        horizontal: .right,
        vertical: .bottom
    )
  )
])

While this works and the layout system takes things like margins and safe area into account, it's still too limited. I want to be able to make much more custom layouts with custom artwork.

In a real scenario, I need a setup more like this, which is a controller from a game I'm currently working on.

To make a layout like this happen, the TouchInputBinding struct have quite a few more parameters than the keyboard and mouse have.

Setting up the previous devices has turned out to be quite a nice and neat piece of configuration code that is easy to overview. I didn't want to visually pollute the code with the touch bindings. So I added a method where I can add more bindings to an existing input action.

By that I can make a choice, if I want to add the touch input bindings together with the other devices, or tag them on separately at the end. So far I've always tagged them on separately, so I can deal with layout, art, and so on in the same location.

So in reality, when I do a full layout the configuration for a touch element will need an artwork reference, position, and size.

// Size shared by all buttons.
static let buttonSize = CGSize(width: 32, height: 32)

// Setup the texture reference
let fireButtonGlyph = TouchControllerTexture(
  name: "Fire Button", size: buttonSize,
  asset: .image(named: "Fire Button"))

  // Add the binding to an existing action.
  fireAction.add(
    binding: TouchButtonBinding(
      position: Position(
        horizontal: .right(buttonSize.width / 2),
        vertical: .top(buttonSize.height / 2)),
      button: TouchButton(
        symbol: fireButtonGlyph,
        background: TouchControllerTexture(
            name: "", size: .zero, asset: .none),
        pressedColor: .white
  )))

The layout system still has room for improvements and is not yet as sophisticated as it could be. On the top of my list is to add a rule system so one element can be placed in relation to another element, and specify a vector with an offset.

That would make tweaking and rearranging the layout much easier. But for now I've got by with these options where I can set the major screen location and then tweak that position that can take an additional adjustment value.

Every touch element can take a background texture, which I in this example do not use, as the element provided its own.

Once all elements are registered with the system, all assets are combined into one single texture in memory during runtime to reduce draw calls and batching for optimal performance.

Using the Input System in a Game

With the configuration done it's time to use the actions in our game. This is where we get rewarded. Not only is it easy to use the actions from this point on, we can also remap actions to new buttons or add new bindings without having to touch any of the game code.

I prefer to use patterns in the line of delegates, so we are listening for events and don't do any kind of processing until an event actually occurs.

In opposite to a polling system where we need to do some tiny processing on each update loop to see if an event has occurred.

I implemented both options in the input system as I find them both useful for different reasons. I want to listen to the action event once I'm done implementing an input-dependent feature. At the same time, I find it convenient to have a polling option when I just quickly want to test something without having to add code for delegates or listen to an event.

I also added support for analog events on everything. So I can always choose if I want to get a digital value or an analog value. That is, I can get a value that the button was pressed, or if needed I can also get the value of how hard the button was pressed.

Taking the .button input type as an example, we've 3 possible states to query about.

triggered: Triggered is set on the frame, the button is pressed down.
released: Released is set on the frame, the button is released.
value: Value always holds the value of how much the button is pressed down, in the 0.0 - 1.0 range.

Polling for Input Actions

Let's start by looking at an example where we poll an input action for an event.

class InputComponent: Component {
  let fireAction = Input.shared.getAction(map: InputConfig.gameplay, name: InputConfig.fire)

  override func update(deltaTime seconds: TimeInterval) {
    if fireAction.triggered {
      // Do something...
    }
  }
}

We grab a reference to the action we are interested in, then we use the game's update loop to check the state of that action.

As soon as some form of input device makes the input system trigger a fire action event, our condition will be true and we can run the code relevant for a fire action in out game.

If I'm more interested in getting the analog value for an action I can use the getValue() method.

if let fireValue: CGFloat = fireAction.getValue() {
  print("fire:", fireValue)
}

Different input types return different value types. A .stick input will return a CGVector while a .button input will return a CGFloat. The getValue() method is a generic method, so we have to cast it to the type we expect the action to return.

Listen for Input Actions

Polling is nice and convenient to make quick tests or prototype things. In the end, listening to actions is what I most likely will use, which is also supported by the input system.

Each action can be assigned a delegate, so it's actually more or less dead simple to set up a listener.

class SomeComponent: Component {
  init() {
    Input.shared.getAction(map: InputConfig.gameplay, name: InputConfig.moveAction).delegate = moveDidChange
  }

  func moveDidChange(_ inputAction: InputAction) {
    let movement: CGVector = inputAction.getValue()

    // Do something with the movement value.

  }
}

We get a reference back to the InputAction when the action is triggered, so we can cast and read the value and update our game state based on the input value.

Switching Input Group

And finally, we are going to look at switching groups. As discussed earlier, we most likely are going to want to switch between UI input and gameplay input whenever we change between a gameplay state and the other states the game can be in.

I prefer to handle that with a state machine for my game states.

class PlayingState: GameSceneState {
  override func didEnter(from previousState: GKState?) {
    Input.shared.enableActionMap(name: InputConfig.gameplay)
  }

  override func willExit(to nextState: GKState) {
    Input.shared.enableActionMap(name: InputConfig.ui)
  }
}

In this example we change the input group each time we enter and exit the playing state of the game. Easy!

And that's all the code to get all the input setup in a game that I need. All the remaining code from dealing with game controllers to keyboards to actually handling input and interaction with devices, lives in my reusable Swift package.

Under the Hood

We have now looked at the concepts and ideas of how to make a rock-solid, decoupled and device-independent input system for games that is easy to interact with and setup from the game's code base.

The actual inner workings that provide the different classes and value types we use are contained in my Game Input System Swift Package. To dive into the core of my library would be a bit too much for an article like this, we would turn it into a book.

Instead, I hope my walkthrough how I've set up my system. My thinking behind the different choices I made and how I interact with the system is enough so you can build an input system and fill in the blanks to build it in your own way with how you prefer to interact with your system.

And that my system can serve as a starting point to get your ideas flowing, and that you might get some insight to do things in ways you might not have thought of otherwise.

The Core Structure

My core structure is built around protocols and value types so I can easily extend it with new features and add new devices in the future.

The most important protocols, classes and value types that could be useful to consider if building an input system with a similar approach as I've done.

InputDevice: This is a protocol that provides the basic ins and outs to communicate with any kind of input device. So any new device type implements this protocol and makes it possible for the system to interact with the device. So any class like Gamepad, Mouse or Touch adapts to this protocol and this is where the unique code is to translate between the device and the input system.
InputBinding: Is a protocol that holds a reference to the InputAction it belongs to and is adapted by Input devices to provide the unique elements. This is the bridge to how the input device passes along an event to an InputAction so the event can be triggered for the game to use. We have things like GamepadBinding and KeyInputBinding that provide their own unique implementation to bridge between the device and the action.
InputAction: This is the working class hero. This is where all device events end up; the values are processed and also transformed when necessary. For instance, there can be processing of input smoothing or calculation of analog values on digital-only devices based on time since triggered. This is where the game can query for current values and check the state of actions at any time.
InputGroup: This value type organizes and toggles the actions associated with the group.

These four are the core functionality of the system. On top of them is the Input singleton that makes it easy to interact with the package, and that's pretty much it.

Then there are quite a lot of additional code to handle special cases like laying out the virtual touch input controller and everything related to that.

Conclusion

Making the gameplay logic and algorithms is the easy part of game development. Making input systems is hard, but it pays off and is well worth the time to get it done right.

Then there's always the management of UI states... But that's a story for another day.

Transform Component in GameplayKit

Johan Steen — Sat, 21 May 2022 17:47:34 +0000

In every new game project I have a few components which are part of my reusable core functionality that I always include. To have a set of GameplayKit based components that provide common functionality most games require can save a great deal of time once implemented.

+-- Shared
  +-- Entities
  +-- Components
    +-- Core
          InputComponent.swift
          PhysicsComponent.swift
          RemoveComponent.swift
          SpriteComponent.swift
          TransformComponent.swift

Last time we looked at implementing a GameplayKit Remove Component and now the time has come to see how we can implement a transform component.

Almost every entity I create needs transformations in one way or another, so to have a rock-solid and robust transform component that is easily accessible everywhere where it makes sense, has turned out to be incredible helpful.

The purpose of the transform component is to give ourselves a clean and logical API that wraps around useful transform related functions similar to how the major game engines do it.

This will provide us with a system where the transform interaction is fully decoupled from the visual representation of the game entity. Clean, single responsible components, help us to get better structured and more maintainable code.

Apart from handling the obvious properties position, rotation and scale, we also get a location in the game code where we can put anything related to overall transformation handling that is useful for more than one entity.

The Transform Component

To start off the transform component we will have an empty node that will serve as a container that holds the transform properties.

/// Handles transformations for an `Entity`.
class TransformComponent: GKComponent {
    /// Reference to the node that holds the transformations.
    ///
    /// We assign an empty node by default so an entity can have transformations
    /// without having a sprite node assigned to it.
    private lazy var node = SKNode()
}

To ensure that our transform component can always hold transformations, we instantiate an empty SpriteKit SKNode by default. We do it lazily as we only want to create the empty node if we actually need it.

The node property can be used differently, depending on the game and the entities needs. Many times I let my SpriteComponent set itself as the node in the transform component, which is the reason why we want it to be lazy.

Other times I might keep the empty SKNode and use it as a parent for the sprites it transforms. So it's a case-by-case scenario.

Transform Properties

Let's move on to the basic properties, where we wrap the transform component around the properties of SKNode with some added sugar on top.

First, we have the position.

/// The position of the entity's node in its parent's coordinate system.
var position: CGPoint {
  get { node.position }
  set { node.position = newValue }
}

/// Computed world position from parent's coordinate system.
var worldPosition: CGPoint {
  get {
    guard let parent = node.parent,
          let entity = self.entity as? Entity,
          let scene = entity.scene
    else { return position }

    /*
      Use parent's coord system.
      Convert this node's local position to the world node's coord system.
      */
    return parent.convert(node.position, to: scene.world)
  }
  set {
    guard let parent = node.parent,
          let entity = self.entity as? Entity,
          let scene = entity.scene
    else { return }

    node.position = scene.world.convert(newValue, to: parent)
  }
}

The position property is simply a wrapper around the position property in SKNode.

More interesting is the world position. I use the worldPosition property all the time and I find it very useful to have a wrapper around reading and setting the position in world space.

So by having both a position and a worldPosition property as part of the transform component, it becomes dead simple to work with the position of entities in both local and world space.

Next, moving on to rotation.

/// The Euler rotation about the z axis (in radians).
var rotation: CGFloat {
  get { node.zRotation }
  set { node.zRotation = newValue }
}

Not much to say here; the rotation property simply wraps around the zRotation property in SKNode. I haven't yet had any reason to add any other options here.

If you prefer working with degrees instead of radians, you could add a conversion for doing that here.

And finally, we have the scale.

/// A scaling factor that multiplies the size of an entity.
var scale: CGSize {
  get {
    return .init(width: node.xScale, height: node.yScale)
  }
  set {
    node.xScale = newValue.width
    node.yScale = newValue.height
  }
}

/// Get accumulated size of the entity.
var size: CGSize { node.calculateAccumulatedFrame().size }

I prefer to work with scale by having it contained in one CGSize value instead of working with each axis separately. So the scale property wraps a CGSize value around xScale and yScale in SKNode.

Then the additional size attribute calculates the total size of everything added to the hierarchy of the node. One use for this is to get the size in Physics Component when setting up the physics properties.

Transform Methods

With the transform properties setup, we can start adding useful methods to interact with the component.

I've a set(node:) method that I use for updating which node that the transform component uses for holding its properties.

/// Set the node that holds the transformation values.
func set(node: SKNode) {
  // Transfer attributes from the previous referenced node to the new.
  node.position = position
  node.zRotation = zRotation
  node.xScale = scale.width
  node.yScale = scale.height

  // Set self.node to reference the new node.
  self.node = node
}

The transform component might already have values assigned to its properties, so when setting a new node I transfer the properties from the node that previously was responsible for holding the properties to the new node.

This is a design consideration that I've been juggling a bit back and forth with. And I'm still not 100% sure if this is the way I'm going to keep it or if I might revise it in the future.

I've been considering using another approach where the transform class has its own properties for position, rotation and scale instead of using a node to hold those properties. But so far I've found it more useful to have it in the node, and also simpler to work with. So for now, I'll stick to this approach.

And then finally, we can start decorating the component with useful methods to simplify making transforms on our game entities.

/// Moves the transform in the direction and distance of translation.
func translate(_ direction: CGVector) {
  node.position += direction
}

/// Run an animation SKAction on the node.
func run(_ action: SKAction) {
  node.run(action)
}

With the structure for the transform component in place, there is no limit to different methods that are useful for transformations in game development that we can keep adding to this class.

I'll get the ball rolling with two example methods.

In any component that handles movement logic for our game entities, we can use the translate method to quickly execute the movement on screen. If the component has a direction and speed, we can simply pass in the formula to the transform component.

transform.translate(direction * speed * Time.deltaTime)

This is something I use all the time. To be able to simple get the delta time anywhere in your game code as in my example above, you can check out my article on writing a class for Game Time in Swift.

Another method that I find useful is to have a run() method where I can execute SKActions on the entity.

transform.run(.sequence([actionA, actionB]))

I use this for animations, but I also use it quite often to quickly be able to run time-based logic on a game entity. For instance, on an explosion entity I would start a run action with a completion action that adds a remove component when the explosion is done.

Accessing the Transform Component

With the transform component done and ready to be used in our game entities, we need to make sure we can easily get hold of a reference to it.

The transform component is something I use all the time. Not only for moving the objects on the screen, but I also need to read the transformation data for all kinds of different logic. It could be anything from a behavior system to handling trigger-based events.

More or less every game entity will require the transform component, so I've made it a part of my base class for entities. Which ensures that the rest of the game systems can count on that there will always be a transform component available.

I create my own base class for that all game entities inherit from, which is on top of GKEntity in GameplayKit.

class Entity: GKEntity {
  /// Transform Component.
  let transform = TransformComponent()

  override init() {
    super.init()

    // Every entity has a transform component.
    addComponent(transform)
  }
}

As every entity in the game inherits this Entity class instead of using GKEntity directly, they all automatically get the transform component added.

We also want to make sure that every game component has quick and easy access to its entity's transforms. So just as we did our own Entity class instead of using GKEntity, we will use our own Component class instead of using GKComponent
in GameplayKit directly.

class Component: GKComponent {
  /// Hold a reference to the entity's TransformComponent.
  lazy var transform: TransformComponent = {
    guard let entity = entity as? Entity
      else { fatalError("The component must be added to an Entity.") }

    return entity.transform
  }()
}

We want it to be dead simple to get hold of the transform component everywhere where it makes sense, and that is in other game components.

By having a lazy property we get the reference to the transform component first time it's used, and then the reference is kept for in the property, which is good for performance.

Now every component in an entity has direct access to its transform, and we can write code like this anywhere without having to first find the transform component or having to worry about which SpriteKit node to interact with.

transform.position = newPosition

Powerful and convenient at the same time.

Where to Next

With the basic structure for the transform component in place, we can continue decorating it with methods to keep increasing its usefulness. We've just scratched the surface of what methods to include.

I'll put some ideas on the table that I believe would be useful. What first comes to mind would be to add a property and related methods to simplify the handling of the parent-child relationship between game entities.

I can also see that including methods for both local and world space operations for rotations and scale would be of use. It would probably also be convenient to add methods that rotate towards a direction and/or move towards a specific position. And the list could go on.

Enjoy leveling up your gamedev with a powerful transform component.

Batch Remove System for GameplayKit Entities

Johan Steen — Sat, 14 May 2022 13:27:59 +0000

In most games, objects are being added and removed from the game world as the game progresses. This is an operation that affects memory usage and also triggers possible garbage collection.

I was looking for a solution to be able to remove objects in batches instead of having custom code that handles removal of objects scattered throughout my games.

I came up with a solution based on using a component together with a component system in GameplayKit.

By removing objects in batches I get control of exactly then during the game's update loop removal of objects are happening and also get the code better structured and performant to do these operations that affects memory in one go instead of being fragmented during the frame cycle.

It has also allowed me to get cleaner and more consolidated code with a single location that handles the removal of objects.

The Remove Component

The remove component is super simple; all it does is add itself to a component system, so it can be processed later.

import GameplayKit

/// Flags an entity to be removed from the game.
class RemoveComponent: Component {
    // MARK: Component Life Cycle

    override func didAddToEntity() {
        super.didAddToEntity()

        // Register with the removeComponentSystem.
        scene?.removeComponentSystem.addComponent(self)
    }
}

We use didAddToEntity() to run our code automatically as soon as we add the component to an entity.

The component system the remove component adds itself to is defined in the scene class where the game runs. As almost all my entities and their added components needs to reference the scene file, I'm letting all my entities have a reference to the scene, and then I don't use GKComponent directly but an extended version with a helper property so I always can reference the scene from components.

It looks something like this.

class Component: GKComponent {
    // MARK: Convenience Properties

    /// The scene the owning entity is added to.
    var scene: GameScene? { (entity as? Entity)?.scene }
}

The RemoveComponent is a child of my Component and not GKComponent so I can use the scene property in didAddToEntity() method.

The Component System

In my game scenes where I define my different component systems, I've setup a dedicated GKComponentSystem which only has the purpose of handling removals of entities from the game.

class GameScene: SKScene {
  // MARK: Component Systems

  /// Component System to remove entities from the game.
  let removeComponentSystem = GKComponentSystem(componentClass: RemoveComponent.self)
}

In the life cycle of SKScene ¹ didFinishUpdate() is the last method called just before the wait for the next frame begins. That method should be a great choice for us to use for the removal of our objects from the game.

At this time everything in the game is done executing during this update loop, so we end this cycle by batch removing all objects flagged for removal.

override func didFinishUpdate() {
  super.didFinishUpdate()

  // Remove entities flagged for removal.
  for component in removeComponentSystem.components {
    if let entity = component.entity as? Entity {
      // Remove the entity and it's resources.
      remove(entity: entity)
    }
  }
}

When iteration through the remove component system to get a reference for each entity that has the RemoveCompenent added, we call a remove method that has the actual logic to remove each entity from the game world.

A remove() method would most likely be unique for each game project. For me, I usually end up with something like this.

/// Removes an entity from the game world.
func remove(entity: Entity) {
  // Remove sprite component as that removes the nodes from the scene.
  entity.removeComponent(ofType: SpriteComponent.self)

  // Remove the reference from the entities set.
  entities.remove(entity)
}

I use a GKComponent that handles the sprite and it knows how to visually remove itself from the game world in the willRemoveFromEntity() method that is automatically called when a component is removed.

I keep a set with references to all entities currently in the game world, which I remove the entity from.

Using the Remove Component

That's basically it; the only thing that remains is to actually start using the RemoveComponent when we need to flag an object for removal.

All we have to do to remove an object from the game is to add the RemoveComponent to the entity.

Let's say that we have a bullet in the scene and we want to remove it when it hits its target. Then we simply can add the RemoveComponent in the contactDidBegin method.

func contactDidBegin(with other: GKEntity, contact: SKPhysicsContact) {
  // Flag the bullet for removal.
  addComponent(RemoveComponent())
}

Or we might have a particle emitter with a lifetime of 1.5 seconds that we want to remove when done playing. Then we could add the RemoveComponent by using an SKAction.

// remove emitter when done
let wait = SKAction.wait(forDuration: 1.5)
let remove = SKAction.run { [weak self] in
    self?.addComponent(RemoveComponent())
}

run(SKAction.sequence([wait, remove]))

We use the run SKAction and a sequence to add the RemoveComponent after the specified time has elapsed.

Where to Next

With this structure in place where we have a separate system that tracks objects for removal, it would be interesting to keep building on this concept to separate some of this logic away from the game loop.

For instance, we could potentially see if it was possible to use a background thread to iterate through the component system to get more time left on the main thread used by the game for a performance increase.

But that's a project for another day.

SKScene Life Cycle. Responding to Frame-Cycle Events. ↩

Better Time Management in SpriteKit

Johan Steen — Sun, 08 May 2022 11:01:06 +0000

Time management and the usage of delta time is one of the most important and fundamental parts for most game projects as it ensures consistency of any on-screen transforms no matter what the device's frame rate is that the game runs on.

More or less any form of movement, rotation or time-related calculation should take delta time into account to ensure it's not dependent on the frame rate.

Without using delta time, a bullet in a game, as an example, would move at a different speed on a 120 fps device compared to a 60 fps device.

Delta Time in SpriteKit

SpriteKit does not give us a delta time value out of the box, which is unfortunate considering how useful it is.

It's not that the game framework engineers at Apple are not aware of delta time, as the GKComponent in GameplayKit requires delta time in its update(deltaTime:) method. But you have to calculate the value yourself.

At the same time as it's unfortunate that SpriteKit does not provide delta time out of the box, it's also understandable that the GameplayKit engineers deemed deltaTime as a requirement when calling the update method, as a component will most likely need to use delta time in one way or another.

And of course, if not using GameplayKit but only plain SpriteKit, you are going to need to use a delta time for your on-screen calculations to ensure consistency no matter what frame rate the device runs on.

SKScene provides the current time value, so most likely you are using or have seen solutions similar to this to get the delta time value.

class GameplayScene: SKScene {
  /// Keeps track of how much time has passed since last game loop update.
  var lastUpdateTime: TimeInterval = 0

  override func update(_ currentTime: TimeInterval) {
    super.update(currentTime)

    // Get delta time since last time `update` was called.
    let deltaTime = calculateDeltaTime(from: currentTime)
  }

  /// Calculates time passed from current time since last update time.
  private func calculateDeltaTime(from currentTime: TimeInterval) -> TimeInterval {
    // When the level is started or after the game has been paused, the last update time is reset to the current time.
    if lastUpdateTime.isZero {
      lastUpdateTime = currentTime
    }

    // Calculate delta time since `update` was last called.
    let deltaTime = currentTime - lastUpdateTime

    // Use current time as the last update time on next game loop update.
    lastUpdateTime = currentTime

    return deltaTime
  }
}

In the life cycle of this SKScene we get the current time provided in the update method. By storing the current time value in the class property lastUpdateTime, we are able to keep track of how much time that has elapsed since the last time the update method was called, and by that we have our delta time value.

We can then take this value and keep passing it along to other methods or systems that need to use delta time for their calculations.

Which could look something like this.

override func update(_ currentTime: TimeInterval) {
  super.update(currentTime)
  let deltaTime = calculateDeltaTime(from: currentTime)

  // Update the bullet system that handle movement of all bullets on screen.
  bulletSystem.update(deltaTime: deltaTime)

  // Update each GameplayKit component system.
  for componentSystem in componentSystems {
    componentSystem.update(deltaTime: deltaTime)
  }
}

Each system, component or object that uses delta time will then have to accept the value in its method signature, and then pass it along further down the chain to its own methods that relies on delta time. You most likely will not want to keep all your logic in the update method, as it could grow massive, but structure the logic in dedicated methods.

We then end up with components like this.

class MoveComponent: GKComponent {
  // ... Initialization and references to other components of the entity here ...

  override func update(deltaTime seconds: TimeInterval) {
    super.update(deltaTime: seconds)

    move(deltaTime: seconds)
  }

  private funct move(deltaTime seconds: TimeInterval) {
    entity.position += speed * direction * CGFloat(seconds)
  }
}

Here we have a move method in the component that moves the entity's position at a speed and direction that is not dependent on the device frame rate as we multiply the resulting velocity with our delta time value. As delta time is passed as a TimeInterval we have to cast it to an appropriate format, like CGFloat.

Most games will of course not only use the update method in SKScene, but will need to use the other methods in the life cycle, such as didSimulatePhysics or didFinishUpdate.

Those methods do not get the current time injected, so we are going to have to promote the deltaTime property to a class property to be able to access and use delta time in those scenarios.

class GameplayScene: SKScene {
  var deltaTime: TimeInterval = 0

  override func update(_ currentTime: TimeInterval) {
    deltaTime = calculateDeltaTime(from: currentTime)
  }

  override func didSimulatePhysics() {
    // Update camera movemement.
    camera?.entity?.update(deltaTime: deltaTime)

    // Update each 'after physics' component system.
    for componentSystem in afterPhysicsComponentSystems {
      componentSystem.update(deltaTime: deltaTime)
    }
  }
}

While this is an approach that does the job, and SpriteKit provides us with the necessary data to deal with delta time, it's quite convoluted.

We are mixing the time logic with the scene logic. And as every calculation that affects what happens on the screen, which is a lot in most games, relies on delta time, we are going to have to keep passing the value around between systems, classes and methods.

We might also have multiple scenes, even running at the same time, which happens when transitioning between scenes, which would create multiple delta time calculations at the same time.

The more complex a game becomes, with more systems and classes, the more this approach will feel to start falling apart. Let's find a better way.

Game Engines

Looking at modern game engines such as Unity and Unreal, they calculate delta time as a core functionality and the value is made available to use where you need it. It makes sense that any framework that targets game development makes this available.

If we for instance take a closer peek at Unity, it provides a Time class¹ that has static properties containing time-related data.

By that, you never have to pass any time information around in your game code. Instead, you can at any time do a calculation like this, by just statically accessing the deltaTime property of Time.

var position += speed * direction * Time.deltaTime;

It's apparent that they decided that something so crucial and that is used so often in game development should be calculated under the hood and be easily available at any time, which making it static solves.

The time class in Unity does not only provide deltaTime as a static property but has a ton of different useful time-related information.

Swift Class for Static Time

We have now examined the ordinary approach to dealing with delta time in SpriteKit as well as taken a peek at how modern game engines handle it. So let's aim for a similar approach in SpriteKit for a better way to easily get access to time information via static properties.

We'll take inspiration from Unity and see how we can have a Time class available in SpriteKit with static properties that are not tied to the current scene's update loop.

The static class will need to hold relevant properties together with an update() method to keep the values current.

/// Tracks the game's time-related information.
public enum Time {
  /// The time given at the beginning of this frame.
  public private(set) static var time = TimeInterval(0.0)

  /// The interval in seconds from the last frame to the current one.
  public private(set) static var deltaTime = TimeInterval(0.0)

  /// Called on the device's frame update to track time properties.
  static func update(at currentTime: TimeInterval) {
    //  If `time` is 0.0 the game has just started, so set it to `currentTime`.
    if time.isZero {
      time = currentTime
    }

    // Calculate delta time since `update(at:)` was last called.
    deltaTime = currentTime - time

    // Set `time` to `currentTime for next game loop update.
    time = currentTime
  }
}

That gives us the Time class with the static properties and a method to keep them up to date. Now we just need a place to call the update() method. The first thought might be to call it from update() in SKScene. Which would work most of the time.

We do get one problem if we do it from SKScene, at some times we might have more than one scene running, for instance when transitioning between two scenes. That would cause a race condition when then they would both update Time, which will give us an incorrect deltaTime for one of the scenes.

We also want to keep our code clean and not have to remember to call Time.update() in every scene class we create, as well as we want to avoid polluting the scene class with code that doesn't have to be there.

Luckily SKView has a delegate property that we can use for this. The delegate property takes an SKViewDelegate² object, which gives us the hook we need to have a place to calculate time values outside the scene class.

Let's create our own Ticker class, which is an SKViewDelegate so we can update our Time class. The view() method in SKViewDelegate is called just before the update() method in SKScene, so it's a perfect place for us to use to update time properties.

/// Assign to the `SKView` to update game time properties for each frame.
public class Ticker: NSObject, SKViewDelegate {
  public func view(_ view: SKView, shouldRenderAtTime time: TimeInterval) -> Bool {
    // Update time properties.
    Time.update(at: time)

    // By returning true the game runs at the full frame rate specified with preferredFramesPerSecond.
    return true
  }
}

And finally, we need to assign the delegate to the SKView, during the game's initialization process.

I prefer to have a GameManager class where I do all my early initialization. I instantiate my GameManager immediately from my ViewController where I pass in the SKView that will present my different game scenes.

That is the perfect spot to assign the custom delegate that will ensure that the time properties stay up to date without having to manage that on a per-scene basis.

class GameManager {
  /// Ticker that updates game time properties.
  let ticker = Ticker()

  init(view: SKView) {
    // Assign the game time ticker to the view.
    view.delegate = ticker

    // ... Other game setup code would go here...
  }
}

And there we have it, a rock-solid reusable solution that gives us easy access to time properties like delta time from anywhere in our game code.

Whenever we need to do a delta time based calculation, we can now at any time use Time.deltaTime as part of the calculation.

Further Improvements

With a central location for our time properties, it doesn't have to end with delta time. There are plenty of time-related properties that are useful for game development. If we look at Unity's Time class as a reference, we could replicate more of the properties there and keep decorating our own Time class.

Let's say we also want to have access to the frame count in our game code.

public enum Time {
  /// The total number of frames since the start of the game.
  public private(set) static var frameCount = 0

  static func update(at currentTime: TimeInterval) {
    // ... previous code in the update method here ...

    // Increase frame count since game started.
    frameCount += 1
  }
}

We can now at any time access Time.frameCount if we need to read this value.

The final tweak, let's extend our value types operators to handle TimeInterval.

Previously in this post we multiplied speed with delta time and had to cast the time value to CGFloat, CGFloat(seconds). As we are going to use the delta time value in many places, it would be convenient if we didn't have to cast it every time. Instead, we can extend types we are going to use with delta time, such as CGFloat and CGVector to use TimeInterval.

Here's an example of extending CGFloat so we can multiply a CGFloat value directly with a TimeInterval without having to cast it every time.

public extension CGFloat {
  static func * (lhs: CGFloat, rhs: TimeInterval) -> CGFloat {
    return lhs * CGFloat(rhs)
  }
}

By that, we are now able to write clean game code like this.

movement = speed * Time.deltaTime

What a beauty!

Unity API: Time. Static properties that provides time information in Unity. ↩
SKViewDelegate. Take custom control over the view's render rate. ↩

Trail VFX with SpriteKit

Johan Steen — Sat, 30 Apr 2022 01:31:21 +0000

Visual Effects are an important part of making pleasing effects in games. Commonly, VFX is used for things like bullets, projectile trails, magic, portals, and countless other things.

I was doing research some time ago on how to be able to replicate some common VFX techniques in SpriteKit. More specifically, I wanted to be able to make trailing effects to spice up the look of bullets as the player upgraded them while progressing through the game.

This is the kind of effect I ended up with, using only the functionality provided by SpriteKit.

Trailing VFX Breakdown

Let's start by breaking down how an effect like this is usually constructed, and then we continue on how to implement those techniques using SpriteKit.

The effect is based on having a seamless trail texture. This can be created in Photoshop quite easily with some random strokes and then matching up the edges with the offset filter to make it seamless. But that's out of the scope of this article.

Moving the Trail Independently

We are going to apply this texture on a plane, which is the VFX object that we will add to and move around in our game world. To make the texture feel dynamic instead of static, we are going to tweak the UV coordinates, which controls how the texture maps to the plane.

When we compress the V position of the coordinates on one edge of the UV, we effectively squeeze the texture located on the opposite edge, so we get a tapered effect on the texture from one edge to the other.

And here comes the beauty, if we move this plane over the scene, and at the same time we also move the U position of the texture, at a different speed than the plane is using, the texture "comes alive" and we get a sense that the texture constantly evolves and animates during its lifetime instead of just statically move over the scene.

Working with a UV like this, the possible effects can be taken much further. We could alter the UV using a curved shape instead of a linear falloff, or segment it up and randomly adjust each segment's size slightly to break up the movement and move it even further away from a static texture.

Fading Out the Trail Edge

Next, we are going to need to fade out the edge of the trail so it doesn't cut off abruptly. We will do that with the help of a gradient map.

The gradient map is the top layer of the stack which we are using to control the opacity of the effect. This layer will remain in place and not move over the UV like the trail texture does. By doing a multiply blend of the top gradient layer with the layers below, we end up with a nice fade out at the edge of the trail.

Additional Tweaks

To give the trails a bit more flare and depth, we are going to duplicate the trail texture two or three times and stack them on top of each other. Each copy will have the texture slightly offset and move over the UV at a slightly different speed.

This gives us tons of dynamic variation as the effect moves over the game scene. In the video of my SpriteKit effect above, I've layered the trail texture two times and each layer moves with different speed values and is then blended together.

And for the final touch to make it glow, top it off with a bit of bloom.

SpriteKit Implementation

That was it for the theory and how one would achieve this kind of effect in most graphics and game systems. So let's see how we can approach this using SpriteKit and get into the nitty gritty details with some code.

The biggest challenge is that we don't have access to manipulate UV coordinates when we map textures to nodes in SpriteKit. With SceneKit it would have been a different story, but oh well. As game VFX is often heavily based on manipulating UVs, we have to come up with some workarounds to achieve similar outcomes.

The Trail Setup

The trail layer would usually rely heavily on manipulating UVs. As we don't have access to UVs in SpriteKit, let's see what we would need the UVs to do, and then find SpriteKit solutions.

With UVs textures can easily be repeated, so when the texture leaves the surface on one edge, it wraps around, and comes in on the opposite edge.
UVs allow us to compress and resize parts of the texture independently of how the displayed surface is sized.

As SKSpriteNode does not have functionality to move and wrap a texture applied to it, we'll solve it by repeating the texture ourselves, parent the repeated setup to a container node, and then crop out the visible area.

We'll have to handle the wrapping ourselves.

We will need three repetitions of the texture, which is enough no matter at what position we are observing it, to have enough repeating texture on each side to always be covered.

This setup will allow us to move the projectile texture independently of the parent node.

So let's begin with setting up the trail. I put this into it's own method so we can potentially create multiple layers of the same trail and stack for variation.

func makeTrail() -> SKNode {
  let trailC = SKSpriteNode(imageNamed: "trailTexture")
  let trailL = SKSpriteNode(imageNamed: "trailTexture")
  let trailR = SKSpriteNode(imageNamed: "trailTexture")

  trailL.position.x = -512
  trailR.position.x = 512

  let trails = SKNode()
  trails.addChild(trailC)
  trails.addChild(trailL)
  trails.addChild(trailR)

  return trails
}

We simply create the three instances we need of the texture. We have one centered, and then we move one to the left of it and one to the right of it.

In the example above, the texture is 512 points wide, so I've hard-coded the values 512 and -512 to move each segment to the left and right. We could have got this value from the texture itself, to make it more reusable.

We then parent all the segments to an SKNode and return this hierarchy. This trail object is basically what we need to be able to move and wrap the trail texture independently.

Now we can call makeTrail() whenever we need a new trail to build and layer up an effect.

override func didMove(to view: SKView) {
  // Get 2 wrapable trails.
  let trail1 = makeTrail()
  let trail2 = makeTrail()

  // Make the second trail slightly taller and change the blend mode to `add`.
  trail2.zPosition = 1
  trail2.yScale = 1.25
  for child in trail2.children {
    if let child = child as? SKSpriteNode {
      child.blendMode = .add
    }
  }

  // ... Setup continues ...
}

In this example we create two trail objects, so we can layer them on top of each other for more variation that will help sell the effect as a non-static texture.

The second trail object is made slightly larger by scaling it to 1.25 on the y-axis. The second trail is placed on top of the first, so each child of the second trail has its blendMode changed to add.

Move and Wrap the Texture

Time to get the texture moving. We will use the SKCropNode to get a window that we can observe our trail object through, and then give the trail object that holds the texture its own movement loop.

The crop node can then move around on the screen while the trail texture moves and wraps independently beneath it.

override func didMove(to view: SKView) {
  // ... Setup continued ...

  // Create a huge hidden background.
  // This is explained further in the taper part. We need this for the warpGeometryGrid.
  let bg = SKSpriteNode(color: .black, size: .init(width: 4000, height: 95))
  bg.zPosition = -1
  bg.isHidden = true

  // Mask with the crop node.
  let mask = SKSpriteNode(color: .red, size: .init(width: 400, height: 95))
  let crop = SKCropNode()
  crop.maskNode = mask
  crop.addChild(bg)
  crop.addChild(trail1)
  crop.addChild(trail2)

  // ... Setup continues ...
}

The huge background we create here is a story by itself that is related to SpriteKit's geometry warping behavior. So it will be explained further once we get to the taper section. We add it here as it needs to be a child to the crop node.

SKCropNode needs a mask that defines our cropping area. The mask is basically our window where we can see what's inside the crop node, and the size of the mask becomes the size of our effect. So the mask is of the same height as the trail texture so we can fully see it, but much less wide, as we will keep moving the trail texture and only want to see a part of it horizontally.

So after setting the mask, we just keep adding children (the trails and the background) that we want to see through the crop node.

override func didMove(to view: SKView) {
  // ... Setup continued ...

  // Keep moving the trails through the crop node.
  let move1 = SKAction.moveTo(x: 512, duration: 0)
  let move2 = SKAction.moveTo(x: -512, duration: 2)
  trail1.run(.repeatForever(.sequence([move1, move2])))
  let move3 = SKAction.moveTo(x: 512, duration: 0)
  let move4 = SKAction.moveTo(x: -512, duration: 2.5)
  trail2.run(.repeatForever(.sequence([move3, move4])))

  // ... Setup continues ...
}

We then need to move the trail texture. We use SKAction.moveTo(x:duration:) to add the texture movement. Each trail needs two move actions. The first action has a duration of 0 as it moves the texture back to its starting position. This is basically the wrap around.

And the second move action animates the texture to move to the other side of the visible area. The duration value here sets the speed. We put both move actions into a sequence that we repeat forever.

In this example we use two trails stacked on top of each other, so we move the second trail with a different duration to get a different speed so it adds visual variation.

Potentially, we could also offset the move x value for one of the trails for even more variation.

And there we have it, a parent node (the crop node) that can be moved in the game scene while a texture moves independently inside it that wraps around. This setup gives us the same behavior as the first of the two UV bullet points.

Fade the Edge

To fade out the edge of the effect, we will do pretty much exactly as theorized above. We'll take a gradient map image and multiply it on top of the effect.

override func didMove(to view: SKView) {
  // ... Setup continued ...

  let opacity = SKSpriteNode(imageNamed: "trailTexture-gradient")
  opacity.blendMode = .multiplyAlpha
  opacity.zPosition = 2

  // ... Setup continues ...
}

We prepare an object with the gradient texture and set its blendMode appropriately so we can fade out the edge of the effect. We will add the node to the effect hierarchy together
with the taper effect in the next step.

Another approach I've been considering is to use an SKShader that should be able to do the same thing, but which would be cleaner and more efficient.

Taper the Texture

It's time to deal with the tapering of the trail effect by using a SpriteKit implementation for the second bullet point from the list with UV behaviors we are trying to replicate.

The closest I've got is to use an SKEffectNode with warpGeometry.

override func didMove(to view: SKView) {
  // ... Setup continued ...

  // The effect node to warp.
  let effect = SKEffectNode()
  effect.addChild(crop)
  effect.addChild(opacity)

  // Create the tapered coordinates.
  let destinationPositions: [vector_float2] = [
    vector_float2(0, 5),   vector_float2(0.5, 0.9), vector_float2(1, -2.5),
    vector_float2(0, 0.5), vector_float2(0.5, 0.5), vector_float2(1, 0.5),
    vector_float2(0, -4),  vector_float2(0.5, 0.1), vector_float2(1, 3.5)
  ]
  let warpGeometryGrid = SKWarpGeometryGrid(columns: 2, rows: 2)

  // Apply the tapered effect.
  effect.warpGeometry = warpGeometryGrid.replacingByDestinationPositions(positions: destinationPositions)
  // Control the quality of the distortion effect.
  effect.subdivisionLevels = 4

  // ... Setup continues ...
}

We distort the trail by using SKWarpGeometryGrid. Basically, we just create a grid of coordinates where we can squeeze the right side of the node together, so when the trail moves over the effect node, it gets compressed on the right side while
it spreads out and widens on the left side.

This approach works fine if used isolated, but as with many SpriteKit things, it gets a tad more complicated when combining parts together.

Use the subdivisionLevels property of the effect node to get rid of distortion blockiness and get a much smoother and crisper look. Higher values do affect performance.

Do you remember this from before, when we created the huge background?

let bg = SKSpriteNode(color: .black, size: .init(width: 4000, height: 95))
bg.isHidden = true

Now is the time to talk about it. The huge, hidden, background is there to ensure that the warpGeometryGrid coordinates stay in put.

The warp does not respect the cropped area.

By having a larger than we need background, the warp will not move around. Otherwise, as the trails move over the node, it instead calculates the unit coordinates based on how
large it sees all nodes added together for each frame. The large background counters that behavior and helps it keep consistent.

It's not a pretty solution, but that's how far I've been able to take it with SpriteKit alone. Using a CIFilter might be worth exploring as an alternative option, a transform there might behave more consistent than using warpGeometry.

Talking about CIFilter, as we have an effect node created already, why not keep using it.

override func didMove(to view: SKView) {
  // ... Setup continued ...

  // Add an additional bloom on top of the effect.
  let bloomFilter = CIFilter(name: "CIBloom")!
  bloomFilter.setValue(5, forKey: "inputRadius")
  bloomFilter.setValue(1, forKey: "inputIntensity")
  effect.filter = bloomFilter

  // ... Setup continues ...
}

The effect node can take a CIFilter among its properties, so let's go ahead and use it to add a bloom filter to enhance the effect further.

Move the Full Trail Effect

With the entire effect layered up and organized in a hierarchy under the effect node, we can now simply move the trail wherever we need it to be my moving the effect node around.

override func didMove(to view: SKView) {
  // ... Setup continued ...

  // Move the entire projectile over the screen.
  effect.run(SKAction.moveTo(x: 700, duration: 3))

  effect.addChild(crop)
}

And that's all there is to it. We start an animation where we want the projectile to go and then add it to the scene.

In this article I've out of convenience, just added the setup inside the didMove(to:) method. It would make more sense to have this functionality in a trailEffect()->SKNode method that would setup the trail and return its node to have it instantiated on demand.

The returned node can then get the appropriate movement action assigned and then added to the scene.

Performance wise using SKEffectNode and SKCropNode can be heavy. Keeping the dimensions down on the effect should have a positive effect on performance.

Next Steps

Even though the fact that this solution can not compete with what you can do with the modern game engines out there, and also that the solution uncovers a few flaws (aka bugs) with SpriteKit, it can still provide a lot of power and usefulness for SpriteKit projects.

A dynamic trail VFX can be the building block and foundation of many different effects. Continuing building on the trails in this example, I'll add a head to the trails using something like an animated flare. On top of that, a small particle emitter could be added as the final layer, emitted some sparkling texture to help bring the effect to life.

Visual Debugging of GameplayKit GKComponent

Johan Steen — Tue, 12 Apr 2022 14:33:35 +0000

When coding games, it can be useful to be able to visualize values in real-time to monitor that algorithms behave as expected and that data is generated correctly. You don't want to feel that you are working against a black hole, hoping for the best that every part of the game works as intended.

Writing a test suite can help somewhat with this, or even sometimes just printing data to the console will do the trick. As games most of the time are a visual experience, getting visual feedback of behaviors during play testing can be extremely useful and time saving and to help feel confident that the implementations are solid.

If you use a game engine like Unreal or Unity, you get some stuff like this "for free" but when we code our own games with Swift in Xcode, we have to implement our own systems to handle the visualizing of crucial values in our games to check that all the parts work as intended.

Use Cases

As this is only intended to be used during development and testing, and will never be shipped to the players in release builds, there is no need to make something pretty.

The point of these visualizations is to simply show the data in an easy to understand manner so it can be analyzed that it works as intended.

I've been building systems for this to keep track of values like enemy healthpoints, simulated input pressure, generated movement paths and many more things.

Implementation Example

Let's study a concrete example, how this can be implemented using the Swift programming language. I'm basing this on using GameplayKit and SpriteKit, but it can easily be adopted to other frameworks.

Visual Debug Protocol

I rely heavily on the Entity Component System provided with GameplayKit, so most of my logic is contained within GKComponents. I'm using a custom protocol with GKComponent that I can implement for components that contain values that I need to analyze visually.

#if DEBUG
/// Protocol to enable/disable visualization of debug info in `GKComponent` objects.
protocol GKComponentDebuggable {
  /// Enable display of debug info.
  func enableDebugInfo()

  /// Disable display of debug info.
  func disableDebugInfo()

  /// Update loop to run debug specic logic.
  func debugUpdate(deltaTime seconds: TimeInterval)
}
#endif

With these three methods in my GKComponentDebuggable protocol I've been able to handle all my visualization needs I've had so far. enableDebugInfo() allows me to do
any initialization, in disableDebugInfo() I do the cleanup and in debugUpdate() I can handle any changes needed on a frame by frame basis.

Debug Core Setup

I handle the setup to enable, disable, and update the components that implement the GKComponentDebuggable in my main GameplayScene class. That is the class that takes care of all the core management of my game systems.

class GameplayScene {
  #if DEBUG
  /// Tracks the state if debug info shall be displayed.
  var debugInfoEnabled = true {
    didSet {
      debugInfoEnabledDidChange()
    }
  }

  /// Root layer of nodes to display movement graphs for debugging.
  let debugGraphLayer = SKNode()
  #endif

  override func didMove(to view: SKView) {
    // ... other initialization code would be here ...

    #if DEBUG
    // Add layers to display debug info to the scene.
    debugGraphLayer.zPosition = LevelLayer.debug.rawValue
    worldNode.addChild(debugGraphLayer)

    // Call didChange once so it can start with debug mode on if enabled.
    debugInfoEnabledDidChange()
    #endif
  }

  // ... And here continues the rest of my GameplayScene class ...
}

I'm using two properties. debugInfoEnabled allows me to define if I should start the game with debug info in an enabled state. When the value is changed, I call a dedicated debugInfoEnabledDidChange() method that handles all states when it comes to visual debug info. This is not limited to the things I show with GKComponentDebuggable as I also have other debug info I enable that are not related to specific components.

debugGraphLayer is a sub-root node that is available in the GameplayScene when making a Debug build, that all GKComponentDebuggable implementations can use to add their visuals to. This is set to a Z depth above everything else in the scene.

During the scene's life cycle, I initialize the debugGraphLayer node at the end of didMove(to:).

Okay, let's move on to interacting with the protocol.

#if DEBUG
// Extend GameplayScene to add methods to display debug info.
extension GameplayScene {
  /// Toggle display of debug overlay metrics.
  func debugInfoEnabledDidChange() {
    // ... other debug info handling....

    // Toggle debug info in components.
    for componentSystem in componentSystems {
      toggleDebugInfo(for: componentSystem.components)
    }
  }

  /// Toggles debug info for provided array of components.
  func toggleDebugInfo(for components: [GKComponent]) {
    for case let component as GKComponentDebuggable in components {
      if debugInfoEnabled {
        component.enableDebugInfo()
      } else {
        component.disableDebugInfo()
      }
    }
  }

  /// Update loop to run debug specic logic.
  func debugUpdate(deltaTime seconds: TimeInterval) {
    // Exit right away if we don't display debug info.
    if !debugInfoEnabled { return }

    // Update component systems.
    for componentSystem in componentSystems {
      for case let component as GKComponentDebuggable in componentSystem.components {
        component.debugUpdate(deltaTime: seconds)
      }
    }
  }
}
#endif

To keep it neat and tidy, I've added the debug handling code in an extension to the GameplayScene class that is only included in debug builds. I've three methods in this extension that manage the debug visualization.

debugInfoEnabledDidChange() is the method we call when we change the debugInfoEnabled property in the GameplayScene above, that handles toggling all different debug visualizations on and off.

In the method, I loop through the componentSystems property. Which is an array of [GKComponentSystem] that holds references to all currently active component systems in the game. That is the standard behavior of ECS in GameplayKit and a bit out of scope for me to go deeper into in this article.

This is the same array I loop through in my standard gameplay update loop, to update all components on each frame iteration.

override func update(_ currentTime: TimeInterval) {
  // ...

  for componentSystem in componentSystems {
    componentSystem.update(deltaTime: Time.deltaTime)
  }
}

Then we have toggleDebugInfo() which takes an array of GKComponents. This is the method we call from debugInfoEnabledDidChange where we pass in the components from each component system. But I also call this method manually when a new entity is added to the game during gameplay in debug mode, to enable visualization if required.

This method simply loops through the components and then calls the enableDebugInfo() or disableDebugInfo() on each component that has implemented the GKComponentDebuggable protocol.

And finally we have the debugUpdate(deltaTime:) method. Just like previous methods, this method loops through all components in each component system to see which ones implement GKComponentDebuggable, and for those that does, the debugUpdate(deltaTime:) method is called in the component.

This method is called last in the regular gameplay update loop when building a debug build.

override func update(_ currentTime: TimeInterval) {
  // ...

  #if DEBUG
  // Run update loop for debug info and overlay.
  debugUpdate(deltaTime: Time.deltaTime)
  #endif
}

Example

So with all this in place, let's see an example, of an actual implementation in a component.

#if DEBUG
// MARK: - Debug

extension EnemyAIComponent: GKComponentDebuggable {
  func enableDebugInfo() {
    guard let scene = renderComponent.node.scene as? GameplayScene else { return }

    // Configure path display
    let shape = SKShapeNode(path: self.path)
    shape.lineWidth = 3
    shape.strokeColor = .red
    shape.name = NodeName.componentDebug
    shape.position = startPos!

    // Store a reference to the entity in the path so we can find it later as it is displayed directly in the scene and not as a child of anything relating to the entity.
    shape.userData = ["entity": entity!]

    scene.debugGraphLayer.addChild(shape)
  }

  func disableDebugInfo() {
    guard let scene = renderComponent.node.scene as? GameplayScene else { return }

    // Find and remove the path in the graph layer.
    scene.debugGraphLayer.enumerateChildNodes(withName: NodeName.componentDebug) { [weak self] (node, _) in
      guard let entity = node.userData?["entity"] as? GKEntity else { return }

      if entity == self?.entity {
        node.removeFromParent()
      }
    }
  }

  func debugUpdate(deltaTime seconds: TimeInterval) {
    // Not needed in this component.
  }
}
#endif

In this example, I extend EnemyAIComponent to visualize the path on screen that an enemy gets assigned when spawned. So during the enableDebugInfo() phase, I take the path property already available in the component and draw the path to screen with a SKShapeNode.

I use disableDebugInfo() to remove the path when the entity is removed.

In this case the path does not change during the component's life cycle, so I don't need to call debugUpdate(deltaTime:). Otherwise, I'd have used this method to update the drawn path during the life span of the component.

Conclusion

There are of course many ways to skin a cat, but for me, I've found that this protocol-based approach together with the ECS system of GameplayKit has worked out great while keeping the code clean and easy to navigate.

While I just scratched the surface here of what one can do, I can imagine taking the concept further to a full-blown in-game console to be able to interact with the protocol and even other game data live during gameplay for even faster iterations.

And other times, a simple print statement to the Xcode console might be enough. I'd put my solution above somewhere in between, which fulfills the purpose fast and efficiently in many day to day scenarios to analyze game data.

Hypastorm Asset Workflow

Johan Steen — Mon, 11 Apr 2022 14:52:52 +0000

I've already covered different coding workflows in multiple previous posts as well as my game development file structure, so let's dig into my pipeline to create all the art related assets and my overall workflow to complete a game production.

All in all, the bulk of making Hypastorm took about one month for our tiny two person team, so I had to come up with some efficient workflows and time saving approaches.

Art

Blender and Photoshop was my main tools to get the graphics done for this game. The actual choice of applications is not very important, in the end it all basically end up as PNG files to be used as sprites in SpriteKit. I wanted to use graphics generated in code for some parts, but it turned out to grow the scope too much, so I canceled that for Hypastorm and added that on my list for things to make for a future game instead. So it is all just bitmap graphics in the asset catalog.

Game Objects

Almost every object in the game is initially created as a 3D model in Blender and then rendered out as a Sprite, or a Sprite Atlas if it needed animation.

The other half of my team, Phimrost Sitthikun, did the initial modeling and setup of each game object that required Blender and then I continued working on it to prepare it so it was "game-ready" before rendering.

From the start I designed a full pipeline around Blender where we could store things in a "library" and use a lot of referencing between scenes and files. I wanted to be able to reuse lighting and other things, so I for instance could adjust the lighting in one place and then batch re-render every object in the game in one go with the adjusted lighting.

That is a workflow that I'm used to and comfortable with in other 3D applications I have used in the past. I eventually got this to work in Blender, as it theoretically has every feature required to achieve this.

Unfortunately, Blender was not very stable.

One of my goals with the project was to get more into the world of Blender, so I really wanted Blender to work out and gave it more chances than I normally would give an application with issues. But it is simply not there yet. It is not production ready and extremely unreliable in certain scenarios.

So while the above mentioned setup worked in theory, in reality it turned Blender into a crash fest. Parts of scenes got corrupted. Reopening a Blender file relying heavily of linking between files was a lottery if it would work again or not, changing a view could be enough for a repeatable crash. More times than I can count the file eventually became corrupted and I had to manually repair it by extracting assets one by one from the .blend file or revert to an older version and redo a lot of work.

That quickly got boring and tedious after a few times.

Never in my career have I encountered a DCC tool that unreliable in some key areas. So while Blender impresses me in some scenarios, I can't rely on it in others.

So in the end I patched the assets enough via salvaged files to get the artwork I needed out of Blender. I've adjusted my 3D pipeline for the next game, and I have invested in Houdini as the core of the 3D workflow. Houdini has been a joy to work with so far. I felt right back at home after a few days with Houdini after weeks of rage quits with Blender.

Houdini is stable. I've never appreciated stability in an application as much as I did after a few weeks with Blender.

Anyway, when it comes to modeling, I find Blender very stable and have never run into any issues there. Perfectly fine workflow wise and stable wise. So Blender is the modeling tool in the pipeline for now. And maybe a render tool.

The short version, I wasted too much precious time recovering and repairing Blender files, when I used features that obviously are not yet stable enough to rely on in a production. Lesson learned and my pipeline is adjusted accordingly.

UI

I created every main UI element in Adobe Illustrator. The Asset Export panel in Illustrator was a huge help for an efficient workflow to streamline getting the art out of Illustrator and into the game.

By piping the output from the Asset Export via my Xcode Asset Catalog Generator tool I got every change I did in Illustrator to immediately update the Xcode Asset Catalog with the new version.

The same holds true for the game object assets that I got out of Blender, but I usually made some hand painted tweaks in Photoshop there before passing the asset on to the generator.

As Xcode 12 now supports SVG files in the asset catalog, I'm able to simplify this even further by just sending SVG files directly into the asset catalog as long as I have UI elements that are suitable as vector graphics. Which is what I am doing for the next game I'm working on.

UI Flow

With my Creative Cloud subscription, I have access to so many apps, many that I've never used or bothered to install. But now was the time to give Adobe XD a spin.

While I was not amazed with it, it got the job done. As the number of overlays and panels in the game grew, I needed an easy way to visualize the different screens and how to put it together. As I don't use any visual editor to make my games but do all these things in code, it was very helpful to have an overview in XD that I easily could edit and try new layouts with before translating it into code logic.

I did this quite late in the development of this game, but as I got quite some mileage out of XD, this is part of my workflow from the beginning on my new game.

Achievements

The achievement badges for Game Center was another interesting challenge where I ended up with a workflow, based on ideas from a post in Adobe Substance's blog, where I rely heavily on Substance Designer.

A workflow that has the potential to handle tons of more illustrations in a streamlined way to not get overwhelming or take ages to make adjustments to existing badges or when adding new badges, that should fit in with the chosen style.

Every badge starts in Blender as a very simple object. The object is only used to be able to get a height map out of Blender. Then the height map will be the source for the rest of the process towards a final badge.

I used Blender's compositor with a File Output node to get normalized height maps out of Blender suitable for this purpose.

In Substance Designer I import all the height maps from Blender. They are linked to Blender's output files, so a change in Blender will automatically update in Substance Designer as well.

By passing in the height maps into a node network that applies materials and other styling, every badge will get the same look and design and look great together when presented in the Game Center Achievements section for the player.

The final node in the Substance network is the PBR render node. That node could easily be replaced with a more stylistic arty output in a color scale for a completely different look, which I'm considering for my next game.

Anyway, I did this at the end of the development cycle and the setup was a breeze and worked more or less as intended right away. I was very happy with the setup and I can easily add more achievements by just making a simple model and add the new additional height map to the Substance node network.

Audio

Initially I started using Adobe Audition for sound effects as I have access to it via my Adobe Creative Cloud subscription. I quickly dropped going down that road and Instead I ended up using Apple's Logic Pro X for everything. It was my first time with Logic Pro X, or actually my first time using any kind of modern DAW for audio creation.

Last time I was doing something down these lines my applications of choice were ProTracker and AudioMaster on the Amiga. Time flies. The evolution from old Amiga software to all the possibilities a modern DAW offers combined with all the incredible instruments you can get these days are amazing. Me, who hasn't followed the progress over the years, was stunned.

Music

As mentioned, Logic Pro X was the core of my audio production and I equipped it with some extra synthesizers that I purchased from Arturia.

I created all instruments with Arturia's SEM V for both the title song and the in game song. SEM V is quite an amazing reproduction of Oberheim's legendary SEM synthesizer.

I simply just love this synthesizer, the sound characteristics and the analog GUI replication of the real original SEM. That's eye candy that I get hooked on.

I began creating the music and sound effects very late into the production and I would have liked to have used more time for it. I felt that I rushed it slightly, as I spent a major part of my audio time learning how to use Logic Pro X and SEM. Still, I think the audio turned out good enough to do the job.

For my next game I will keep making the audio in parallel with the rest of the production, so I don't have a huge amount of sounds to create towards the end. And also, now I know my way around a DAW, so I will not have to use time to learn the actual applications.

I might take the opportunity to explore a different instrument next time, I'm currently eying Analog Dreams from Native Instruments, to get the lovely 80's movie synthesizer sound as the foundation for my next game's soundtrack. Either that or Roland's JUPITER-80 synthesizer, which is virtualized by Arturia.

Sound Effects

For sound effects I ended up sampling a few sounds myself and the rest I created digitally with Alchemy. Alchemy is included with Logic Pro X and is a powerful synthesizer that I haven't spent enough time with, I was too eager to play with the synthesizers I got from Arturia.

Anyway, Alchemy turned out to be a good companion to get sound effects created. I should dig a bit deeper into it next time.

The sounds I recorded myself, I captured with my old trusty Zoom H4N portable recorder, which I imported into the new sampler that comes with the Logic Pro X 10.5 update.

For my next game I will definitely spend more time with the sampler and do more of my own recordings. I like the feeling to start with my own analog sounds as the source for the effects. On top of that, I'm also tempted to try Massive from Native Instruments as an alternative to Alchemy.

The options of cool software instruments available these days are endless and they are all too fun to play around with.

Audio Formats

Once the sounds are ready to go into the game, I've made a batch processing tool that converts the audio to optimized formats for Apple's devices.

The music I keep as Stereo 48kHz, AAC. The music is actually responsible for most of the game's download size. Probably over 50% of the game size is the audio, on the top of my head.

The sound effects I convert to uncompressed Core Audio Format, little endian in 16 bit, Mono, 24kHz. I couldn't really hear any difference between 24kHz and 48kHz for the sound I've made for the game, so I opted to save some space and processing power to go with 24kHz.

Progress Tracking

There are so many productivity systems out there these days, all fighting for your attention and promising to be the magic bullet to succeed with your projects. Hypastorm is not the only game I've been working on, so I've had quite some time to give many of the usual productivity suspects a fair run during my game development endeavors so far. But as I've progressed with the games, I've simplified, and then simplified more, how I manage my tasks. Right now I'm finding it to be more efficient with a few simple lists of tasks in Things combined with spreadsheets.

I actually do like kanban boards and related workflows, which is why I've tried to apply it on my game projects. I've used Jira, Trello and other similar systems for years when I've been developing apps with larger teams. In such cases, those systems are excellent! But I found out when I'm basically just a solo developer with an "assistant" that work on different things than me, it felt overkill for things I could organize and overview easier in plain old lists.

So instead I make an area in Things for each game and then add a project for every hat I have to wear during the development the game. Naturally that is Code, Art and Audio but also things like Ideas, Marketing and QA gets their own projects.

In each project I organize tasks under headings. So for instance in code I make a heading for each planned build / milestone, so I can track what to code and fix next, and then I can simply archive the heading when done.

It just works out to be very fast and reliable. I have my tasks available on all my devices in a native app, so I can sort and organize my tasks whenever I have some spare time. While I was happy enough with Things instead of a kanban board to manage my tasks, one thing I really missed is attachment support. I sort of patched that with using Bear as an attachment "add-on" for Things. That's not perfect, not even close.

Other useful applications I use are Apple Numbers where I track all the art and audio assets I need to create, in spreadsheets. I actually rely on Numbers quite a bit, everything from time tracking, balancing enemies and weapons to planning achievements and their difficulty versus rewards.

MindNode I use for diagramming. It's not really a diagramming app, but I found it to work out quite well for that purpose, and I like it way better than the different web based diagramming apps I've tried. I visualize my workflows in MindNode and I also design things like decision trees for game AI.

And finally I use a dedicated game development journal in Day One to note down my personal thoughts after each day of game work, so I get obstacles, solutions, victories and defeats on record for me to maybe evaluate later. I like to record a short video for each entry if it makes sense as I enjoy seeing the game's evolution by browsing the videos when looking back.

Conclusion

Hopefully this overview of my asset workflow has been helpful and given you some ideas for your projects that you can take with you and use.

For me, there were many lessons learned during the production of this game and I now have a much better and more effective foundation when I'm working on my next game. I'm sure I'll run into many new things to solve in that production too, and keep refining and improving my pipeline further.

Finally, the game is available in the App Store for iPhone, iPad, Apple TV and Mac, if you'd like to give it a spin.

Gamedev File Structure

Johan Steen — Sun, 10 Apr 2022 08:08:55 +0000

File structures for game development. Not as sexy as adding a new effect to the game's visuals. Nonetheless, it needs to be dealt with.

When I was starting my first game last year I was looking for this type of information for ideas and inspiration how to organize my projects, but I couldn't find any good resources. That rings extra true when you narrow it down to game development with Swift using Xcode.

This is a breakdown of how I organized my latest game project in Xcode, version control and storage.

Ever-evolving

I recently finished my second game, Hypastorm, after having put my first game on hold for a while. Which kinda makes my second game the first, but more on that in another post to come.

I started the second game as I felt I had learned so much since I began working on the first game. I wanted to try a new structure of my approach to game development on a new fresh canvas. I will now go back and reapply this structure to my first game.

So, my game project structure did evolve a lot between the two games. And it is ever-changing and as I've now started pre-production on my third game, where I'm fine-tuning, streamlining and revising it even more.

But for now, let's focus on how the second game ended up being handled.

Code

I use git to version control the main code base and I keep the repository origin on GitHub.

This has worked out fine, as the games I've been working on are not that heavy on art and sound. The repository sizes has a small footprint.

The day I start a game that relies on more large assets I'll consider using Git LFS as the next step up.

In Xcode I organized my last game like this:

Game Repository
+-- Shared
    +-- Entities
    +-- Components
    +-- Scenes
    +-- UI
    +-- Audio
    +-- Log
    +-- Utilities
    +-- Preload
    +-- Assets
    +-- Level.swift
    +-- ECS.swift
    +-- GameData.swift
    +-- GameConfig.swift
    +-- GameManager.swift
    +-- SceneManager.swift
+-- iOS
+-- tvOS
+-- macOS
+-- Nexus
+-- GameMath
+-- Tools

A quick breakdown what goes in each folder/file above.

Entities / Components: The ECS, unique game mechanics.
Scenes: Different game scenes with all possible game states, including the main finite game state machine.
UI: The HUD, all-in game overlays and UI elements like buttons and labels.
Audio: My audio players and mixer. In my next game these are moved to the engine framework.
Log: Debug logging and plenty of signposts for measuring performance.
Utilities: Convenience methods and different extensions of Apple's frameworks.
Preload: Handles preloading from disk and the decoding of assets into memory and onto the GPU. This is now mature enough to have been graduated into my engine framework for the next game.
Assets: Graphics, sound effects, music, level data, json... You name it, it's here.
Level.swift: Constructs a playable level from data on disk.
ECS.swift: Game specific extensions of my ECS.
GameData.swift: Data persistent between levels.
GameConfig.swift: A central place to tweak game config and stats for entities.
GameManager.swift: Where it all begins...
SceneManager.swift: Fade in / fade out. Handles adaptation to different screen sizes. Yada yada yada...
iOS / tvOS / macOS: The unique code for each platform target.
Nexus: My lightweight game engine framework. Reduces common boilerplate code between games.
GameMath My math library. Fills in the blanks of all necessary math operations not covered by Apple's frameworks. Did I hear trigonometry?
Tools: Game specific tools. Mainly command line. Converters, generators, like my Xcode Asset Catalog Generator, and automation.

I have an old Mac mini with Xcode server that runs a small test suite for each platform when I make a new commit to the repository as an extra safety net to reduce the risk of breaking things.

Assets

The assets that are in the code repository above are the final, small, optimized exported versions. But then you need a location to work on the original source assets and store them, with versioning.

I've chosen Git LFS for that and I keep the origin repository on Azure DevOps as they have a generous free tier that works for me.

Assets Repository
+-- Art
    +-- Entities
    +-- FX
    +-- Output
    +-- UI
+-- Audio
    +-- Title Music
    +-- In Game Music
    +-- Sound Effects

A short breakdown of what might be noteworthy of the above structure.

Art: Here goes the Photoshop, Blender, Illustrator and other art files. The Output directory is where I send exported/rendered versions of assets. I then have my conversion script in Tools in the code repository that builds the Xcode asset catalog from here with optimized versions for different devices and screens.
Audio: Not much to say about this, I store all audio related work here. I make music and sound effects in Logic Pro X and I found saving the work using Organize as folder instead of as package, when saving the project, a bit more friendly when working with version control.

The Rest

Apart from the files that makes up what will become the game, there's a bunch of other types of files being generated during the game's development cycle.

I've chosen to keep them on an ordinary cloud based sync service. I'm using iCloud Drive as I had a huge amount of unused storage available there. Otherwise I'd considered Dropbox.

This could go in version control instead, but I felt that using a cloud drive for this made more sense. I can access the files everywhere, if I get any ideas when I'm out and about I can open the documents on my iPad and edit them on the go. Or use my Apple Pencil to illustrate ideas or flows.

On top of that, it makes it easier to share this folder with non-coding people that I might give access to, for additional input or help with these parts.

iCloud Drive
+-- Concept Art
+-- Documentation
+-- Marketing

And the breakdown.

Concept Art: My early initial drawings and collections of inspirational art and mood boards. PureRef is a great tool to organize inspirational art.
Documentation: Game Design Documents, my time log and asset tracking spreadsheets.
Marketing: Videos and screenshots for Apple Store. Videos to share on social media. I actually haven't really had time to do any marketing, at all. Additional content will likely appear here later on. For now I've put my focus mainly on getting games done and build personal gamedev habits and workflows that works for me.

Conclusion

I hope you found the breakdowns of how I organized my last game project helpful. You might have got some useful ideas from how I organize my game projects that you can use or tweak.

As I mentioned earlier, it is ever-evolving, and I've made multiple adjustments for the next game that I've started working on. I might revisit this article and make an updated version in a year from now.

Keep coding!