https://github.com/michael94ellis/swiftuijoystick
An Open Source Joystick library for SwiftUI, Swift, iOS apps
https://github.com/michael94ellis/swiftuijoystick
cocoapods ios ios-app ios-swift joystick joystick-control joystick-library pods podspec spm swift swift-library swiftui swiftui-library
Last synced: 5 months ago
JSON representation
An Open Source Joystick library for SwiftUI, Swift, iOS apps
- Host: GitHub
- URL: https://github.com/michael94ellis/swiftuijoystick
- Owner: michael94ellis
- License: mit
- Created: 2021-12-04T18:35:38.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-07-28T00:19:51.000Z (7 months ago)
- Last Synced: 2025-08-24T22:11:38.680Z (6 months ago)
- Topics: cocoapods, ios, ios-app, ios-swift, joystick, joystick-control, joystick-library, pods, podspec, spm, swift, swift-library, swiftui, swiftui-library
- Language: Swift
- Homepage:
- Size: 1.64 MB
- Stars: 42
- Watchers: 1
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SwiftUIJoystick đšī¸
## A customizable Joystick made with SwiftUI
## Create your own Base and Thumb/Handle view using SwiftUI
[](https://github.com/michael94ellis/SwiftUIJoystick)
[](https://cocoapods.org/pods/SwiftUIJoystick)
[](https://opensource.org/licenses/MIT)
- [Examples](#examples)
- [đ˛ Installation](#-how-to-install-%EF%B8%8F)
- [Swift Package Manager](#swift-package-manager-spm)
- [Cocoapods](#cocoapods)
- [đ How to use](#-how-to-use)
- [Example Code](#example-code)
- [đ How to Customize](#-how-to-customize)
- [Setup Joystick Monitor](#setup-a-joystick-monitor)
- [Use Joystick Builder](#option-1)
- [Use Joystick Recognizer](#option-2)
- [Joystick Parameters](#parameters)
- [đ¨âđģ Contributors](#-contributions)
- [âī¸ Author](#-authors)
- [đ License](#-license)
## Features
* Customizable background and thumb/foreground
* Normal Joystick Example
* Locking Joystick Example
* Polar or XY Coordinates
View these examples to see how to make your own Joystick!
(View Code Example)
(View Code Example)
(View Code Example)
# đ˛ How to Install đšī¸
### Swift Package Manager SPM
Add this repository's URL
`https://github.com/michael94ellis/SwiftUIJoystick`
### Cocoapods
Add this line to your podfile
`pod SwiftUIJoystick`
# đ How to use
### Example Code:
### Ready to Copy, Paste, and Use (after install with SPM or Pods)
```Swift
// An example Joystick
// Copy this example and modify it
import SwiftUI
import SwiftUIJoystick
public struct Joystick: View {
/// The monitor object to observe the user input on the Joystick in XY or Polar coordinates
@ObservedObject public var joystickMonitor: JoystickMonitor
/// The width or diameter in which the Joystick will report values
/// For example: 100 will provide 0-100, with (50,50) being the origin
private let dragDiameter: CGFloat
/// Can be `.rect` or `.circle`
/// Rect will allow the user to access the four corners
/// Circle will limit Joystick it's radius determined by `dragDiameter / 2`
private let shape: JoystickShape
public init(monitor: JoystickMonitor, width: CGFloat, shape: JoystickShape = .rect) {
self.joystickMonitor = monitor
self.dragDiameter = width
self.shape = shape
}
public var body: some View {
VStack{
JoystickBuilder(
monitor: self.joystickMonitor,
width: self.dragDiameter,
shape: .rect,
background: {
// Example Background
RoundedRectangle(cornerRadius: 8).fill(Color.red.opacity(0.5))
},
foreground: {
// Example Thumb
Circle().fill(Color.black)
},
locksInPlace: false)
}
}
}
```
# đ How to customize
## Start by making a JoystickMonitor
You can subscribe to changes
### Use a JoystickBuilder to build your own Joystick Controls' Background/Base and Thumb/Foreground views
## Setup a Joystick Monitor
#### Setup the observer JoystickMonitor and width of the joystick
```
@StateObject private var monitor = JoystickMonitor(width: 100)
private let draggableDiameter: CGFloat = 100
```
## Option 1
#### Create the Joystick using the Joystick Builder
Joystick Builder applies the joystickGestureRecognizer
```
JoystickBuilder(
monitor: self.joystickMonitor,
width: self.draggableDiameter,
shape: .rect,
background: {
// Example Background
RoundedRectangle(cornerRadius: 8).fill(Color.red.opacity(0.5))
},
foreground: {
// Example Thumb
Circle().fill(Color.black)
},
locksInPlace: false)
```
## Option 2
#### Create your own Joystick tracking View with the JoystickRecognizer
Apply the joystickGestureRecognizer to any of your views to receive updates on the monitor
```
YourView()
.joystickGestureRecognizer(monitor: self.joystickMonitor,
width: self.width,
shape: self.controlShape,
locksInPlace: self.locksInPlace)
```
### Parameters
| parameter | type | description | default |
| --------- | --------------- | ------------------------------------------------------------------------------ | -------- |
| monitor | JoyStickMonitor | ObservableObect that publishes the Joystick control's XY and Polar coordinates | no |
| width | CGFloat | The width or diameter of the Joystick control | no |
| | | Output values will be from 0-width | |
| shape | JostickShape | The shape of the Joystick's hitbox area, rectangluar or circular Valid input: `.rect` or `.circle` | no |
| background | some View | Any View type input can be put here to create a background for the Joystick | no |
| foreground | some View | A View for the thumb or foreground of the Joystick | no |
| locksInPlace | Bool | A bool to determine if the Joystick resets back to the center when release | no |
## đ¨âđģ Contributions
All issue reports, feature requests, pull requests and GitHub stars are welcomed and much appreciated. I would enjoy fixing or adding anything you need!
To make a contribution, I would help you if you ask, or
1. Fork this repo
2. Make your changes and test
3. Update readme as neded and add yourself to Authors section
4. Make a [Pull Request](https://github.com/michael94ellis/SwiftUIJoystick/pulls)
5. After merge update podspec version and project version appropriately (Major/Minor/Patch paradigm)
6. Push changes
7. Create new [version tag](https://github.com/michael94ellis/SwiftUIJoystick/tags) to match podspec and project version
8. Update pods repo, run this command in the package directory 'pod trunk push SwiftUIJoystick.podspec'
## âī¸ Authors
Created By: Michael Ellis - https://www.michaelrobertellis.com/
Inspired by Bradhowes Joystick for Swift, I had used this previously but I switched to pure SwiftUI
https://github.com/bradhowes/Joystick
A Big Thanks To Steven.Lin
c941010623 - https://github.com/c941010623
## đ License
`SwiftUIJoystick` is available under the MIT license. See the [LICENSE](https://github.com/michael94ellis/SwiftUIJoystick/blob/main/LICENSE) file for more info