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 keyBindingGetter); /** - * Presses and releases a key or mouse button. + * Presses and releases a key or 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 #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 @@ * *