SwiftGodot

!Platforms

SwiftGodot provides Swift language bindings for the Godot 4.6 game
engine using the new GDExtension system. Support for older versions of Godot is available on branches.

SwiftGodot can be used to either build an extension that can be added
to an existing Godot project, where your code is providing services
to the game engine, or it can be used as an API with SwiftGodotKit
which embeds Godot as an application that is driven directly from
Swift.

Tutorials and Documentation:

• Meet Swift Godot
• SwiftGodot API Documentation
• Differences to GDScript
• Tutorials and walkthroughs
• SwiftGodot port of KenneyNL's StarterKit 3D Platformer
• WIP: SwiftGodot port of C# Udemy tutorial: GridBasedPuzzleGameTutorial
• SwiftGodot template project with a Editor plugin allowing recompiling with a single button tap
• Template to create your own bridge iOS/MacOS APIs to Godot
• Godot Apple Plugins is a good example of wrapping iOS/MacOS APIs for use in Godot.

Of interest to the community:

• Running Godot in VisionPro using GodotVision
• Example Godot on Vision GodotVisionExample

Driving Godot from Swift has the advantage that on MacOS you can
debug your code from Xcode as well as the Godot code.

https://user-images.githubusercontent.com/36863/232163186-dc7c0290-71db-49f2-b812-c775c55b8b77.mov

Why SwiftGodot?

• No game stutters caused by GC, unlike C#.

