# Fabric Lifecycle Events (V1)

## Drafting note - Not in final draft
By commenting on this document, you agree to license your comments under the Apache 2.0 License <http://www.apache.org/licenses/LICENSE-2.0.txt> as this is intended to go into a final fabric api readme PR.

By commenting, you agree to license your suggestions/comments under apache 2.0 for use with improving these readmes. If you do not agree to the terms, please do not comment on this this document.

Events for hooking into the lifecycle of Minecraft's Client and Server.
This module is organized into `Client` and `Server` event classes.

## Organization

Events in this module belong to a single class which relates to the category of events. The implementation of event invokers are sub classes. For example, `ServerLifecycleEvents.SERVER_STARTING` belongs in `ServerLifecycleEvents` and the implementation of the event's invoker is `ServerLifecycleEvents.ServerStarting`.

# Server Events

Events related to objects on a logical server.

## `ServerLifecycleEvents`

Contains lifecycle events related to a Minecraft Server.

### `ServerLifecycleEvents.SERVER_STARTING`

- Called when a Minecraft server is starting. This is called before any worlds are loaded, no players are connected yet and the `PlayerManager` is null.
- Mods which rely on tracking the current server instance may use this event to capture the server instance.

### `ServerLifecycleEvents.SERVER_STARTED`

- Called when a Minecraft server has finshed starting and is about to tick for the first time. When this event is called, all worlds have been loaded and players are ready to be accepted.

### `ServerLifecycleEvents.SERVER_STOPPING`

- Called when a Minecraft server has started shutting down.
- This occurs before the server's network channel is closed and before any connected players are disconnected.

### `ServerLifecycleEvents.SERVER_STOPPED`

- Called when a Minecraft server has stopped.
All worlds have been closed and all (block) entities and players have been unloaded.
- If a mod stores the server instance anywhere, this event should be used for reference cleanup.
- Depending on the implementation of the server the following may occur after this event is called:
- On an integrated server (`EnvType.CLIENT`), the client will continue running.
- On a dedicated server (`EnvType.SERVER`), this will be the last event called. The JVM will terminate after this event.

### `ServerLifecycleEvents.START_DATA_PACK_RELOAD`
- Called before a Minecraft server reloads data packs.
- In vanilla, this is typically called after `/reload` command is executed.

### `ServerLifecycleEvents.END_DATA_PACK_RELOAD`
- Called after a Minecraft server has reloaded data packs.
- This event does not garuntee the data pack reload was successful.
- Per the `EndDataPackReload` interface, the last `boolean` parameter specifies whether the data pack reload was successful.

@FunctionalInterface
public interface EndDataPackReload {
    void endDataPackReload(MinecraftServer server, ServerResourceManager serverResourceManager, boolean success);
}

- If the data pack reload is successful, data packs will be set. If the reload failed, then the currently loaded data packs will be kept.

## `ServerTickEvents`
- Contains events related to the ticking of a Minecraft server.

### `ServerTickEvents.START_SERVER_TICK`
- Called at the start of the server tick.
- This event can be used by mods to pre-process before the server tick occurs.

### `ServerTickEvents.END_SERVER_TICK`
- Called at the end of the server tick.

### `ServerTickEvents.START_WORLD_TICK`
- Called at the start of a ServerWorld's tick.

### `ServerTickEvents.END_WORLD_TICK`
- Called at the end of a ServerWorld's tick.
- End of world tick may be used to start async computations for the next tick.

## `ServerWorldEvents`

Events related to the lifecycle of server worlds.

### `ServerWorldEvents.LOAD`
- Called when a world is loaded by a Minecraft server.
- This event may be called at any time, but is typically called between `ServerLifecycleEvents.SERVER_STARTING` and `ServerLifecycleEvents.SERVER_STARTED`.
- Mods which implement dynamically loaded dimensions may call this event to notify other mods of a new server world being loaded.

### `ServerWorldEvents.UNLOAD`
- Called before a world is unloaded by a Minecraft server.
- This event may be called at any time but is typically called after a server has started shutting down (`ServerLifecycleEvents.SERVER_STOPPING`).
- Mods which implement dynamically loaded dimensions may call this event to notify other mods of a server world being unloaded for reference cleanup.

## `ServerChunkEvents`

Events related to the lifecycle of chunks in a server world.

### `ServerChunkEvents.CHUNK_LOAD`
- Called when an chunk is loaded into a ServerWorld.
- The chunk may be modified when this event is called.

### `ServerChunkEvents.CHUNK_UNLOAD`
- Called when an chunk is unloaded from a ServerWorld.
- The chunk may be modified when this event is called.

## `ServerEntityEvents`

Events related to the lifecycle of entities in a server world.

### `ServerEntityEvents.ENTITY_LOAD`
- Called when an Entity is loaded into a ServerWorld.
- The entity is present in the server world when this event is called.
- **The unload event has not been implemented yet.**

## `ServerBlockEntityEvents`

Events related to the lifecycle of block entities in a server world.

### `ServerBlockEntityEvents.BLOCK_ENTITY_LOAD`
- Called when an BlockEntity is loaded into a ServerWorld.
- The block entity is present in the server world when this event is called.

### `ServerBlockEntityEvents.BLOCK_ENTITY_UNLOAD`
- Called when an BlockEntity is about to be unloaded from a ServerWorld.
- The block entity is present in the server world when this event is called.

# Client Events

Events related to objects on a logical client.

## `ClientLifecycleEvents`

Events related to the lifecycle of a Minecraft client

### `ClientLifecycleEvents.CLIENT_STARTED`
- Called when Minecraft has started and it's client about to tick for the first time.
- This occurs while the splash screen is displayed.

### `ClientLifecycleEvents.CLIENT_STOPPING`
- Called when Minecraft's client begins to stop.
- This is caused by quitting while in game, or closing the game window.
- This is called before the integrated server is stopped.

## `ClientTickEvents`

Events related to ticking of a Minecraft client.

### `ClientTickEvents.START_CLIENT_TICK`
- Called at the start of the client tick.

### `ClientTickEvents.END_CLIENT_TICK`
- Called at the end of the client tick.

### `ClientTickEvents.START_WORLD_TICK`
- Called at the start of a client world's tick.

### `ClientTickEvents.END_WORLD_TICK`
- Called at the end of a client world's tick.
- End of world tick may be used to start async computations for the next tick.

## `ClientChunkEvents`

Events related to the lifecycle of chunks on a Minecraft client

### `ClientChunkEvents.CHUNK_LOAD`
- Called when a chunk is loaded into a client world.

### `ClientChunkEvents.CHUNK_UNLOAD`
- Called when a chunk is about to be unloaded from a client world.

## `ClientEntityEvents`

Events related to the lifecycle of entities in a client world

### `ClientEntityEvents.ENTITY_LOAD`
- Called when an Entity is loaded into a client world.
- The entity is present in the client world when this event is called.

### `ClientEntityEvents.ENTITY_UNLOAD`
- Called when an Entity is about to be unloaded from a client world.
- The entity is present in the client world when this event is called.

## `ClientBlockEntityEvents`

Events related to the lifecycle of block entities in a client world

### `ClientBlockEntityEvents.BLOCK_ENTITY_LOAD`
- Called when a BlockEntity is loaded into a client world.
- The block entity is present in the client world when this event is called.

### `ClientBlockEntityEvents.BLOCK_ENTITY_LOAD`
- Called when a BlockEntity is about to be unloaded from a client world.
- The block entity is present in the client world when this event is called.