https://github.com/r-unic/mechanism

An elegant input wrapper for Roblox
https://github.com/r-unic/mechanism

Last synced: 10 days ago
JSON representation

An elegant input wrapper for Roblox

• Host: GitHub
• URL: https://github.com/r-unic/mechanism
• Owner: R-unic
• Created: 2024-12-27T06:47:16.000Z (13 days ago)
• Default Branch: master
• Last Pushed: 2024-12-27T21:33:29.000Z (13 days ago)
• Last Synced: 2024-12-27T21:36:19.075Z (13 days ago)
• Language: TypeScript
• Size: 10.7 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Mechanism

An elegant composable input library for Roblox

## Examples

### Creating an InputManager

An `InputManager` is a context to bind actions to. It is disposable and unbinds all actions when destroyed.


The constructor takes a `useAllGamepads` parameter, which when false only uses `Gamepad1` and not any other gamepad input type.

```ts

import { InputManager, StandardActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const action = new StandardActionBuilder().setID("testID");

input.bind(action);

input.unbind(action);

input.unbind("testID");

```

### StandardAction

```ts

import { InputManager, StandardActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const crouchAction = new StandardActionBuilder("C", "LeftCtrl")

  .setProcessed(false) // only activates when gameProcessedEvent is false, false by default

  .setCooldown(0.25); // can only be activated every 0.25 seconds

  .setInputQueueing(false); // if this were true, it would queue every input made during a cooldown to be activated after the cooldown is over

crouchAction.activated.Connect(() => print("crouched"));

crouchAction.deactivated.Connect(() => print("stood"));

input.bind(crouchAction);

```

### AxisAction

```ts

import { InputManager, AxisActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const scrollAction = new AxisActionBuilder("MouseWheel");

scrollAction.updated.Connect(() => print("scroll position:", scrollAction.position.Z));

input.bind(scrollAction);

```

### RepeatAction

A `RepeatAction` is an input that must be repeated multiple times to activate.

```ts

import { InputManager, RepeatActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const sprintAction = new RepeatActionBuilder("W")

  .setRepeats(2) // takes 2 presses to activate

  .setTiming(0.3); // each press must be within 0.3 seconds of each other, 0 by default (which is infinite time between presses)

sprintAction.activated.Connect(() => print("sprinting"));

sprintAction.deactivated.Connect(() => print("walking"));

input.bind(sprintAction);

```

### CompositeAction

A `CompositeAction` is an action composed of multiple inputs that must all be simultaneously pressed to activate the action. The action is deactivated when one of the inputs is released.

```ts

import { InputManager, CompositeActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const toggleAction = new CompositeActionBuilder("LeftCtrl", "LeftAlt", "M")

  .setTiming(0.5); // each press must be within 0.5 seconds of each other

toggleAction.activated.Connect(() => print("toggled"));

input.bind(toggleAction);

```

### SequentialAction

A `SequentialAction` is an action composed of multiple inputs that must all be pressed in order to activate the action. The action is deactivated when one of the last input in the sequence is released.

```ts

import { InputManager, SequentialActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const menAction = new SequentialActionBuilder("M", "E", "N")

  .setTiming(0.5); // each press must be within 0.5 seconds of each other

menAction.activated.Connect(() => print("typed 'men' quickly"));

input.bind(menAction);

```

### UniqueAction

A `UniqueAction` is an action composed of multiple child actions and is only active when exactly one of the child actions is active.

```ts

import { InputManager, UniqueActionBuilder } from "@rbxts/mechanism";

const input = new InputManager;

const cOrVAction = new UniqueActionBuilder(

  new StandardActionBuilder("C"),

  new StandardActionBuilder("V")

);

cOrVAction.activated.Connect(() => print("pressed C or V exclusively"));

input.bind(cOrVAction);

```

### DynamicAction

A `DynamicAction` is an action containing one interchangable action.

```ts

import { InputManager, DynamicAction } from "@rbxts/mechanism";

const input = new InputManager;

const crouchAction = new DynamicAction(new StandardActionBuilder("C")); // default bind

keybinds.changed.Connect(keybinds => 

  crouchAction.updateAction(new StandardActionBuilder(keybinds.crouch)) // update bind based on data

);

crouchAction.activated.Connect(() => print("crouched"));

crouchAction.deactivated.Connect(() => print("stood"));

input.bind(crouchAction);

```