diff --git a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/TestInput.java b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/TestInput.java index 9fd8e8da4a..16f35173b3 100644 --- a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/TestInput.java +++ b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/TestInput.java @@ -34,6 +34,8 @@ public interface TestInput { * Starts holding down a key binding. The key binding will be held until it is released. The key binding must be * bound. Does nothing if the key binding is already being held. * + *
Most key bindings will only start reacting to this when a tick is waited. + * * @param keyBinding The key binding to hold * @see #releaseKey(KeyBinding) * @see #pressKey(KeyBinding) @@ -45,6 +47,8 @@ public interface TestInput { * Starts holding down a key binding. The key binding will be held until it is released. The key binding must be * bound. Does nothing if the key binding is already being held. * + *
Most key bindings will only start reacting to this when a tick is waited. + * * @param keyBindingGetter The function to get the key binding from the game options * @see #releaseKey(Function) * @see #pressKey(Function) @@ -56,6 +60,8 @@ public interface TestInput { * Starts holding down a key or mouse button. The key will be held until it is released. Does nothing if the key or * mouse button is already being held. * + *
Most key bindings will only start reacting to this when a tick is waited. + * * @param key The key or mouse button to hold * @see #releaseKey(InputUtil.Key) * @see #pressKey(InputUtil.Key) @@ -66,6 +72,8 @@ public interface TestInput { * Starts holding down a key. The key will be held until it is released. Does nothing if the key is already being * held. * + *
Most key bindings will only start reacting to this when a tick is waited. + * * @param keyCode The key code of the key to hold * @see #releaseKey(int) * @see #pressKey(int) @@ -76,6 +84,8 @@ public interface TestInput { * Starts holding down a mouse button. The mouse button will be held until it is released. Does nothing if the mouse * button is already being held. * + *
Most key bindings will only start reacting to this when a tick is waited. + * * @param button The mouse button to hold * @see #releaseMouse(int) * @see #pressMouse(int) @@ -110,6 +120,8 @@ public interface TestInput { /** * Releases a key binding. The key binding must be bound. Does nothing if the key binding is not being held. * + *
Most key bindings will only react to this when a tick is waited. + * * @param keyBinding The key binding to release * @see #holdKey(KeyBinding) * @see #releaseKey(Function) @@ -119,6 +131,8 @@ public interface TestInput { /** * Releases a key binding. The key binding must be bound. Does nothing if the key binding is not being held. * + *
Most key bindings will only react to this when a tick is waited. + * * @param keyBindingGetter The function to get the key binding from the game options * @see #holdKey(Function) * @see #releaseKey(KeyBinding) @@ -128,6 +142,8 @@ public interface TestInput { /** * Releases a key or mouse button. Does nothing if the key or mouse button is not being held. * + *
Most key bindings will only react to this when a tick is waited. + * * @param key The key or mouse button to release * @see #holdKey(InputUtil.Key) */ @@ -136,6 +152,8 @@ public interface TestInput { /** * Releases a key. Does nothing if the key is not being held. * + *
Most key bindings will only react to this when a tick is waited. + * * @param keyCode The GLFW key code of the key to release * @see #holdKey(int) */ @@ -144,6 +162,8 @@ public interface TestInput { /** * Releases a mouse button. Does nothing if the mouse button is not being held. * + *
Most key bindings will only react to this when a tick is waited. + * * @param button The GLFW mouse button to release * @see #holdMouse(int) */ @@ -174,7 +194,10 @@ public interface TestInput { void releaseAlt(); /** - * Presses and releases a key binding. The key binding must be bound. + * Presses and releases a key binding, then waits a tick. The key binding must be bound. + * + *
A tick is waited because most key bindings need a tick to happen to react to the press. If you don't want the + * delay, use {@link #holdKeyFor(KeyBinding, int) holdKeyFor} with a tick count of {@code 0}. * * @param keyBinding The key binding to press * @see #holdKey(KeyBinding) @@ -183,7 +206,10 @@ public interface TestInput { void pressKey(KeyBinding keyBinding); /** - * Presses and releases a key binding. The key binding must be bound. + * Presses and releases a key binding, then waits a tick. The key binding must be bound. + * + *
A tick is waited because most key bindings need a tick to happen to react to the press. If you don't want the
+ * delay, use {@link #holdKeyFor(Function, int) holdKeyFor} with a tick count of {@code 0}.
*
* @param keyBindingGetter The function to get the key binding from the game options
* @see #holdKey(Function)
@@ -192,7 +218,10 @@ public interface TestInput {
void pressKey(Function A tick is waited because most key bindings need a tick to happen to react to the press. If you don't want the
+ * delay, use {@link #holdKeyFor(InputUtil.Key, int) holdKeyFor} with a tick count of {@code 0}.
*
* @param key The key or mouse button to press.
* @see #holdKey(InputUtil.Key)
@@ -200,7 +229,10 @@ public interface TestInput {
void pressKey(InputUtil.Key key);
/**
- * Presses and releases a key.
+ * Presses and releases a key, then waits a tick.
+ *
+ * A tick is waited because most key bindings need a tick to happen to react to the press. If you don't want the
+ * delay, use {@link #holdKeyFor(int, int) holdKeyFor} with a tick count of {@code 0}.
*
* For sending Unicode text input (e.g. into text boxes), use {@link #typeChar(int)} or
* {@link #typeChars(String)} instead.
@@ -211,7 +243,10 @@ public interface TestInput {
void pressKey(int keyCode);
/**
- * Presses and releases a mouse button.
+ * Presses and releases a mouse button, then waits a tick.
+ *
+ * A tick is waited because most key bindings need a tick to happen to react to the press. If you don't want the
+ * delay, use {@link #holdMouseFor(int, int) holdMouseFor} with a tick count of {@code 0}.
*
* @param button The GLFW mouse button to press
* @see #holdMouse(int)
@@ -222,6 +257,9 @@ public interface TestInput {
* 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.
*
+ * Although the key will be released when this method returns, most key bindings will only react to this
+ * when a tick is waited.
+ *
* @param keyBinding The key binding to hold
* @param ticks The number of ticks to hold the key binding for
* @see #holdKey(KeyBinding)
@@ -233,6 +271,9 @@ public interface TestInput {
* 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.
*
+ * Although the key will be released when this method returns, most key bindings will only react to this
+ * when a tick is waited.
+ *
* @param keyBindingGetter The key binding to hold
* @param ticks The number of ticks to hold the key binding for
* @see #holdKey(Function)
@@ -244,6 +285,9 @@ public interface TestInput {
* Holds a key or mouse button for the specified number of ticks and then releases it. Waits until this process is
* finished.
*
+ * Although the key or mouse button will be released when this method returns, most key bindings will
+ * only react to this when a tick is waited.
+ *
* @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)
@@ -253,6 +297,9 @@ public interface TestInput {
/**
* Holds a key for the specified number of ticks and then releases it. Waits until this process is finished.
*
+ * Although the key will be released when this method returns, most key bindings will only react to this
+ * when a tick is waited.
+ *
* @param keyCode The GLFW key code of the key to hold
* @param ticks The number of ticks to hold the key for
* @see #holdKey(int)
@@ -263,6 +310,9 @@ public interface TestInput {
* Holds a mouse button for the specified number of ticks and then releases it. Waits until this process is
* finished.
*
+ * Although the mouse button will be released when this method returns, most key bindings will only react
+ * to this when a tick is waited.
+ *
* @param button The GLFW mouse button to hold
* @param ticks The number of ticks to hold the mouse button for
* @see #holdMouse(int)
diff --git a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/package-info.java b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/package-info.java
index d89e5df6b6..460182b838 100644
--- a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/package-info.java
+++ b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/api/client/gametest/v1/package-info.java
@@ -17,6 +17,14 @@
*
* The game remains paused unless you explicitly unpause it using various waiting functions such as
* {@link net.fabricmc.fabric.api.client.gametest.v1.ClientGameTestContext#waitTick() ClientGameTestContext.waitTick()}.
+ * A side effect of this is that the results of your code may not be immediate if the game needs a tick to
+ * process them. A big example of this is key bindings, although some key binding methods have built-in tick
+ * waits to mitigate the issue. See the {@link net.fabricmc.fabric.api.client.gametest.v1.TestInput TestInput}
+ * documentation for details. Another pseudo-example is effects on the server need a tick to propagate to the client and
+ * vice versa, although this is related to packets more than the fact the game is suspended (see the network
+ * synchronization section below). A good strategy for debugging these issues is by
+ * {@linkplain net.fabricmc.fabric.api.client.gametest.v1.ClientGameTestContext#takeScreenshot(String) taking screenshots},
+ * which capture the immediate state of the game.
*
* A few changes have been made to how the vanilla game threads run, to make tests more reproducible. Notably, there
* is exactly one server tick per client tick while a server is running (singleplayer or multiplayer). There is also a
diff --git a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/NetworkSynchronizer.java b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/NetworkSynchronizer.java
index 3a0ac268d3..d8d65b0909 100644
--- a/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/NetworkSynchronizer.java
+++ b/fabric-client-gametest-api-v1/src/client/java/net/fabricmc/fabric/impl/client/gametest/NetworkSynchronizer.java
@@ -37,7 +37,7 @@
*
*
*
*