Bevy Archie - Rust / Bevy Controller Support Module

Archie Out of Context

A comprehensive game controller support module for the Bevy engine, inspired by the RenPy Controller GUI project.

Controller Support Matrix

Controller	Gyroscope	Touchpad	Adaptive Triggers	Rumble	Layout
Xbox 360	🔴	🔴	🔴	✅	Xbox
Xbox One	🔴	🔴	🔴	✅	Xbox
Xbox Series X\|S	🔴	🔴	🔴	✅	Xbox
PlayStation 3	✅	🔴	🔴	✅	PlayStation
PlayStation 4	✅	✅	🔴	✅	PlayStation
PlayStation 5	✅	✅	✅	✅	PlayStation
Switch Pro	✅	🔴	🔴	✅	Nintendo
Switch 2 Pro	✅	🔴	🔴	✅	Nintendo
Switch Joy-Con	✅	🔴	🔴	✅	Nintendo
Steam Controller	✅	✅	🔴	✅	Xbox
Stadia	✅	🔴	🔴	✅	Xbox
Amazon Luna	🔴	🔴	🔴	✅	Xbox
8BitDo M30	🔴	🔴	🔴	✅	Sega
8BitDo SN30 Pro	🔴	🔴	🔴	✅	Nintendo
HORI Fighting Cmd	🔴	🔴	🔴	✅	PlayStation
Generic	🔶	🔶	🔴	✅	Xbox

Legend: ✅ Supported | 🔴 Hardware limitation | 🔶 Unknown (varies by device)

Note: Gyroscope, touchpad, and adaptive triggers require platform-specific implementations. See Advanced Features for details.

Version Compatibility

bevy	bevy_archie
0.18	`bevy-0.18` branch
0.17	0.1.x (main)

Features

Core Input System

Input Device Detection: Automatically detect and switch between mouse, keyboard, and gamepad input
Input Action Mapping: Abstract input actions with customizable bindings for gamepad, keyboard, and mouse
Action State Tracking: Query pressed, just_pressed, just_released states and analog values for any action
Per-Stick Settings: Independent sensitivity and inversion for left/right analog sticks
Deadzone Configuration: Configurable stick deadzones with per-stick customization

Controller Support

Controller Icon System: Asset-agnostic icon mapping system that adapts to controller type (Xbox, PlayStation, Nintendo, Steam, Stadia, Generic). Bring your own icon assets or use any compatible pack.
Controller Profiles: Automatic detection and profile loading based on vendor/product IDs
Multi-controller Support: Handle multiple connected controllers with player assignment
Controller Layout Detection: Auto-detect and adapt UI to controller type

Advanced Input Features

Actionlike Trait: Define custom action enums with the Actionlike trait for type-safe input handling
Haptic Feedback: Rumble and vibration patterns (Constant, Pulse, Explosion, DamageTap, HeavyImpact, Engine, Heartbeat) - fully implemented
Input Buffering: Record and analyze input sequences for fighting game-style combo detection
Action Modifiers: Detect Tap, Hold, DoubleTap, LongPress, and Released events on actions
Button Chords: Detect simultaneous button combinations with configurable clash resolution
Virtual Input Composites: Combine buttons into virtual axes (VirtualAxis, VirtualDPad, VirtualDPad3D)
Conditional Bindings: Context-aware actions that activate based on game state or custom conditions
Input State Machine: Define state machines driven by input actions with automatic transitions
Gyroscope Support: Motion controls for PS4/PS5/Switch/Stadia/Steam controllers - complete gesture detection and data structures, needs hardware driver integration (HID/SDL2). See ps5_dualsense_motion.rs and switch_pro_gyro.rs
Touchpad Support: PS4/PS5/Steam touchpad input with multi-touch and gesture detection (swipe, pinch, tap) - complete gesture detection and data structures, needs hardware driver integration (HID/SDL2). See ps5_dualsense_motion.rs and steam_touchpad.rs

Multiplayer

Player Assignment: Automatic or manual controller-to-player assignment (up to 4 players)
Controller Ownership: Track which player owns which controller
Hot-swapping: Handle controller disconnection and reassignment

UI & Configuration

Controller Remapping: Allow players to remap controller buttons at runtime
Virtual Keyboard: On-screen keyboard for controller-friendly text input
Virtual Cursor: Gamepad-controlled cursor for mouse-based UI navigation
Configuration Persistence: Save and load controller settings to/from JSON files

Developer Tools

Input Debugging: Visualize input states, history, and analog values
Input Recording: Record input sequences for testing and replay
Input Playback: Play back recorded inputs for automated testing
Input Mocking: MockInput and MockInputPlugin for unit testing input-dependent systems
Build Helpers: Generate icon manifests and organize controller assets at build time

