Differences

This shows you the differences between two versions of the page.

--- tutorial:callbacks [2020/02/17 18:26] – accept suggestions from @JamiesWhiteShirt et al. at Discord (renaming) & Add events mkpoli
+++ tutorial:callbacks [2021/07/26 23:00] – Typo daomephsta
@@ Line 1: / Line 1: @@
-====== Register a Callback on an existing Event (DRAFT) ======
+====== Listening to Events ======
-In this tutorial, you are going to achieve:
+In this tutorial you will learn to:
   - Understand Events and Callbacks
-  - Be able to register a Callback on an existing Event
+  - Register a callback for an existing Event
-===== Callback Interfaces =====
+===== Events =====
-There is a series of interfaces named [EventName]Callback. They will handle the events (get called by mixins), invoke callbacks which are registered on mod initialization.
+Events are represented by instances of ''net.fabricmc.fabric.api.event.Event'' which store and call callbacks. Often there is a single event instance for a callback, which is stored in a static field ''EVENT'' of the callback interface, but there are other patterns. For example [[https://github.com/FabricMC/fabric/blob/1.17/fabric-lifecycle-events-v1/src/main/java/net/fabricmc/fabric/api/client/event/lifecycle/v1/ClientTickEvents.java|ClientTickEvents]] groups several related events together.
+===== Callbacks =====
+Each event has a corresponding callback interface, conventionally named ''EventNameCallback''. Callbacks are registered by calling ''register()'' on an event instance with an instance of the callback interface as the argument.
 ==== Callback Interfaces in Fabric API ====
-Event Callbacks provided by Fabric API can be found in ''net.fabricmc.fabric.api.event'' package.
+All event callback interfaces provided by Fabric API can be found in the ''net.fabricmc.fabric.api.event'' package.
+A partial list of existing callbacks is provided at the bottom of this tutorial.
-Here is a partial list of existing callbacks.
+==== Custom Callbacks ====
+Although there are plenty of events already provided by Fabric API, you can still make your own events. Please refer to [[tutorial:events]].
-=== Player Interactive Events ===
+===== Practice ======
+This example registers an ''AttackBlockCallback'' to damage players when they hit blocks that don't drop when hand-mined. It returns ''<yarn class_1269.field_5811>'' as other callbacks should still be called. See the [[https://github.com/FabricMC/fabric/blob/12865e786ce2102d344304a679b70084be84d166/fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/AttackBlockCallback.java#L29-L39|AttackBlockCallback]] JavaDoc in your IDE for the meaning of other values.
+<yarncode java [enable_line_numbers="true"]>
+public class ExampleMod implements ModInitializer
+{
+    [...]
+    @Override
+    public void onInitialize()
+    {
+        AttackBlockCallback.EVENT.register((player, world, hand, pos, direction) ->
+        {
+            class_2680 state = world.method_8320(pos);
+            /* Manual spectator check is necessary because AttackBlockCallbacks
+               fire before the spectator check */
+            if (state.method_29291() && !player.method_7325() &&
+                player.method_6047().method_7960())
+            {
+                player.method_5643(class_1282.field_5869, 1.0F);
+            }
+            return class_1269.field_5811;
+        });
+    }
+}
+</yarncode>
+===== Fabric API Events ======
+=== Player Interaction Events ===
 Player: [[https://github.com/FabricMC/fabric/blob/1.15/fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/AttackBlockCallback.java|AttackBlockCallback]] / [[https://github.com/FabricMC/fabric/blob/1.15/fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/AttackEntityCallback.java|AttackEntityCallback]] / [[https://github.com/FabricMC/fabric/blob/1.15/fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/UseBlockCallback.java|UseBlockCallback]] / [[https://github.com/FabricMC/fabric/blob/1.15/fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/UseEntityCallback.java|UseEntityCallback]] / [[https://github.com/FabricMC/fabric/blob/1.15/fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/UseItemCallback.java|UseItemCallback]]
@@ Line 25: / Line 58: @@
 [[https://github.com/FabricMC/fabric/blob/1.15/fabric-loot-tables-v1/src/main/java/net/fabricmc/fabric/api/loot/v1/event/LootTableLoadingCallback.java|LootTableLoadingCallback]]
-There is an example using ''LootTableLoadingCallback'' you can find [[tutorial:adding_to_loot_tables|here]].
+There is an example of using ''LootTableLoadingCallback'' [[tutorial:adding_to_loot_tables|here]].
 === World Events ===
@@ Line 35: / Line 68: @@
 === Network Events ===
 [[https://github.com/FabricMC/fabric/blob/1.15/fabric-networking-v0/src/main/java/net/fabricmc/fabric/api/event/network/C2SPacketTypeCallback.java|C2SPacketTypeCallback]] / [[https://github.com/FabricMC/fabric/blob/1.15/fabric-networking-v0/src/main/java/net/fabricmc/fabric/api/event/network/S2CPacketTypeCallback.java|S2CPacketTypeCallback]]
-==== Custom Callbacks ====
-Although there are plenty of events already provided by Fabric API, you can still make your own events. Please refer to [[tutorial:events]].
-===== Practice ======
-<!-- TODO: Add explaination -->
-Let's see Take ''AttackBlockCallback'' as an example for how register a listener
-Basically, we are going to ... (an event listener) callback to listen the event.
-Since there is not more a method that is able to be called on a block clicked, you may want to. If you want to make a ;
-As stated in javadoc of ''AttackBlockCallback'', this event accepts ; You can interrupt and stop continuing by sending ActionResult.SUCCESS;
-<code java>
-/**
- * Callback for left-clicking ("attacking") a block.
- * Is hooked in before the spectator check, so make sure to check for the player's game mode as well!
- *
- * <p>Upon return:
- * <ul><li>SUCCESS cancels further processing and, on the client, sends a packet to the server.
- * <li>PASS falls back to further processing.
- * <li>FAIL cancels further processing and does not send a packet to the server.</ul>
- *
- * <p>ATTACK_BLOCK does not let you control the packet sending process yet.
- */
-</code>
-<!-- TODO: Really do sth. -->
-<code java [enable_line_numbers="true"]>
-public class ExampleMod implements ModInitializer
-{
-    [...]
-    @Override
-    public void onInitialize() {
-        AttackBlockCallback.EVENT.register((player, world, hand, pos, direction) -> {
-            // Do sth...
-            if ([condition]) {
-                return ActionResult.SUCCESS;
-            } else {
-                return ActionResult.PASS;
-            }
-        })
-    }
-}
-</code>
-<!-- TODO: An image of the effect of something have done -->