Improve documentation and make Scroll Speed work intuitively.

This commit is contained in:
Anna Rose 2025-01-19 13:06:46 -05:00
parent c4244d325d
commit 754b4107b3
2 changed files with 37 additions and 13 deletions

View File

@ -2,6 +2,8 @@ from datetime import datetime, timedelta
import gremlin
from gremlin.user_plugin import *
# User-configurable variables; these appear in the Joystick Gremlin UI
axis = PhysicalInputVariable(
"Axis",
"The axis that will trigger scrolling.",
@ -13,7 +15,7 @@ mode = ModeVariable(
"The mode in which the axis will be mapped.",
)
response_coefficient = FloatVariable(
scroll_speed = FloatVariable(
"Scroll Speed",
"Adjusts the rate at which the target button is pressed, relative to the axis strength.",
1.0,
@ -32,16 +34,25 @@ invert = BoolVariable(
False,
)
# Constants
AXIS_SCALING_FACTOR = 250 # Value determined through testing.
# Debugging
ticks = 0
axis_decorator = axis.create_decorator(mode.value)
# Stateful data
last_timestamp = datetime.now()
scroll_scaling = scroll_speed.value if scroll_speed.value != 0.0 else 1.0
@axis_decorator.axis(axis.input_id)
# TODO: use this code instead when periodic callback is fixed
# @gremlin.input_devices.periodic(1)
@axis_decorator.axis(axis.input_id)
def handle_axis(event):
global last_timestamp
global damping
global ticks # debug
# TODO: use this code instead when periodic callback is fixed
# axis_value = joy[axis.device_guid].axis(axis.input_id).value
axis_value = event.value
@ -50,8 +61,13 @@ def handle_axis(event):
delta = (datetime.now() - last_timestamp) / timedelta(milliseconds=1)
if delta >= (1 - abs(axis_value)) * 250 * response_coefficient.value:
# Scroll speed is *inversely proportional* to the right-hand side of this comparison
if delta >= ((1 - abs(axis_value)) * AXIS_SCALING_FACTOR) / scroll_scaling:
direction = 1 if axis_value > 0 else -1
if invert.value: direction = direction * -1
gremlin.sendinput.mouse_wheel(direction)
last_timestamp = datetime.now()
last_timestamp = datetime.now()
# debug
ticks += 1
gremlin.util.log(ticks)

View File

@ -2,15 +2,20 @@
This is a plugin for [Joystick Gremlin](https://github.com/WhiteMagic/JoystickGremlin) (JG). Familiarity with JG is assumed.
This script will allow you to configure a joystick axis to send mouse scrollwheel events. The scrollwheel will move faster in proportion to how far the axis is moved.
This script will allow you to configure a joystick axis to send mouse scrollwheel events. The scrollwheel will move faster when the axis is farther from zero. A centered axis is assumed; a single-directional axis (like some throttles, sliders, etc) will only be able to scroll in one direction.
The motivating use case for this plugin is ship tractor beams in the game [Star Citizen](https://robertsspaceindustries.com/); tuning defaults are configured with this in mind.
## Installation
Download the code (TODO: add granular instructions). Click "Add Plugin" on the Plugins tab of Joystick Gremlin. Navigate to the axis_to_scrollwheel.py file and select it.
* Download the latest release from the [releases page](https://git.annabunches.net/annabunches/joystick_gremlin_axis_to_scrollwheel/releases).
* Extract the zip file somewhere.
* Click "Add Plugin" on the Plugins tab of Joystick Gremlin.
* Navigate to the axis_to_scrollwheel.py file you just extracted and select it.
## Configuration
Clicking on the gear next to the plugin in the plugin list will present you with several configuration options. Note that you must toggle the profile off and on again for changes to take effect.
Clicking on the gear icon next to the plugin in the plugin list will present you with several configuration options. You need to toggle the profile off and on again for changes to take effect.
### Axis
@ -18,11 +23,13 @@ The axis that should act as a scrollwheel.
### Mode
The Joystick Gremlin mode that needs to be active for the binding to work. If you aren't using Modes (or don't know what they are) the default value should work correctly.
The plugin will only change the axis behavior when in the selected Mode. If you aren't using Modes (or don't know what they are) the default value should work correctly.
### Scroll Speed
Increasing this value will cause the scroll wheel to scroll more quickly. 1.0 is a good default.
Increasing this value will cause the scroll wheel to scroll more quickly. 1.0 is a good default. If scrolling feels too fast to you, try changing this to 0.5.
Note that this value *cannot* be zero; if it is set to zero it will be automatically changed to 1.0.
### Deadzone
@ -34,5 +41,6 @@ If the scrolling feels backwards, select this.
## Known Issues
* The Response Coefficient doesn't always get assigned a default value. You should set it to `1.0` to start.
* Maxing out the axis in either direction will cause the scrolling to stop. This is a limitation of Joystick Gremlin; it stops producing joystick axis events in this case. Ideally we could use a periodic check instead of responding to axis events, but this is currently broken (see https://github.com/WhiteMagic/JoystickGremlin/issues/239).
* The Scroll Speed always gets assigned a default value of `0.0`, due to [a bug](https://github.com/WhiteMagic/JoystickGremlin/issues/358) in Joystick Gremlin. For this reason `0.0` is always treated as `1.0`.
* Maxing out the axis in either direction will cause the scrolling to stop. This is a limitation of Joystick Gremlin; it stops producing joystick axis events in this case. Ideally we could use a periodic check instead of responding to axis events, but periodic callbacks are [currently broken](https://github.com/WhiteMagic/JoystickGremlin/issues/239).
* Any other binds in Joystick Gremlin for this axis will still be executed. A major future improvement is to make the plugin's behavior a first-order action in Joystick Gremlin (i.e., you'd be able to select it where you would normally choose "Remap") but that functionality is not well documented.