Mobile & Touch

Touch Joystick: Virtual on-screen joysticks for mobile platforms with fixed or floating modes

Networking

Input Synchronization: ActionDiff and ActionDiffBuffer for efficient network input sync with rollback support

Supported Controllers

Xbox - Xbox 360, Xbox One, Xbox Series X|S controllers
PlayStation - PS3, PS4, PS5 (DualShock 3, DualShock 4, and DualSense)
Nintendo - Switch Pro Controller, Switch 2 Pro, Joy-Cons
Steam - Steam Controller, Steam Deck
Stadia - Google Stadia Controller (Bluetooth mode)
Amazon Luna - Amazon Luna Controller (Xbox-style layout)
8BitDo - M30 (Sega-style), SN30 Pro (Nintendo-style)
HORI - Fighting Commander, HORIPAD series
Generic - Any other standard gamepad

Note: Stadia controllers must be switched to Bluetooth mode (a permanent one-time operation that was available until Dec 31, 2025). In Bluetooth mode, they function as standard Xbox-style gamepads.

Installation

Add to your Cargo.toml:

[dependencies]
bevy_archie = { path = "path/to/bevy-archie" }
# Or with specific features:
bevy_archie = { path = "path/to/bevy-archie", features = ["full"] }

Quick Start

use bevy::prelude::*;
use bevy_archie::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(ControllerPlugin::default())
        .add_systems(Startup, setup)
        .add_systems(Update, handle_input)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
}

fn handle_input(
    input_state: Res<InputDeviceState>,
    actions: Res<ActionState>,
) {
    // Check which input device is active
    match input_state.active_device {
        InputDevice::Mouse => { /* Mouse logic */ }
        InputDevice::Keyboard => { /* Keyboard logic */ }
        InputDevice::Gamepad(_) => { /* Controller logic */ }
    }

    // Check action states
    if actions.just_pressed(GameAction::Confirm) {
        println!("Confirm pressed!");
    }
}

Action System

Define your game actions and bind them to controller buttons:

use bevy_archie::prelude::*;

// Actions are predefined, but you can extend with custom actions
fn setup_actions(mut action_map: ResMut<ActionMap>) {
    // Rebind an action
    action_map.bind(GameAction::Confirm, GamepadButtonType::South);
    action_map.bind(GameAction::Cancel, GamepadButtonType::East);
    
    // Add keyboard bindings
    action_map.bind_key(GameAction::Confirm, KeyCode::Enter);
    action_map.bind_key(GameAction::Cancel, KeyCode::Escape);
}

Remapping

Enable controller remapping in your settings menu:

fn spawn_remap_ui(mut commands: Commands) {
    commands.spawn((
        RemapButton {
            action: GameAction::Confirm,
        },
        // ... UI components
    ));
}

Configuration

use bevy_archie::prelude::*;

fn configure_controller(mut config: ResMut<ControllerConfig>) {
    // Stick deadzone (0.0 - 1.0)
    config.deadzone = 0.15;
    
    // Per-stick sensitivity multipliers
    config.left_stick_sensitivity = 1.0;
    config.right_stick_sensitivity = 1.5; // Faster cursor movement
    
    // Per-stick X-axis inversion
    config.invert_left_x = false;
    config.invert_right_x = true; // Inverted camera controls
    
    // Auto-detect controller layout
    config.auto_detect_layout = true;
    
    // Force a specific layout
    config.force_layout = Some(ControllerLayout::PlayStation);
}

Virtual Cursor

Enable gamepad-controlled cursor for mouse-based UI:

use bevy::prelude::*;
use bevy_archie::prelude::*;

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Spawn virtual cursor (automatically shown when gamepad active)
    bevy_archie::virtual_cursor::spawn_virtual_cursor(
        &mut commands,
        &asset_server,
        None, // Uses default cursor.png
    );
}

fn handle_clicks(mut click_events: EventReader<VirtualCursorClick>) {
    for event in click_events.read() {
        println!("Cursor clicked at: {:?}", event.position);
    }
}

Configuration Persistence

Save and load controller settings:

use bevy_archie::prelude::*;

// Load config on startup
fn load_config(mut config: ResMut<ControllerConfig>) {
    *config = ControllerConfig::load_or_default().unwrap();
}

// Save config
fn save_config(config: Res<ControllerConfig>) {
    config.save_default().unwrap();
}

// Custom path
fn save_to_custom_path(config: Res<ControllerConfig>) {
    config.save_to_file("my_config.json").unwrap();
}

Config files are saved to platform-specific directories:

