// // README.md // apple_remote_controller // // Created by Nicolas Peeters on 27/05/2026. //
A native macOS SwiftUI application that maps game controller inputs to keyboard, mouse, and system actions.
Built as a practical input-remapping experiment and a portfolio-oriented codebase, apple_remote_controller focuses on clean architecture, native macOS integration, and a polished desktop UI.
- Overview
- Features
- Screenshots
- Architecture
- Project structure
- How it works
- Persistence
- Default mappings
- Requirements
- Getting started
- macOS permissions
- Roadmap
- Current limitations
- Technical highlights
- Why this project
- Author
- License
apple_remote_controller turns a game controller into a configurable desktop remote on macOS.
The app currently supports:
- button-to-key mapping
- keyboard shortcut mapping
- mouse button mapping
- analog stick mouse movement
- analog stick scrolling
- local persistent mapping storage
This project is intentionally modest in scope, but it is designed to demonstrate:
- SwiftUI application structure
- separation between UI, state, and runtime services
GameControllerintegration- system event dispatch with
AppKit/CoreGraphics - practical persistence without unnecessary complexity
- Controller input model covering:
- face buttons
- shoulders
- triggers
- D-pad
- stick clicks
- stick movement
- Editable mapping UI
- Keyboard key capture
- Keyboard shortcut capture
- Mouse button actions
- Analog runtime:
- right stick → mouse movement
- left stick → scrolling
- Controller preview with active input highlighting
- Automatic local persistence using
UserDefaults - Responsive three-panel layout
- richer system actions
- analog tuning and ergonomics
- UI/UX refinement
- more robust release behavior for mapped inputs
Placeholder section — screenshots and GIF previews will be added soon.
Suggested folder structure:
docs/
└── screenshots/
├── main-interface-placeholder.png
├── mapping-editor-placeholder.png
└── controller-preview-placeholder.png
The project is structured around a few simple layers.
Domain types:
ControllerInputControllerMappingActionCapturedShortcutStoredMapping
Observable application state:
ControllerMappingStore
Runtime and platform integration:
GameControllerManagerAnalogStickRuntimeMappingExecutionEngineSystemEventDispatcherKeyCodeMapper
SwiftUI interface composition:
ContentViewResponsiveThreePanelLayoutSidebarViewMainControllerPanelMappingEditorView- controller preview views
text
apple_remote_controller
├── App
│ └── apple_remote_controllerApp.swift
├── Models
│ ├── CapturedShortcut.swift
│ ├── ControllerInput.swift
│ ├── ControllerMappingAction.swift
│ └── StoredMapping.swift
├── Stores
│ └── ControllerMappingStore.swift
├── Services
│ ├── GameController
│ │ ├── AnalogStickRuntime.swift
│ │ └── GameControllerManager.swift
│ ├── Mapping
│ │ └── MappingExecutionEngine.swift
│ └── SystemEvents
│ ├── KeyCodeMapper.swift
│ └── SystemEventDispatcher.swift
├── Views
│ ├── ContentView.swift
│ ├── ControllerPreview
│ ├── Layout
│ ├── Mapping
│ ├── Panels
│ └── Sidebar
GameControllerManagerlistens to controller input changes- button presses are forwarded to
MappingExecutionEngine - the mapped action is resolved through
ControllerMappingStore SystemEventDispatchersends the corresponding keyboard, mouse, or system event
- thumbstick values are captured through
GameController - stick vectors are updated in real time
AnalogStickRuntimeprocesses them continuously- dead zone filtering is applied
- resulting values are converted into:
- mouse movement
- scroll events
Mappings are automatically persisted locally using UserDefaults.
- storage key:
controller.mappings.v1 - format: JSON
- load on launch: yes
- autosave on change: yes
- fallback to default mappings if decoding fails
This keeps the persistence layer intentionally lightweight and well suited to the current size of the project.
The current default configuration is:
buttonA→SpacebuttonB→ right clickbuttonX→RbuttonY→Mission ControlleftStickMove→ vertical scrollrightStickMove→ mouse movement
- macOS
- Xcode 15+
- Swift 5.10+ recommended
bash
git clone https://github.com/NicoPFr/apple_remote_controller.git
cd apple_remote_controllerbash
open apple_remote_controller.xcodeprojRun the apple_remote_controller target from Xcode.
Because the app sends synthetic keyboard and mouse events, it requires Accessibility permissions.
Go to:
- System Settings
- Privacy & Security
- Accessibility
Then allow the app.
Without these permissions, keyboard and mouse dispatching may not work correctly.
- add a software debug panel to simulate analog sticks without a physical controller
- expose dead zone and sensitivity settings
- add a reset-to-defaults UI action
- improve empty states and editing feedback
- support multiple mapping profiles
- add mapping import/export
- improve pressed / released behavior handling
- complete additional system actions
- menu bar mode
- richer automation-oriented actions
- controller presets
- public release polish
- some system actions are still placeholders
launchpadandshowDesktopare not implemented yet- analog mapping currently models mouse movement with a
MouseAxis, while the runtime already handles 2D stick motion - no profile management yet
- no import/export UI yet
- no built-in debug panel yet to simulate sticks without hardware
These are known limitations and part of the roadmap.
This project demonstrates:
- native macOS event synthesis with
CGEvent - controller input integration through
GameController - a lightweight persistence strategy with
UserDefaults+ JSON - state-driven UI with
SwiftUI - separation between:
- input monitoring
- mapping resolution
- event dispatch
- UI presentation
Nicolas Peeters https://www.linkedin.com/in/nicolas-p-bb3b028b/?locale=fr_FR
This project is distributed under the MIT License.
See LICENSE for details.
git clone https://github.com/NicoPFr/apple_remote_controller.git

