Pádraig on the Computer

SwiftSyntax Code Generation Notes

2023-10-17T22:00:25+00:00

I used SwiftSyntax in my SceneGen tool. The syntax code can easily get messy and hard to follow, so I’ve been following these patterns in my renderer code to keep it neat and simple:

Prepare the Data First

Process any data that the renderer functions will need separately from any code that touches SwiftSyntax. Any fetching, parsing, mapping should be done outside the renderer. The renderer functions should just take a model with everything neatly arranged for it and output the rendered code.

This helps keep this code simpler, because it’s only about the structure of the source code you’re building.

Use Extensions to Simplify

If you find you have a few lines of SwiftSyntax code just to do something very simple, then extract it into an extension, especially if it’s repeated in a few places.

Make these extensions private, they should be specific to your implementation here and won’t usually be re-usable in the rest of the project.

When writing extensions consider using concrete types for the arguments, like TypeSyntax, instead of protocols like TypeSyntaxProtocol. This will allow you to leverage ExpressibleByStringLiteral so you can just pass a string at the call-site.

Here’s an example — I often want to tag a struct as conforming to a protocol, so I added this extension, and now I can call ExtensionDeclSyntax.conform("MyStruct", to: "Equatable") to do it in one line of easily understood code.

/// Adds a conformance to a type
/// Usage: `ExtensionDeclSyntax.conform("MyStruct", to: "Equatable")`
private extension ExtensionDeclSyntax {
  static func conform(
    _ type: TypeSyntax, 
    to conformType: TypeSyntax
  ) -> ExtensionDeclSyntax {
    ExtensionDeclSyntax(
      leadingTrivia: .newline,
      extendedType: type,
      inheritanceClause: InheritanceClauseSyntax(
        inheritedTypes: [InheritedTypeSyntax(type: conformType)]
      )
    ) {}
  }
}

Isolate SwiftSyntax to One File

Keep your SwiftSyntax quarantined. For public functions, don’t use any SwiftSyntax types as parameters or return values. I have a single ~250 line file with import SwiftSyntax in my project and it contains everything I need to understand how rendering is working.

Find a Balance when Specifying Syntax

Don’t go to extremes to specify everything as granularly as possible. When rendering a utility function with no interpolation in it, favour using DeclSyntax() with a block string.

Conversely, if you have big block string with a lot of interpolation happening, consider breaking it up into more explicit pieces of syntax.

SceneGen for SwiftGodot

2023-10-17T20:00:25+00:00

I’ve been enjoying tinkering with Godot and SwiftGodot lately. Following tutorials while translating all the GDScript parts into Swift has a nice side-effect of keeping my attention more focused, so I am not just zoning out and copying everything from the tutorial.

This week I released a code generation tool that lets me leverage Swift’s type safety when referencing objects in Godot that are usually referenced using raw strings.

Background

Godot game designers build scenes in the Godot editor. A scene is a tree of nodes with some properties that are configured in the editor. A node could be a sprite, a collision detector, or a path to follow. Nodes are built up into scenes that represent each game object, so maybe a spaceship for the player, a level map, or the heads-up-display interface.

Most scenes in a game need some behaviour; e.g. when a bullet scene collides with a rock scene, the bullet should disappear and the rock should explode. To add behaviour to a scene, the programmer must write some code.

Example

Lets say a game programmer wants to handle when the game ends; they want to make the player disappear.

func gameEnd() {
  guard let player = getNodeOrNull(
    path: "Node/PlayerSprite"
  ) as? Sprite2D else {
    print("didn't find a player node :(")
      return
  }
	
  player.hide() 
}

This code calls getNodeOrNull to get the node at path “Node/PlayerSprite” in the scene tree. It then attempts to cast it to a Sprite2D object. This is very brittle and will break if the programmer:

Moves the PlayerSprite to have a different parent node in the tree
Renames PlayerSprite.
Mistypes the name.
Changes the type of Sprite2D to something else.

It’s common to do all of these when making a game. These problems are particularly bad because they occur at run time. Since paths are just strings even our IDE can’t help us by suggesting the correct spelling of node names.

So I wrote a tool to make this better! SceneGen will generate strongly typed descriptions of all the nodes in each scene, so now, you can do:

func gameEnd() {
  node(.playerSprite).hide() 
}

Here .playerSprite is a reference to a generated struct that knows the path to "Node/PlayerSprite" and knows that it is a Sprite2D type object, so there’s no longer a need to supply these at the call-site.

The node() function is scoped tightly to only the nodes on the scene you’re working on so IDE suggestions will provide the exact names.

If you re-arrange, rename or change the types of any of these nodes in the editor, you’ll get compile-time errors exactly at the point in your code that needs to be fixed, instead of run time crashes / failures.

Conclusion

Having my IDE be directly aware of my scenes has been a huge improvement. I’m spending much less time debugging crashes and more time enjoying learning how to make games.