Linux: ~/.config/bevy_archie/controller.json
macOS: ~/Library/Application Support/bevy_archie/controller.json
Windows: %APPDATA%\bevy_archie\controller.json

Examples

Bevy-archie includes several examples to help you get started:

Basic Examples

basic_input.rs: Simple input handling
controller_icons.rs: Display controller-specific icons
remapping.rs: Runtime button remapping
virtual_cursor.rs: Gamepad-controlled cursor
config_persistence.rs: Save/load settings

Advanced Hardware Integration

These examples show how to integrate real hardware for gyro and touchpad:

ps5_dualsense_motion.rs: DualSense gyro + touchpad via hidapi
- Complete HID report parsing reference
- Both USB and Bluetooth modes
- Calibration and data injection patterns
switch_pro_gyro.rs: Switch Pro Controller gyro via SDL2
- Cross-platform gyro support
- Alternative: Direct HID approach
steam_touchpad.rs: Steam Deck/Steam Controller touchpad
- Steam Input API integration (recommended)
- Alternative: Direct HID for advanced users

Run examples with:

cargo run --example basic_input
cargo run --example ps5_dualsense_motion --features motion-backends

Supported Controller Layouts

Xbox: Xbox 360, Xbox One, Xbox Series controllers
PlayStation: DualShock 3/4, DualSense
Nintendo: Joy-Con, Pro Controller, GameCube
Steam: Steam Controller, Steam Deck
Stadia: Google Stadia Controller (Bluetooth mode)
Generic: Fallback for unrecognized controllers

Advanced Features

Haptic Feedback

Add rumble and vibration to your game:

use bevy_archie::prelude::*;

fn trigger_rumble(
    mut rumble_events: MessageWriter<RumbleRequest>,
    gamepads: Query<Entity, With<Gamepad>>,
) {
    for gamepad in gamepads.iter() {
        // Simple rumble
        rumble_events.write(RumbleRequest::new(
            gamepad,
            0.8,  // Intensity (0.0-1.0)
            Duration::from_millis(500),
        ));
        
        // Pattern-based rumble
        rumble_events.write(RumbleRequest::with_pattern(
            gamepad,
            RumblePattern::Explosion,  // Strong fade effect
            0.9,
            Duration::from_secs(1),
        ));
    }
}

// Available patterns:
// - Constant: Steady vibration
// - Pulse: Rhythmic pulsing
// - Explosion: Strong start with fade
// - DamageTap: Quick impact feel
// - HeavyImpact: Longer impact
// - Engine: Motor-like hum
// - Heartbeat: Pulse pattern

Input Buffering & Combos

Detect input sequences for fighting game mechanics:

use bevy_archie::prelude::*;

fn setup_combos(mut registry: ResMut<ComboRegistry>) {
    // Define a combo sequence
    registry.register(
        Combo::new("hadouken", vec![
            GameAction::Down,
            GameAction::Right,
            GameAction::Primary,
        ])
        .with_window(Duration::from_millis(500))
    );
}

fn handle_combos(
    mut combo_events: MessageReader<ComboDetected>,
) {
    for event in combo_events.read() {
        println!("Combo detected: {}", event.combo);
        // Trigger special move
    }
}

Multiplayer Controller Management

Assign controllers to players:

use bevy_archie::prelude::*;

fn setup_players(mut commands: Commands) {
    // Spawn player entities
    commands.spawn(Player::new(0)); // Player 1
    commands.spawn(Player::new(1)); // Player 2
}

fn manual_assignment(
    mut assign_events: MessageWriter<AssignControllerRequest>,
    gamepads: Query<Entity, With<Gamepad>>,
) {
    // Manually assign a controller to a player
    if let Some(gamepad) = gamepads.iter().next() {
        assign_events.write(AssignControllerRequest {
            gamepad,
            player: PlayerId::new(0),
        });
    }
}

fn check_ownership(
    ownership: Res<ControllerOwnership>,
    input: Res<ActionState>,
) {
    // Check which player owns a gamepad
    if let Some(player_id) = ownership.get_owner(gamepad_entity) {
        println!("Controller owned by player {}", player_id.id());
    }
    
    // Get gamepad for a specific player
    if let Some(gamepad) = ownership.get_gamepad(PlayerId::new(0)) {
        // Read input for player 1's controller
    }
}

Action Modifiers

Detect advanced input patterns:

use bevy_archie::prelude::*;

fn handle_modifiers(
    mut modifier_events: MessageReader<ModifiedActionEvent>,
) {
    for event in modifier_events.read() {
        match event.modifier {
            ActionModifier::Tap => {
                println!("Quick tap on {:?}", event.action);
            }
            ActionModifier::Hold => {
                println!("Held for {} seconds", event.duration);
            }
            ActionModifier::DoubleTap => {
                println!("Double-tapped!");
            }
            ActionModifier::LongPress => {
                println!("Long press detected");
            }
            ActionModifier::Released => {
                println!("Button released");
            }
        }
    }
}

