From 6c6eb17bd8908775346c384fe87c875ebe7fd833 Mon Sep 17 00:00:00 2001 From: joe Date: Wed, 11 Dec 2024 15:53:09 +0000 Subject: [PATCH] Rename and document input methods --- .../gametest/v1/ClientGameTestInput.java | 279 ++++++++++++++++-- .../gametest/ClientGameTestInputImpl.java | 106 +++---- .../gametest/client/ClientGameTestTest.java | 6 +- 3 files changed, 303 insertions(+), 88 deletions(-) diff --git a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/ClientGameTestInput.java b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/ClientGameTestInput.java index b83d099280..90753d1dd1 100644 --- a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/ClientGameTestInput.java +++ b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/ClientGameTestInput.java @@ -18,6 +18,7 @@ import java.util.function.Function; +import net.minecraft.client.gui.screen.Screen; import net.minecraft.client.option.GameOptions; import net.minecraft.client.option.KeyBinding; import net.minecraft.client.util.InputUtil; @@ -26,68 +27,282 @@ * The client gametest input handler used to simulate inputs to the client. */ public interface ClientGameTestInput { - // TODO: document all these methods - void pressKey(KeyBinding keyBinding); - - void pressKey(Function keyBindingGetter); - - void pressKey(InputUtil.Key key); - - void pressKey(int keyCode); - - void pressMouse(int button); - - void pressControl(); - - void pressShift(); - - void pressAlt(); - + /** + * Starts holding down a key binding. The key binding will be held until it is released. The key binding must be + * bound. + * + * @param keyBinding The key binding to hold + * @see #releaseKey(KeyBinding) + * @see #pressKey(KeyBinding) + * @see #holdKey(Function) + */ + void holdKey(KeyBinding keyBinding); + + /** + * Starts holding down a key binding. The key binding will be held until it is released. The key binding must be + * bound. + * + * @param keyBindingGetter The function to get the key binding from the game options + * @see #releaseKey(Function) + * @see #pressKey(Function) + * @see #holdKey(KeyBinding) + */ + void holdKey(Function keyBindingGetter); + + /** + * Starts holding down a key or mouse button. The key will be held until it is released. + * + * @param key The key or mouse button to hold + * @see #releaseKey(InputUtil.Key) + * @see #pressKey(InputUtil.Key) + */ + void holdKey(InputUtil.Key key); + + /** + * Starts holding down a key. The key will be held until it is released. + * + * @param keyCode The key code of the key to hold + * @see #releaseKey(int) + * @see #pressKey(int) + */ + void holdKey(int keyCode); + + /** + * Starts holding down a mouse button. The mouse button will be held until it is released. + * + * @param button The mouse button to hold + * @see #releaseMouse(int) + * @see #pressMouse(int) + */ + void holdMouse(int button); + + /** + * Starts holding down left control, or left super on macOS. Suitable for triggering + * {@link Screen#hasControlDown()}. The key will be held until it is released. + * + * @see #releaseControl() + */ + void holdControl(); + + /** + * Starts holding down left shift. Suitable for triggering {@link Screen#hasShiftDown()}. The key will be held until + * it is released. + * + * @see #releaseShift() + */ + void holdShift(); + + /** + * Starts holding down left alt. Suitable for triggering {@link Screen#hasAltDown()}. The key will be held until it + * is released. + * + * @see #releaseAlt() + */ + void holdAlt(); + + /** + * Releases a key binding. The key binding must be bound. + * + * @param keyBinding The key binding to release + * @see #holdKey(KeyBinding) + * @see #releaseKey(Function) + */ void releaseKey(KeyBinding keyBinding); + /** + * Releases a key binding. The key binding must be bound. + * + * @param keyBindingGetter The function to get the key binding from the game options + * @see #holdKey(Function) + * @see #releaseKey(KeyBinding) + */ void releaseKey(Function keyBindingGetter); + /** + * Releases a key or mouse button. + * + * @param key The key or mouse button to release + * @see #holdKey(InputUtil.Key) + */ void releaseKey(InputUtil.Key key); + /** + * Releases a key. + * + * @param keyCode The key code of the key to release + * @see #holdKey(int) + */ void releaseKey(int keyCode); + /** + * Releases a mouse button. + * + * @param button The mouse button to release + * @see #holdMouse(int) + */ void releaseMouse(int button); + /** + * Releases left control, or left super on macOS. Suitable for un-triggering {@link Screen#hasControlDown()}. + * + * @see #holdControl() + */ void releaseControl(); + /** + * Releases left shift. Suitable for un-triggering {@link Screen#hasShiftDown()}. + * + * @see #holdShift() + */ void releaseShift(); + /** + * Releases left alt. Suitable for un-triggering {@link Screen#hasAltDown()}. + * + * @see #holdAlt() + */ void releaseAlt(); - void pressReleaseKey(KeyBinding keyBinding); - - void pressReleaseKey(Function keyBindingGetter); - - void pressReleaseKey(InputUtil.Key key); - - void pressReleaseKey(int keyCode); - - void pressReleaseMouse(int button); - - void holdKey(KeyBinding keyBinding, int ticks); + /** + * Presses and releases a key binding. The key binding must be bound. + * + * @param keyBinding The key binding to press + * @see #holdKey(KeyBinding) + * @see #pressKey(Function) + */ + void pressKey(KeyBinding keyBinding); - void holdKey(Function keyBindingGetter, int ticks); + /** + * Presses and releases a key binding. The key binding must be bound. + * + * @param keyBindingGetter The function to get the key binding from the game options + * @see #holdKey(Function) + * @see #pressKey(KeyBinding) + */ + void pressKey(Function keyBindingGetter); - void holdKey(InputUtil.Key key, int ticks); + /** + * Presses and releases a key or mouse button. + * + * @param key The key or mouse button to press. + * @see #holdKey(InputUtil.Key) + */ + void pressKey(InputUtil.Key key); - void holdKey(int keyCode, int ticks); + /** + * Presses and releases a key. + * + * @param keyCode The key code of the key to press + * @see #holdKey(int) + */ + void pressKey(int keyCode); - void holdMouse(int button, int ticks); + /** + * Presses and releases a mouse button. + * + * @param button The mouse button to press + * @see #holdMouse(int) + */ + void pressMouse(int button); + /** + * Holds a key binding for the specified number of ticks and then releases it. Waits until this process is finished. + * The key binding must be bound. + * + * @param keyBinding The key binding to hold + * @param ticks The number of ticks to hold the key binding for + * @see #holdKey(KeyBinding) + * @see #holdKeyFor(Function, int) + */ + void holdKeyFor(KeyBinding keyBinding, int ticks); + + /** + * Holds a key binding for the specified number of ticks and then releases it. Waits until this process is finished. + * The key binding must be bound. + * + * @param keyBindingGetter The key binding to hold + * @param ticks The number of ticks to hold the key binding for + * @see #holdKey(Function) + * @see #holdKeyFor(Function, int) + */ + void holdKeyFor(Function keyBindingGetter, int ticks); + + /** + * Holds a key or mouse button for the specified number of ticks and then releases it. Waits until this process is + * finished. + * + * @param key The key or mouse button to hold + * @param ticks The number of ticks to hold the key or mouse button for + * @see #holdKey(InputUtil.Key) + */ + void holdKeyFor(InputUtil.Key key, int ticks); + + /** + * Holds a key for the specified number of ticks and then releases it. Waits until this process is finished. + * + * @param keyCode The key code of the key to hold + * @param ticks The number of ticks to hold the key for + * @see #holdKey(int) + */ + void holdKeyFor(int keyCode, int ticks); + + /** + * Holds a mouse button for the specified number of ticks and then releases it. Waits until this process is + * finished. + * + * @param button The mouse button to hold + * @param ticks The number of ticks to hold the mouse button for + * @see #holdMouse(int) + */ + void holdMouseFor(int button, int ticks); + + /** + * Types a code point (character). Useful for typing in text boxes. + * + * @param codePoint The code point to type + * @see #typeChars(String) + */ void typeChar(int codePoint); + /** + * Types a sequence of code points (characters) one after the other. Useful for typing in text boxes. + * + * @param chars The code points to type + */ void typeChars(String chars); + /** + * Scrolls the mouse vertically. + * + * @param amount The amount to scroll by + * @see #scroll(double, double) + */ void scroll(double amount); + /** + * Scrolls the mouse horizontally and vertically. + * + * @param xAmount The horizontal amount to scroll by + * @param yAmount The vertical amount to scroll by + * @see #scroll(double) + */ void scroll(double xAmount, double yAmount); + /** + * Sets the cursor position. + * + * @param x The x position of the new cursor position + * @param y The y position of the new cursor position + * @see #moveCursor(double, double) + */ void setCursorPos(double x, double y); + /** + * Moves the cursor position. + * + * @param deltaX The amount to add to the x position of the cursor + * @param deltaY The amount to add to the y position of the cursor + * @see #setCursorPos(double, double) + */ void moveCursor(double deltaX, double deltaY); } diff --git a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/ClientGameTestInputImpl.java b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/ClientGameTestInputImpl.java index 0590cd920f..ea24b1b665 100644 --- a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/ClientGameTestInputImpl.java +++ b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/ClientGameTestInputImpl.java @@ -54,25 +54,25 @@ public void clearKeysDown() { } @Override - public void pressKey(KeyBinding keyBinding) { - ThreadingImpl.checkOnGametestThread("pressKey"); + public void holdKey(KeyBinding keyBinding) { + ThreadingImpl.checkOnGametestThread("holdKey"); Preconditions.checkNotNull(keyBinding, "keyBinding"); - pressKey(getBoundKey(keyBinding, "press")); + holdKey(getBoundKey(keyBinding, "hold")); } @Override - public void pressKey(Function keyBindingGetter) { - ThreadingImpl.checkOnGametestThread("pressKey"); + public void holdKey(Function keyBindingGetter) { + ThreadingImpl.checkOnGametestThread("holdKey"); Preconditions.checkNotNull(keyBindingGetter, "keyBindingGetter"); KeyBinding keyBinding = context.computeOnClient(client -> keyBindingGetter.apply(client.options)); - pressKey(keyBinding); + holdKey(keyBinding); } @Override - public void pressKey(InputUtil.Key key) { - ThreadingImpl.checkOnGametestThread("pressKey"); + public void holdKey(InputUtil.Key key) { + ThreadingImpl.checkOnGametestThread("holdKey"); Preconditions.checkNotNull(key, "key"); if (KEYS_DOWN.add(key)) { @@ -81,38 +81,38 @@ public void pressKey(InputUtil.Key key) { } @Override - public void pressKey(int keyCode) { - ThreadingImpl.checkOnGametestThread("pressKey"); + public void holdKey(int keyCode) { + ThreadingImpl.checkOnGametestThread("holdKey"); - pressKey(InputUtil.Type.KEYSYM.createFromCode(keyCode)); + holdKey(InputUtil.Type.KEYSYM.createFromCode(keyCode)); } @Override - public void pressMouse(int button) { - ThreadingImpl.checkOnGametestThread("pressMouse"); + public void holdMouse(int button) { + ThreadingImpl.checkOnGametestThread("holdMouse"); - pressKey(InputUtil.Type.MOUSE.createFromCode(button)); + holdKey(InputUtil.Type.MOUSE.createFromCode(button)); } @Override - public void pressControl() { - ThreadingImpl.checkOnGametestThread("pressControl"); + public void holdControl() { + ThreadingImpl.checkOnGametestThread("holdControl"); - pressKey(MinecraftClient.IS_SYSTEM_MAC ? InputUtil.GLFW_KEY_LEFT_SUPER : InputUtil.GLFW_KEY_LEFT_CONTROL); + holdKey(MinecraftClient.IS_SYSTEM_MAC ? InputUtil.GLFW_KEY_LEFT_SUPER : InputUtil.GLFW_KEY_LEFT_CONTROL); } @Override - public void pressShift() { - ThreadingImpl.checkOnGametestThread("pressShift"); + public void holdShift() { + ThreadingImpl.checkOnGametestThread("holdShift"); - pressKey(InputUtil.GLFW_KEY_LEFT_SHIFT); + holdKey(InputUtil.GLFW_KEY_LEFT_SHIFT); } @Override - public void pressAlt() { - ThreadingImpl.checkOnGametestThread("pressAlt"); + public void holdAlt() { + ThreadingImpl.checkOnGametestThread("holdAlt"); - pressKey(InputUtil.GLFW_KEY_LEFT_ALT); + holdKey(InputUtil.GLFW_KEY_LEFT_ALT); } @Override @@ -186,89 +186,89 @@ private static void pressOrReleaseKey(MinecraftClient client, InputUtil.Key key, } @Override - public void pressReleaseKey(KeyBinding keyBinding) { - ThreadingImpl.checkOnGametestThread("pressReleaseKey"); + public void pressKey(KeyBinding keyBinding) { + ThreadingImpl.checkOnGametestThread("pressKey"); Preconditions.checkNotNull(keyBinding, "keyBinding"); - pressReleaseKey(getBoundKey(keyBinding, "press and release")); + pressKey(getBoundKey(keyBinding, "press")); } @Override - public void pressReleaseKey(Function keyBindingGetter) { - ThreadingImpl.checkOnGametestThread("pressReleaseKey"); + public void pressKey(Function keyBindingGetter) { + ThreadingImpl.checkOnGametestThread("pressKey"); Preconditions.checkNotNull(keyBindingGetter, "keyBindingGetter"); KeyBinding keyBinding = context.computeOnClient(client -> keyBindingGetter.apply(client.options)); - pressReleaseKey(keyBinding); + pressKey(keyBinding); } @Override - public void pressReleaseKey(InputUtil.Key key) { - ThreadingImpl.checkOnGametestThread("pressReleaseKey"); + public void pressKey(InputUtil.Key key) { + ThreadingImpl.checkOnGametestThread("pressKey"); Preconditions.checkNotNull(key, "key"); - pressKey(key); + holdKey(key); releaseKey(key); } @Override - public void pressReleaseKey(int keyCode) { - ThreadingImpl.checkOnGametestThread("pressReleaseKey"); + public void pressKey(int keyCode) { + ThreadingImpl.checkOnGametestThread("pressKey"); - pressReleaseKey(InputUtil.Type.KEYSYM.createFromCode(keyCode)); + pressKey(InputUtil.Type.KEYSYM.createFromCode(keyCode)); } @Override - public void pressReleaseMouse(int button) { - ThreadingImpl.checkOnGametestThread("pressReleaseMouse"); + public void pressMouse(int button) { + ThreadingImpl.checkOnGametestThread("pressMouse"); - pressReleaseKey(InputUtil.Type.MOUSE.createFromCode(button)); + pressKey(InputUtil.Type.MOUSE.createFromCode(button)); } @Override - public void holdKey(KeyBinding keyBinding, int ticks) { - ThreadingImpl.checkOnGametestThread("holdKey"); + public void holdKeyFor(KeyBinding keyBinding, int ticks) { + ThreadingImpl.checkOnGametestThread("holdKeyFor"); Preconditions.checkNotNull(keyBinding, "keyBinding"); Preconditions.checkArgument(ticks > 0, "ticks must be positive"); - holdKey(getBoundKey(keyBinding, "hold"), ticks); + holdKeyFor(getBoundKey(keyBinding, "hold"), ticks); } @Override - public void holdKey(Function keyBindingGetter, int ticks) { - ThreadingImpl.checkOnGametestThread("holdKey"); + public void holdKeyFor(Function keyBindingGetter, int ticks) { + ThreadingImpl.checkOnGametestThread("holdKeyFor"); Preconditions.checkNotNull(keyBindingGetter, "keyBindingGetter"); Preconditions.checkArgument(ticks > 0, "ticks must be positive"); KeyBinding keyBinding = context.computeOnClient(client -> keyBindingGetter.apply(client.options)); - holdKey(keyBinding, ticks); + holdKeyFor(keyBinding, ticks); } @Override - public void holdKey(InputUtil.Key key, int ticks) { - ThreadingImpl.checkOnGametestThread("holdKey"); + public void holdKeyFor(InputUtil.Key key, int ticks) { + ThreadingImpl.checkOnGametestThread("holdKeyFor"); Preconditions.checkNotNull(key, "key"); Preconditions.checkArgument(ticks > 0, "ticks must be positive"); - pressKey(key); + holdKey(key); context.waitTicks(ticks); releaseKey(key); } @Override - public void holdKey(int keyCode, int ticks) { - ThreadingImpl.checkOnGametestThread("holdKey"); + public void holdKeyFor(int keyCode, int ticks) { + ThreadingImpl.checkOnGametestThread("holdKeyFor"); Preconditions.checkArgument(ticks > 0, "ticks must be positive"); - holdKey(InputUtil.Type.KEYSYM.createFromCode(keyCode), ticks); + holdKeyFor(InputUtil.Type.KEYSYM.createFromCode(keyCode), ticks); } @Override - public void holdMouse(int button, int ticks) { - ThreadingImpl.checkOnGametestThread("holdMouse"); + public void holdMouseFor(int button, int ticks) { + ThreadingImpl.checkOnGametestThread("holdMouseFor"); Preconditions.checkArgument(ticks > 0, "ticks must be positive"); - holdKey(InputUtil.Type.MOUSE.createFromCode(button), ticks); + holdKeyFor(InputUtil.Type.MOUSE.createFromCode(button), ticks); } @Override diff --git a/fabric-client-gametest-api-v1/src/testmodClient/java/net/fabricmc/fabric/test/gametest/client/ClientGameTestTest.java b/fabric-client-gametest-api-v1/src/testmodClient/java/net/fabricmc/fabric/test/gametest/client/ClientGameTestTest.java index 4460826cef..7e8fe43dc1 100644 --- a/fabric-client-gametest-api-v1/src/testmodClient/java/net/fabricmc/fabric/test/gametest/client/ClientGameTestTest.java +++ b/fabric-client-gametest-api-v1/src/testmodClient/java/net/fabricmc/fabric/test/gametest/client/ClientGameTestTest.java @@ -82,10 +82,10 @@ public void runTest(ClientGameTestContext context) { } { - context.getInput().pressReleaseKey(options -> options.chatKey); + context.getInput().pressKey(options -> options.chatKey); context.waitTick(); context.getInput().typeChars("Hello, World!"); - context.getInput().pressReleaseKey(InputUtil.GLFW_KEY_ENTER); + context.getInput().pressKey(InputUtil.GLFW_KEY_ENTER); context.takeScreenshot("chat_message_sent", 5); } @@ -99,7 +99,7 @@ public void runTest(ClientGameTestContext context) { } { - context.getInput().pressReleaseKey(options -> options.inventoryKey); + context.getInput().pressKey(options -> options.inventoryKey); context.takeScreenshot("in_game_inventory"); context.setScreen(null); }