NSView Subviews

2021-09-05T20:09:25+00:00

In a custom NSView, when building up a list of subviews, it is typical to call the addSubview function once for each subview. A neater way to do this is to just set the subviews array directly. The NSView internals are clever enough to do any of the extra book-keeping required, just as if you had called addSubview each time.

For example:

let titleView = NSTextField(…)
let detailText = NSTextField(…)
let saveButton = NSButton(…)

subviews = [titleView, detailText, saveButton]

I like this because it’s a little more concise, and it also reminds me to think about the order of the subviews. Thanks to Jeff Nadeau for pointing this out on Twitter!

Autolayoutable

2021-09-02T19:09:25+00:00

In AppKit (or UIKit) projects where I’ve decided to implement user interfaces strictly in code, rather than through storyboards or xibs, it gets tiresome to repeatedly type the following code:

let view = NSView(frame: .zero)
view.translatesAutoresizingMaskIntoConstraints = false

Here’s a little snippet I’ve been using to cut down on this somewhat:

extension NSView {
  static func autolayoutable() -> Self {
	let view = Self(frame: .zero)
	view.translatesAutoresizingMaskIntoConstraints = false
	return view
  }
}

// Example usage when creating an NSTableView
let tableView = NSTableView.autolayoutable()

This works for almost all views I create but occasionally I want to use some of the convenience initializers for NSButton or NSTextView like labelWithString. In those cases, I don’t use the method above, I just disable autosizing manually.

View Controllers without XIBs

2020-10-25T22:30:25+00:00

Cutting down on boilerplate is a good way to make a code base more maintainable and more pleasant to work with.

The NSViewController class supports a variety of layout options. It can be used with XIBs, Storyboards or with views that define their layout in code directly. Additionally there are multiple layout systems: developers might use Auto Layout, Auto Resizing, or both. One tactic for reducing boilerplate is to choose which of these technologies you wish to use, and then simplify NSViewController’s interface down to just the parts you need.

In this post, I’ll define a tiny NSViewController class that we can use as a superclass throughout the rest of a project. My choices are: We’ll write all layout in code, no XIBs or Storyboards at all. Additionally, we will use Auto Layout everywhere instead of Auto Resizing.

–

With these simplifying assumptions we can now mitigate the following annoyances that we’ll face for every NSViewController subclass we create:

Write a loadView() override which will probably be a boilerplate-y one liner every time.
Access the typed view subclass from the view controller
Gaze upon this designated initializer init(nibName nibNameOrNil: NSNib.Name?, bundle nibBundleOrNil: Bundle?) in all its clunky irrelevance to our layout choices.
Add mandatory boilerplate to implement init?(coder: NSCoder) which exists solely for decoding XIBs… which we are not using at all.

–

Since the type of NSViewController’s view property is NSView, not the type of our own view subclass, accessing custom methods and properties on our specific view class will be our first problem.

Swift Generics give us a nice way to solve this. We can define the view’s actual type in a new view controller superclass that we’ll use throughout the project.

class XiblessVC<View: NSView>: NSViewController {
  override func loadView() {
    view = View(frame: .zero)
  }
  
  var contentView : View {
    view as! View
  }
}

This provides strongly typed view access, and it saves us having to implement loadView() everywhere. We can also solve the “ugly designated initializer” point with a clean custom initializer to call the designated initializer

  init() {
    super.init(nibName: nil, bundle: nil)
  }

And finally, by annotating the NSCoder initializer using @available, we won’t need to implement this required method in our subclasses.

  @available(*, unavailable)
  required init?(coder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
  }

Here is a quick example of what a view controller might look like if we used NSViewController directly.

class ClockViewController : NSViewController {
  var clockView : ClockView?
  
  init() {
    super.init(nibName: nil, bundle: nil)
  }
  
  required init?(coder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
  }
  
  override func loadView() {
    view = ClockView(frame: .zero)
    clockView = view 
  }
  
  override func viewDidLoad() {
    clockView.date = Date()
  }
}

With XiblessVC as our view controller superclass, we can slim all of that down to something like this:

class ClockViewController : XiblessVC<ClockView> { 
  override func viewDidLoad() { 
    contentView.date = Date()
  }
}

As you can see, the use of this superclass gives us a considerable reduction in boilerplate on every view controller in our project, and encourages consistency with our layout decisions across the project.

There are some drawbacks:

It’s ugly to have a custom view controller superclass used everywhere, rather than using AppKit objects directly.
New developers on the codebase might take a bit longer to pick up what’s going on.
Developers may be tempted add additional features to the superclass, exacerbating the above issues.
Using Generics like this requires the views to have the same access control level as the view controller though, so developers lose the ability to keep custom views private in the same file as the view controller.

I think the trade-off here is worth making though, as long as we keep the superclass simple and focused on our goals: reducing boilerplate and enforcing layout scheme consistency.