// Configure modifier timings
fn configure_modifiers(mut state: ResMut<ActionModifierState>) {
    state.config.hold_duration = 0.2;        // 200ms for hold
    state.config.long_press_duration = 0.8;  // 800ms for long press
    state.config.double_tap_window = 0.3;    // 300ms between taps
}

PlayStation Touchpad

Handle touchpad input on DualShock 4 and DualSense:

use bevy_archie::prelude::*;

fn handle_touchpad(
    mut gesture_events: MessageReader<TouchpadGestureEvent>,
    touchpad_query: Query<&TouchpadData>,
) {
    // Handle gestures
    for event in gesture_events.read() {
        match event.gesture {
            TouchpadGesture::Tap => println!("Tapped at {:?}", event.position),
            TouchpadGesture::TwoFingerTap => println!("Two-finger tap"),
            TouchpadGesture::SwipeLeft => println!("Swiped left"),
            TouchpadGesture::SwipeRight => println!("Swiped right"),
            TouchpadGesture::SwipeUp => println!("Swiped up"),
            TouchpadGesture::SwipeDown => println!("Swiped down"),
            TouchpadGesture::PinchIn => println!("Pinch in (zoom out)"),
            TouchpadGesture::PinchOut => println!("Pinch out (zoom in)"),
        }
    }
    
    // Direct touchpad access
    for touchpad in touchpad_query.iter() {
        let finger1_pos = touchpad.finger1.position();
        let finger1_delta = touchpad.finger1_delta();
        
        if touchpad.button_pressed {
            println!("Touchpad button pressed");
        }
        
        println!("Active fingers: {}", touchpad.active_fingers());
    }
}

Controller Profiles

Automatically detect controller models and load profiles:

use bevy_archie::prelude::*;

fn setup_profiles(mut registry: ResMut<ProfileRegistry>) {
    // Register a custom profile for PS5 controllers
    let ps5_profile = ControllerProfile::new("PS5 Default", ControllerModel::PS5)
        .with_action_map(my_custom_action_map())
        .with_layout(ControllerLayout::PlayStation);
    
    registry.register(ps5_profile);
    registry.auto_load = true;  // Auto-apply profiles when controllers connect
}

fn handle_detection(
    mut detected_events: MessageReader<ControllerDetected>,
    detected_query: Query<&DetectedController>,
) {
    for event in detected_events.read() {
        println!("Detected: {:?}", event.model);
        
        // Check controller capabilities
        if event.model.supports_gyro() {
            println!("Controller has gyroscope support");
        }
        if event.model.supports_touchpad() {
            println!("Controller has touchpad");
        }
        if event.model.supports_adaptive_triggers() {
            println!("Controller has adaptive triggers (PS5)");
        }
    }
}

Motion Controls (Gyroscope)

Access gyroscope and accelerometer data:

use bevy_archie::prelude::*;

fn handle_motion(
    mut gesture_events: MessageReader<MotionGestureDetected>,
    gyro_query: Query<&GyroData>,
    accel_query: Query<&AccelData>,
) {
    // Handle detected gestures
    for event in gesture_events.read() {
        match event.gesture {
            MotionGesture::Flick => println!("Quick rotation detected"),
            MotionGesture::Shake => println!("Controller shaken"),
            MotionGesture::Tilt => println!("Controller tilted"),
            MotionGesture::Roll => println!("Controller rolled"),
        }
    }
    
    // Direct gyro access
    for gyro in gyro_query.iter() {
        if gyro.valid {
            let rotation_speed = gyro.magnitude();
            println!("Rotation: pitch={}, yaw={}, roll={}", 
                gyro.pitch, gyro.yaw, gyro.roll);
        }
    }
    
    // Direct accelerometer access
    for accel in accel_query.iter() {
        if accel.valid {
            if accel.is_shaking(3.0) {  // Threshold in m/s²
                println!("Shake detected!");
            }
        }
    }
}

// Configure motion controls
fn configure_motion(mut config: ResMut<MotionConfig>) {
    config.gyro_sensitivity = 1.5;
    config.gyro_deadzone = 0.01;
    config.enabled = true;
}

Debug Tools

Visualize and record input for testing:

use bevy_archie::prelude::*;

fn toggle_debug(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut debug_events: MessageWriter<ToggleInputDebug>,
) {
    if keyboard.just_pressed(KeyCode::F12) {
        debug_events.write(ToggleInputDebug { enable: true });
    }
}

