# Forge Concept Events

> Forge 事件系统：事件总线（MinecraftForge#EVENT_BUS、FMLJavaModLoadingContext#getModEventBus、typed EventBus<T>）、事件处理程序注册（IEventBus#addListener、addGenericListener、@SubscribeEvent、@Mod.EventBusSubscriber）、事件取消（@Cancelable、Event#setCanceled）、事件结果（@HasResult、Event$Result DENY/DEFAULT/ALLOW）、事件优先级（EventPriority HIGHEST/MONITOR）、子事件继承、模组事件总线（IModBusEvent、FMLCommonSetupEvent、FMLClientSetupEvent、InterModEnqueueEvent）、1.21.11+类型化记录事件（static BUS 字段、CancellableEventBus）、TickEvent.ServerTickEvent、RegisterCommandsEvent、LivingDeathEvent、BuildCreativeModeTabContentsEvent。

- Skill: `zmjjkk123-hub/forge-concept-events` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmjjkk123-hub/forge-concept-events`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmjjkk123-hub/forge-concept-events/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ZMJJKK123-hub (https://skillmd.com/u/zmjjkk123-hub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zmjjkk123-hub/forge-concept-events

---


# Events

Forge uses an event bus that lets mods intercept vanilla and mod behaviors.

> ⚠️ **IMPORTANT (1.21.11):** the old `MinecraftForge.EVENT_BUS`, `FMLJavaModLoadingContext#getModEventBus`, `@SubscribeEvent`, and `@Mod.EventBusSubscriber` patterns below are LEGACY and generally NOT available in this Forge version. Use the **typed event bus** `SomeEvent.BUS.addListener(...)` shown in the "1.21.11+ current event bus" section at the bottom. Do NOT copy the legacy examples.

## Legacy event handler patterns (older Forge, not 1.21.11)

The main bus is `MinecraftForge#EVENT_BUS`; the mod-specific bus is `FMLJavaModLoadingContext#getModEventBus`.

## Creating an event handler (legacy)

Handlers are single-parameter methods returning void, registered with `IEventBus#addListener` (or `#addGenericListener` for `GenericEvent<T>`, specifying the generic class) inside the mod constructor:

```java
modEventBus.addListener(this::modEventHandler);
forgeEventBus.addGenericListener(Entity.class, ExampleMod::forgeEventHandler);
```

### Annotated handlers

- **Instance**: `@SubscribeEvent` on an instance method; register with `MinecraftForge.EVENT_BUS.register(instance)`.
- **Static**: `@SubscribeEvent` on a static method; register with `...register(Class.class)`.
- **Automatic**: `@Mod.EventBusSubscriber(modid, bus, value = Dist.CLIENT)` auto-registers the class to the given bus at mod construction (methods must be static).

## Canceling

Cancelable events are `@Cancelable` (`Event#isCancelable()` true); use `Event#setCanceled(true/false)`. Canceling a non-cancelable event throws `UnsupportedOperationException` — always check first.

## Results

`@HasResult` events use `Event$Result`: `DENY` (stops the event), `DEFAULT` (vanilla behavior), `ALLOW` (forces the action). Set via `#setResult`; semantics differ per event — read the JavaDoc.

## Priority

`@SubscribeEvent(priority = EventPriority.X)`: `HIGHEST` first, descending to `LOWEST`, then `MONITOR` (read-only, last; mutating during MONITOR may throw).

## Sub events

Listening to a parent event class receives all subclasses (e.g. all `PlayerEvent` variants).

## Mod event bus

Used for lifecycle events implementing `IModBusEvent`. Lifecycle events run in parallel — defer cross-mod work to `#enqueueWork` or use `InterModComms`. Common lifecycle events: `FMLCommonSetupEvent`, `FMLClientSetupEvent`/`FMLDedicatedServerSetupEvent`, `InterModEnqueueEvent`, `InterModProcessEvent`. Non-parallel mod-bus events: `RegisterColorHandlersEvent`, `ModelEvent$BakingCompleted`, `TextureStitchEvent`, `RegisterEvent`. Rule of thumb: mod-bus events handle mod initialization.

## 1.21.11+ current event bus (verified from mc_java_sources)

In this Forge build, events are **typed record events with a static `BUS` field** instead of the old global `MinecraftForge.EVENT_BUS` + `@SubscribeEvent` pattern.

Each event class exposes:

```java
public static final EventBus<MyEvent> BUS = EventBus.create(MyEvent.class);
// cancellable events:
public static final CancellableEventBus<MyEvent> BUS = CancellableEventBus.create(MyEvent.class);
```

Subscribe directly:

```java
MyEvent.BUS.addListener((MyEvent event) -> {
    // handle
});
```

Common examples:
- `TickEvent.ServerTickEvent` / nested `Pre`/`Post` use `TickEvent.ServerTickEvent.BUS` or nested `TickEvent.ServerTickEvent.Pre.BUS`.
- `ServerTickEvent.Pre.BUS.addListener(...)`
- `RegisterCommandsEvent.BUS.addListener(...)`
- `LivingDeathEvent.BUS.addListener(...)` (cancellable via `CancellableEventBus`)
- `BuildCreativeModeTabContentsEvent.BUS.addListener(...)`

Prefer reading the exact event class first; the bus field name and type are always visible in `mc_java_sources`.