Skip to content

Commit

Permalink
docs: revise isKey/isButton checks and add examples (#484) cherry-pick (
Browse files Browse the repository at this point in the history
#488)

Co-authored-by: imaginarny <[email protected]>
  • Loading branch information
niceEli and imaginarny authored Oct 31, 2024
1 parent 8f0d864 commit cae018b
Showing 1 changed file with 116 additions and 10 deletions.
126 changes: 116 additions & 10 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2168,38 +2168,114 @@ export interface KAPLAYCtx<
*/
mouseDeltaPos(): Vec2;
/**
* If certain keys are currently down.
* If any or certain key(s) are currently down.
*
* @example
* ```js
* // Any key down
*
* let lastKeyTime = time()
* let triedToWakeUp = false
*
* onUpdate(() => {
* if (isKeyDown()) {
* lastKeyTime = time()
* triedToWakeUp = false
* return
* }
*
* if (triedToWakeUp || time() - lastKeyTime < 5) return
*
* debug.log("Wake up!")
* triedToWakeUp = true
* })
*
* // Certain key down
* // equivalent to the calling bean.move() in an onKeyDown("left")
*
* onUpdate(() => {
* if (isKeyDown("left")) {
* bean.move(-SPEED, 0)
* }
* })
*
* // Certain keys down
*
* let isMoving = false
*
* onUpdate(() => {
* isMoving = isKeyDown(["left", "right"])
* })
* ```
*
* @since v3001.0
* @group Input
*/
isKeyDown(k?: Key | Key[]): boolean;
/**
* If certain keys are just pressed last frame.
* If any or certain key(s) are just pressed last frame.
*
* @example
* ```js
* onUpdate(() => {
* if (!isKeyPressed()) return // early return as no key was pressed
*
* if (isKeyPressed("space")) debug.log("Pressed the jump key")
* if (isKeyPressed(["left", "right"])) debug.log("Pressed any of the move keys")
* })
* ```
*
* @since v3001.0
* @group Input
*/
isKeyPressed(k?: Key | Key[]): boolean;
/**
* If certain keys are just pressed last frame (also fires repeatedly when the keys are being held down).
* If any or certain key(s) are just pressed last frame (also fires repeatedly when the keys are being held down).
*
* @example
* ```js
* let heldKeys = new Set()
*
* onUpdate(() => {
* if (isKeyPressedRepeat("space")) {
* pressedOrHeld(["space"], 'the jump key')
* } else if (isKeyPressedRepeat(["left", "right"])) {
* pressedOrHeld(["left", "right"], 'any of the move keys')
* } else if (isKeyPressedRepeat()) {
* pressedOrHeld(["any"], 'any key')
* }
* })
*
* onKeyRelease((key) => wait(0.1, () => {
* heldKeys.delete(key)
* heldKeys.delete("any")
* }))
*
* // log message if pressed only or held as well
* function pressedOrHeld(keys, string) {
* debug.log(`Pressed${keys.some(key => heldKeys.has(key)) ? ' and held' : ''} ${string}`)
* keys.forEach((key) => {
* if (key == "any" || isKeyDown(key)) heldKeys.add(key)
* })
* }
* ```
*
* @since v3001.0
* @group Input
*/
isKeyPressedRepeat(k?: Key | Key[]): boolean;
/**
* If certain keys are just released last frame.
* If any or certain key(s) are just released last frame.
*
* @example
* ```js
* onUpdate(() => {
* if (!isKeyReleased()) return // early return as no key was released
*
* if (isKeyReleased("space")) debug.log("Released the jump key")
* if (isKeyReleased(["left", "right"])) debug.log("Released any of the move keys")
* })
* ```
*
* @since v3001.0
* @group Input
Expand Down Expand Up @@ -2255,26 +2331,56 @@ export interface KAPLAYCtx<
*/
isGamepadButtonReleased(btn?: KGamepadButton | KGamepadButton[]): boolean;
/**
* If certain bound buttons are just pressed last frame on any input (keyboard, gamepad).
* If any or certain bound button(s) are just pressed last frame on any input (keyboard, gamepad).
*
* @example
* ```js
* onUpdate(() => {
* if (!isButtonPressed()) return // early return as no button was pressed
*
* if (isButtonPressed("jump")) debug.log("Player jumped")
* if (isButtonPressed(["left", "right"])) debug.log("Player moved")
* })
* ```
*
* @since v3001.0
* @group Input
*/
isButtonPressed(button: TButton | TButton[]): boolean;
isButtonPressed(button?: TButton | TButton[]): boolean;
/**
* If certain bound buttons are currently held down on any input (keyboard, gamepad).
* If any or certain bound button(s) are currently held down on any input (keyboard, gamepad).
*
* @example
* ```js
* onUpdate(() => {
* if (!isButtonDown()) return // early return as no button is held down
*
* if (isButtonDown("jump")) debug.log("Player is jumping")
* if (isButtonDown(["left", "right"])) debug.log("Player is moving")
* })
* ```
*
* @since v3001.0
* @group Input
*/
isButtonDown(button: TButton | TButton[]): boolean;
isButtonDown(button?: TButton | TButton[]): boolean;
/**
* If certain bound buttons are just released last frame on any input (keyboard, gamepad).
* If any or certain bound button(s) are just released last frame on any input (keyboard, gamepad).
*
* @example
* ```js
* onUpdate(() => {
* if (!isButtonReleased()) return // early return as no button was released
*
* if (isButtonReleased("jump")) debug.log("Player stopped jumping")
* if (isButtonReleased(["left", "right"])) debug.log("Player stopped moving")
* })
* ```
*
* @since v3001.0
* @group Input
*/
isButtonReleased(button: TButton | TButton[]): boolean;
isButtonReleased(button?: TButton | TButton[]): boolean;
/**
* Get a input binding from a button name.
*
Expand Down

0 comments on commit cae018b

Please sign in to comment.