fn configure_debugger(mut debugger: ResMut<InputDebugger>) {
    debugger.show_history = true;   // Show input history
    debugger.show_sticks = true;    // Show analog stick positions
    debugger.show_buttons = true;   // Show button states
    debugger.show_gyro = true;      // Show gyro data
    debugger.history_size = 50;     // Keep last 50 inputs
}

fn start_recording(
    mut record_events: MessageWriter<RecordingCommand>,
) {
    record_events.write(RecordingCommand { start: true });
}

fn playback_recording(
    recorder: Res<InputRecorder>,
    mut playback_events: MessageWriter<PlaybackCommand>,
) {
    if !recorder.recording {
        playback_events.write(PlaybackCommand {
            inputs: recorder.recorded.clone(),
        });
    }
}

Virtual Input Composites

Combine multiple buttons into unified axes:

use bevy_archie::prelude::*;

fn setup_virtual_inputs(mut commands: Commands) {
    // Combine W/S keys into a vertical axis (-1.0 to 1.0)
    let vertical = VirtualAxis::new(KeyCode::KeyW, KeyCode::KeyS);
    
    // Combine WASD into a 2D movement vector
    let movement = VirtualDPad::new(
        KeyCode::KeyW,  // up
        KeyCode::KeyS,  // down
        KeyCode::KeyA,  // left
        KeyCode::KeyD,  // right
    );
    
    // Combine multiple buttons with OR logic
    let any_jump = VirtualButton::any(vec![
        KeyCode::Space,
        KeyCode::KeyW,
    ]);
}

Button Chords

Detect simultaneous button presses:

use bevy_archie::prelude::*;

fn setup_chords(mut chord_registry: ResMut<ChordRegistry>) {
    // Register Ctrl+S chord for saving
    let save_chord = ButtonChord::from_buttons([KeyCode::ControlLeft, KeyCode::KeyS]);
    chord_registry.register("save", save_chord);
    
    // Register gamepad chord (LB + RB for special move)
    let special_chord = ButtonChord::from_buttons([
        GamepadButton::LeftTrigger,
        GamepadButton::RightTrigger,
    ]);
    chord_registry.register("special_move", special_chord)
        .with_clash_strategy(ClashStrategy::PrioritizeLongest);
}

fn handle_chords(mut chord_events: MessageReader<ChordTriggered>) {
    for event in chord_events.read() {
        match event.chord_name.as_str() {
            "save" => println!("Save triggered!"),
            "special_move" => println!("Special move!"),
            _ => {}
        }
    }
}

Conditional Bindings

Make actions context-aware:

use bevy_archie::prelude::*;

#[derive(States, Default, Clone, Eq, PartialEq, Debug, Hash)]
enum GameState {
    #[default]
    Menu,
    Playing,
    Paused,
}

fn setup_conditional_bindings(mut bindings: ResMut<ConditionalBindings>) {
    // "Confirm" only works in menus
    bindings.add(
        GameAction::Confirm,
        KeyCode::Enter,
        InputCondition::in_state(GameState::Menu),
    );
    
    // "Attack" only works while playing
    bindings.add(
        GameAction::Primary,
        KeyCode::Space,
        InputCondition::in_state(GameState::Playing),
    );
    
    // Chain conditions: works in Playing OR Paused
    bindings.add(
        GameAction::Pause,
        KeyCode::Escape,
        InputCondition::in_state(GameState::Playing)
            .or(InputCondition::in_state(GameState::Paused)),
    );
}

Input State Machine

Define states driven by input:

use bevy_archie::prelude::*;

fn setup_state_machine(mut commands: Commands) {
    let state_machine = StateMachineBuilder::new()
        .add_state("idle")
        .add_state("walking")
        .add_state("running")
        .add_state("jumping")
        .initial_state("idle")
        // Transitions based on actions
        .add_transition("idle", "walking", GameAction::Up)
        .add_transition("idle", "walking", GameAction::Down)
        .add_transition("walking", "running", GameAction::Primary) // Sprint
        .add_transition("idle", "jumping", GameAction::Confirm)    // Jump
        .add_transition("walking", "jumping", GameAction::Confirm)
        // Return to idle when no input
        .add_transition("walking", "idle", GameAction::Released)
        .build();
    
    commands.insert_resource(state_machine);
}

fn handle_state_changes(mut state_events: MessageReader<StateMachineTransition>) {
    for event in state_events.read() {
        println!("State changed: {} -> {}", event.from_state, event.to_state);
    }
}

Input Mocking for Tests

Test input-dependent systems:

use bevy_archie::prelude::*;
use bevy_archie::testing::*;