• Learn more: [Swift Godot: Fixing the Multi-million dollar

mistake](https://www.youtube.com/watch?v=tzt36EGKEZo)

• Easy to surface Swift APIs to Godot, for example GodotApplePlugins

Tiny and Large

When compiled, you can choose to use and reference a minimal SwiftGodot that
only contains support for the core variant types, Object, ClassDB and RefCounted
in the target SwiftGodotRuntime, or you can choose to use the traditional
SwiftGodot target that contains the entire Godot API and is a superset of SwiftGodotRuntime.

[Learn More about the
rationale](https://github.com/migueldeicaza/SwiftGodot/discussions/741).

Quickly Getting Started

The SwiftGodotKick project can create a skeleton template
GDExtension with Swift, as well as a standalone SwiftGodotKit project that can be used to quickly
iterate on your game on MacOS.

SwiftGodotCLI is a command-line tool that lets you build and run
SwiftGodot code directly without any manual Godot project setup.

Supported Platforms

Currently, SwiftGodot can be used in projects targeting the iOS, Linux, macOS,
or Windows platforms. It may be possible to target additional platforms, but
testing for other platforms has not been completed and stability cannot be
verified at this time.

Consuming SwiftGodot

There are two ways of consuming SwiftGodot. Reference this repository from
SwiftPM for a complete source build on any supported platform, or use the
prebuilt Apple-platform package from
SwiftGodotBinary for faster
iteration on macOS and iOS. See Binary releases for the
published slices and release process.

SwiftGodot currently requires Swift 6.3.

Working with this Repository

You should be all set by referencing this as a package from SwiftPM
but if you want to just work on the binding generator, you may want
to open the Generator project and edit the okList variable
to trim the build times.

Driving Godot From Swift

To drive Godot from Swift, use the companion <code class="ra0-md-code">SwiftGodotKit</code>
module which embeds Godot directly into your application, which
allows you to to launch the Godot runtime from your code.

Creating an Extension

Creating an extension that can be used in Godot requires a few
components:

• Your Swift code: this is where you bring the magic
• A .gdextension file that describes where to find the requires

Swift library assets

• Some Swift registration code and bootstrap code
• Importing your extension into your project

Your Swift Code

Your Swift code will be compiled into a shared library that Godot
will call. To get started, the simplest thing to do is to
create a Swift Library Package that references the Swift Godot
package, like this:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MyFirstGame",
    products: [
        .library(name: "MyFirstGame", type: .dynamic, targets: ["MyFirstGame"]),
    ],
    dependencies: [
        .package(url: "https://github.com/migueldeicaza/SwiftGodot", branch: "main")
    ],
    targets: [
        .target(
            name: "MyFirstGame",
            dependencies: ["SwiftGodot"])]
)

The above compiles all of SwiftGodot. On Apple platforms, you can instead add
the prebuilt SwiftGodotBinary
package and select its SwiftGodot product. Client code still uses
import SwiftGodot, including macros such as @Godot and @Export.

The next step is to create your source file with the magic on it,
here we declare a spinning cube:

import SwiftGodot

@Godot(.tool)
class SpinningCube: Node3D {
    public override func _ready () {
        let meshRender = MeshInstance3D()
        meshRender.mesh = BoxMesh()
        addChild(node: meshRender)
    }

    public override func _process(delta: Double) {
        rotateY(angle: delta)
    }
}

Additionally, you need to write some glue code for your
project to be loadable by Godot, you can do it like this:

/// We register our new type when we are told that the scene is being loaded
func setupScene (level: ExtensionInitializationLevel) {
    if level == .scene {
        register(type: SpinningCube.self)
    }
}

// Export our entry point to Godot:
@_cdecl("swift_entry_point")
public func swift_entry_point(
    interfacePtr: OpaquePointer?,
    libraryPtr: OpaquePointer?,
    extensionPtr: OpaquePointer?) -> UInt8
{
    print ("SwiftGodot Extension loaded")
    guard let interfacePtr, let libraryPtr, let extensionPtr else {
        print ("Error: some parameters were not provided")
        return 0
    }
    initializeSwiftModule(interfacePtr, libraryPtr, extensionPtr, initHook: setupScene, deInitHook: { x in })
    return 1
}

Alternatively, you can use the #initSwiftExtension macro:

import SwiftGodot

#initSwiftExtension(cdecl: "swift_entry_point", types: [SpinningCube.self])

Also, you can use EntryPointGeneratorPlugin that will scan the target source files and generate an entry point called swift_entry_point with types array mentioning all classes with @Godot macro attached. All you need is to add plugins entry in your Package.swift as below:

let package = Package(
    name: "MyFirstGame",
    products: [
        .library(name: "MyFirstGame", type: .dynamic, targets: ["MyFirstGame"]),
    ],
    dependencies: [
        .package(url: "https://github.com/migueldeicaza/SwiftGodot", branch: "main")
    ],
    targets: [
        .target(
            name: "MyFirstGame",
            dependencies: ["SwiftGodot"],
            // this plugin will generate a source file visible to compiler with '#initSwiftExtension(cdecl: "swift_entry_point", types: [SpinningCube.self])'
            plugins: [
                .plugin(name: "EntryPointGeneratorPlugin", package: "SwiftGodot")
            ]
        )
    ],
)

Bundling Your Extension

To make your extension available to Godot, you will need to
build the binaries for all of your target platforms, as well
as creating a .gdextension file that lists this payload,
along with the entry point you declared above.

You would create something like this in a file called
MyFirstGame.gdextension:

[configuration]
entry_symbol = "swift_entry_point"
compatibility_minimum = 4.2

[libraries]
macos.debug = "res://bin/MyFirstGame"
macos.release = "res://bin/MyFirstGame"
windows.debug.x86_32 = "res://bin/MyFirstGame"
windows.release.x86_32 = "res://bin/MyFirstGame"
windows.debug.x86_64 = "res://bin/MyFirstGame"
windows.release.x86_64 = "res://bin/MyFirstGame"
linux.debug.x86_64 = "res://bin/MyFirstGame"
linux.release.x86_64 = "res://bin/MyFirstGame"
linux.debug.arm64 = "res://bin/MyFirstGame"
linux.release.arm64 = "res://bin/MyFirstGame"
linux.debug.rv64 = "res://bin/MyFirstGame"
linux.release.rv64 = "res://bin/MyFirstGame"
android.debug.x86_64 = "res://bin/MyFirstGame"
android.release.x86_64 = "res://bin/MyFirstGame"
android.debug.arm64 = "res://bin/MyFirstGame"
android.release.arm64 = "res://bin/MyFirstGame"

In the example above, the extension always expects the
platform specific payload to be called "MyFirstGame",
regardless of the platform. If you want to distribute
your extension to other users and have a single payload,
you will need to manually set different names for those.

Installing your Extension

You need to copy both the new .gdextension file into
an existing project, along with the resources it references.

Once it is there, Godot will load it for you.

Using your Extension

Once you create your extension and have loaded it into
Godot, you can reference it from your code by using the
"Add Child Node" command in Godot (Command-A on MacOS)
and then finding it in the hierarchy.

In our example above, it would appear under Node3D, as it
is a Node3D subclass.

Community

Join the community on Discord

The old community is still around, but it clears the history in Slack.

Contributing

Have a bug fix or feature request you'd like to see added? Consider contributing! Join our community to get started.