#[test]
fn test_jump_mechanic() {
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_plugins(MockInputPlugin);  // Use mock input instead of real
    
    // Simulate pressing jump
    let mock = MockInput::new()
        .press(GameAction::Confirm)
        .with_duration(Duration::from_millis(100));
    
    app.world.insert_resource(mock);
    app.update();
    
    // Assert jump was triggered
    let actions = app.world.resource::<ActionState>();
    assert!(actions.just_pressed(GameAction::Confirm));
}

// Script a sequence of inputs
fn test_combo_detection() {
    let sequence = MockInputSequence::new()
        .then_press(GameAction::Down, Duration::from_millis(50))
        .then_press(GameAction::Right, Duration::from_millis(50))
        .then_press(GameAction::Primary, Duration::from_millis(50));
    
    // Inject and verify combo detection
}

Touch Joystick (Mobile)

Add virtual joysticks for touch screens:

use bevy_archie::prelude::*;
use bevy_archie::touch_joystick::*;

fn setup_touch_controls(mut commands: Commands) {
    // Left stick for movement (fixed position)
    commands.spawn(TouchJoystick {
        position: Vec2::new(150.0, 150.0),
        radius: 100.0,
        dead_zone: 0.15,
        mode: JoystickMode::Fixed,
        output_action: Some(GameAction::Up), // Maps to movement
    });
    
    // Right stick for camera (floating - appears where you touch)
    commands.spawn(TouchJoystick {
        position: Vec2::ZERO,
        radius: 80.0,
        dead_zone: 0.1,
        mode: JoystickMode::Floating,
        output_action: Some(GameAction::LookUp),
    });
}

fn read_joystick(joysticks: Query<&TouchJoystick>) {
    for joystick in joysticks.iter() {
        let direction = joystick.direction(); // Vec2 from -1 to 1
        let magnitude = joystick.magnitude(); // 0.0 to 1.0
    }
}

Network Input Sync

Synchronize input state across network:

use bevy_archie::prelude::*;
use bevy_archie::networking::*;

fn send_input_to_server(
    action_state: Res<ActionState>,
    mut diff_buffer: ResMut<ActionDiffBuffer>,
    mut network: ResMut<NetworkClient>,
) {
    // Generate diff from last sent state
    if let Some(diff) = diff_buffer.generate_diff(&action_state) {
        // Serialize and send
        let bytes = diff.serialize().expect("serialization failed");
        network.send_reliable(bytes);
        
        // Store for potential rollback
        diff_buffer.push(diff);
    }
}

fn receive_input_from_client(
    mut network_events: MessageReader<NetworkPacket>,
    mut remote_actions: ResMut<RemoteActionStates>,
) {
    for packet in network_events.read() {
        let diff = ActionDiff::deserialize(&packet.data)
            .expect("deserialization failed");
        remote_actions.apply_diff(packet.player_id, diff);
    }
}

Examples

Run the examples to see features in action:

# Basic input handling
cargo run --example basic_input

# Controller icon display
cargo run --example controller_icons

# Button remapping UI
cargo run --example remapping

# Virtual cursor
cargo run --example virtual_cursor

# Config persistence
cargo run --example config_persistence

API Reference

SystemSets

bevy_archie provides the following system sets for ordering your systems:

pub enum ControllerSystemSet {
    /// Device detection runs first.
    Detection,
    /// Action state updates.
    Actions,
    /// UI updates based on input state.
    UI,
}

Execution order: Detection → Actions → UI

Use these to order your systems relative to controller input processing:

app.add_systems(Update, my_input_system.after(ControllerSystemSet::Actions));

Core Types

`InputDeviceState`

Tracks the currently active input device.

pub struct InputDeviceState {
    pub active_device: InputDevice,
    pub last_gamepad: Option<Entity>,
    // ...
}

// Methods
fn using_gamepad(&self) -> bool;
fn using_keyboard(&self) -> bool;
fn using_mouse(&self) -> bool;
fn active_gamepad(&self) -> Option<Entity>;

`ActionState`

Query the state of game actions.

pub struct ActionState {
    // ...
}

// Methods
fn pressed(&self, action: GameAction) -> bool;
fn just_pressed(&self, action: GameAction) -> bool;
fn just_released(&self, action: GameAction) -> bool;
fn value(&self, action: GameAction) -> f32;  // 0.0-1.0 for analog

`ActionMap`

Map actions to input sources.

pub struct ActionMap {
    // ...
}

// Methods
fn bind_gamepad(&mut self, action: GameAction, button: GamepadButton);
fn bind_axis(&mut self, action: GameAction, axis: GamepadAxis, direction: AxisDirection, threshold: f32);
fn bind_key(&mut self, action: GameAction, key: KeyCode);
fn bind_mouse(&mut self, action: GameAction, button: MouseButton);
fn clear_bindings(&mut self, action: GameAction);
fn primary_gamepad_button(&self, action: GameAction) -> Option<GamepadButton>;

`GameAction`

Predefined actions that can be customized.

pub enum GameAction {
    // Navigation
    Confirm, Cancel, Pause, Select,
    
    // Movement
    Up, Down, Left, Right,
    
    // Camera
    LookUp, LookDown, LookLeft, LookRight,
    
    // Actions
    Primary, Secondary,
    LeftShoulder, RightShoulder,
    LeftTrigger, RightTrigger,
    
    // UI
    PageLeft, PageRight,
    
    // Custom slots
    Custom1, Custom2, Custom3, Custom4,
}

// Methods
fn all() -> &'static [GameAction];
fn display_name(&self) -> &'static str;
fn is_remappable(&self) -> bool;
fn is_required(&self) -> bool;

Configuration

`ControllerConfig`

Main configuration resource.

pub struct ControllerConfig {
    pub deadzone: f32,
    pub left_stick_sensitivity: f32,
    pub right_stick_sensitivity: f32,
    pub invert_left_x: bool,
    pub invert_left_y: bool,
    pub invert_right_x: bool,
    pub invert_right_y: bool,
    pub auto_detect_layout: bool,
    pub force_layout: Option<ControllerLayout>,
}

// Methods (for persistence)
fn save_default(&self) -> std::io::Result<()>;
fn save_to_file(&self, path: impl AsRef<Path>) -> std::io::Result<()>;
fn load_or_default() -> std::io::Result<Self>;
fn load_from_file(path: impl AsRef<Path>) -> std::io::Result<Self>;

Events (now Messages in Bevy 0.17)

All events are now Message types. Use MessageReader and MessageWriter:

InputDeviceChanged - Input device switched
GamepadConnected / GamepadDisconnected - Controller connection
VirtualCursorClick - Virtual cursor clicked
RumbleRequest - Request haptic feedback
ComboDetected - Input combo detected
ModifiedActionEvent - Action modifier detected
TouchpadGestureEvent - Touchpad gesture
MotionGestureDetected - Motion gesture
ControllerAssigned / ControllerUnassigned - Player assignment
ControllerDetected - Controller model detected
StartRemapEvent / RemapEvent - Remapping events
ToggleInputDebug / RecordingCommand / PlaybackCommand - Debug commands

Platform Support

Haptic Feedback

Fully implemented using Bevy's native GamepadRumbleRequest. Works out of the box on all platforms that support rumble through gilrs.

Motion Controls

What's implemented: Complete gesture detection (shake, tilt, flick, roll), data structures (GyroData, AccelData), and event system.

What's needed: Hardware drivers to read sensor data from controllers. See the Hardware Integration Guide for detailed instructions.

Quick example (see ps5_dualsense_motion.rs for full code):

fn inject_gyro_data(mut gamepads: Query<&mut GyroData>) {
    // Use hidapi, SDL2, or platform-specific drivers
    let (pitch, yaw, roll) = read_controller_sensors();
    for mut gyro in &mut gamepads {
        gyro.set_raw(pitch, yaw, roll);
    }
}

Touchpad

What's implemented: Complete gesture detection (swipe, pinch, tap, multi-touch), data structures (TouchpadData), and event system.

What's needed: Hardware drivers to read touchpad data from controllers. See the Hardware Integration Guide for detailed instructions.

Quick example (see ps5_dualsense_motion.rs for full code):

fn inject_touchpad_data(mut gamepads: Query<&mut TouchpadData>) {
    // Use hidapi, SDL2, or platform-specific drivers
    let (x, y, pressed) = read_touchpad();
    for mut touchpad in &mut gamepads {
        touchpad.set_finger(0, x, y, pressed);
        touchpad.update_frame();
    }
}

Hardware integration resources:

📘 Hardware Integration Guide - Complete guide with controller-specific details
🎮 PS5 DualSense Example - Both gyro and touchpad
🎮 Switch Pro Example - Gyro via SDL2
🎮 Steam Deck Example - Touchpad via Steam Input API

Migration from Bevy 0.16

Bevy 0.17 introduced a major change: Events are now Messages.

Key Changes

// Bevy 0.16
app.add_event::<MyEvent>();
fn system(mut events: EventWriter<MyEvent>) { }
fn reader(mut events: EventReader<MyEvent>) { }

// Bevy 0.17
app.add_message::<MyEvent>();
fn system(mut events: MessageWriter<MyEvent>) { }
fn reader(mut events: MessageReader<MyEvent>) { }

All events in bevy_archie have been migrated to Messages.

Testing

Running Tests

# Run all unit tests
cargo test --lib

# Run all tests including integration tests
cargo test

# Run specific test module
cargo test --lib config::tests

# Run with all features enabled
cargo test --all-features

Test Coverage

The project includes comprehensive unit and integration tests covering:

Core Modules (actions, config, detection): Input device detection, action mapping, configuration management
Icon System (icons): Icon filename generation, platform-specific labels, asset loading
Integration Tests: Plugin initialization, resource management, end-to-end workflows

Coverage Goal: 80% code coverage across all modules. See docs/TEST_COVERAGE.md for coverage tools and analysis.

Test Structure

src/*/tests: Unit tests for each module
tests/integration_tests.rs: Integration tests for full plugin functionality
.cargo/config.toml: Test configuration and aliases

For detailed coverage analysis instructions, see docs/TEST_COVERAGE.md.

Controller Icons

This library's icon system is asset-agnostic - it provides the infrastructure for loading and displaying controller-appropriate icons, but does not bundle icon assets in the crate to keep download size minimal.

Recommended Icon Pack

We recommend Mr. Breakfast's Free Prompts - a comprehensive CC0-licensed icon pack with 400+ PNG/SVG icons for Xbox, PlayStation, Nintendo Switch, Steam Deck, keyboard, and mouse.

Adding Icon Assets

Download the icon pack from itch.io

Extract to your project's assets folder:

your_game/
└── assets/
    └── icons/
        └── mrbreakfast/
            ├── LICENSE
            └── png/
                ├── xbox_a.png
                ├── ps_cross.png
                └── ...

Configure the icon system:

fn setup_icons(mut commands: Commands) {
    commands.insert_resource(
        ControllerIconAssets::new("icons/mrbreakfast/png")
    );
}

Alternative Icon Packs

You can use any icon pack that follows standard naming conventions:

Kenney Input Prompts (CC0)
Xelu's Controllers & Keyboard Prompts (CC0)
Custom artwork

Icon Naming Conventions

The system expects icons named according to platform conventions:

Xbox: xbox_a.png, xbox_b.png, xbox_lb.png, xbox_lt.png
PlayStation: ps_cross.png, ps_circle.png, ps_l1.png, ps_l2.png
Nintendo: switch_b.png, switch_a.png, switch_l.png, switch_zl.png
Generic: left_stick.png, right_stick.png, dpad.png

Icon sizes are supported via suffixes: xbox_a_small.png (32x32), xbox_a.png (48x48), xbox_a_large.png (64x64).

If your icon pack uses different naming, create a thin wrapper or use symbolic links.

Credits

Inspired by the RenPy Controller GUI by Feniks.

Included Assets

Mr. Breakfast's Free Prompts - Controller and keyboard input prompt icons by Mr. Breakfast. Over 400 PNG/SVG icons supporting Xbox, PlayStation, Nintendo Switch, Steam Deck, keyboard, and mouse. Licensed under CC0 1.0 Universal (Public Domain).

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE)
MIT license (LICENSE-MIT)

at your option.

bevy_archie 0.1.6

Bevy Archie - Rust / Bevy Controller Support Module

Controller Support Matrix

Version Compatibility

Features

Core Input System

Controller Support

Advanced Input Features

Multiplayer

UI & Configuration

Developer Tools

Mobile & Touch

Networking

Supported Controllers

Installation

Quick Start

Action System

Remapping

Configuration

Virtual Cursor

Configuration Persistence

Examples

Basic Examples

Advanced Hardware Integration

Supported Controller Layouts

Advanced Features

Haptic Feedback

Input Buffering & Combos

Multiplayer Controller Management

Action Modifiers

PlayStation Touchpad

Controller Profiles

Motion Controls (Gyroscope)

Debug Tools

Virtual Input Composites

Button Chords

Conditional Bindings

Input State Machine

Input Mocking for Tests

Touch Joystick (Mobile)

Network Input Sync

Examples

API Reference

SystemSets

Core Types

InputDeviceState

ActionState

ActionMap

GameAction

Configuration

ControllerConfig

Events (now Messages in Bevy 0.17)

Platform Support

Haptic Feedback

Motion Controls

Touchpad

Migration from Bevy 0.16

Key Changes

Testing

Running Tests

Test Coverage

Test Structure

Controller Icons

Recommended Icon Pack

Adding Icon Assets

Alternative Icon Packs

Icon Naming Conventions

Credits

Included Assets

License

`InputDeviceState`

`ActionState`

`ActionMap`

`GameAction`

`ControllerConfig`