# Using External Event Listeners

This guide shows how a feature can subscribe to external Forge events.

External listeners are useful when feature logic must react to events outside the OMS lifecycle.

***

### Overview

Features may register external event listeners by overriding `createEventListeners()`.

These listeners are registered on the Forge event bus during addon initialization.

***

### 1. Create a listener class

A listener is a regular Forge event listener:

```kotlin
class HelloWorldEvents(
    private val feature: HelloWorldFeature
) {

    @SubscribeEvent
    fun onPlayerLoggedIn(event: PlayerEvent.PlayerLoggedInEvent) {
        val server = event.entity.server ?: return
        val playerName = event.entity.name.string
        feature.sayHello(server, playerName)
    }
}
```

***

### 2. Attach listeners to the feature

Return listener instances from `createEventListeners()`:

```kotlin
class HelloWorldFeature(
    configProvider: ConfigProvider<CHelloWorldFeature>
) : OmsFeature<CHelloWorldFeature>(configProvider) {

    override fun createEventListeners(): List<Any> {
        return listOf(
            HelloWorldEvents(this)
        )
    }
    
    fun sayHello(server: MinecraftServer, playerName: String) {
        server.playerList.broadcastSystemMessage(
            Component.literal("Hello, $playerName!"),
            false
        )
    }
}
```

OMS will register these listeners on the Forge event bus.

***

### 3. Enabled state behavior

External listeners are registered independently of the feature enabled state.

This means OMS does **not** automatically prevent listener execution when the feature is disabled.

If a listener should only act while the feature is enabled, that check must be implemented explicitly:

```kotlin
class HelloWorldEvents(
    private val feature: HelloWorldFeature
) {

    @SubscribeEvent
    fun onPlayerLoggedIn(event: PlayerEvent.PlayerLoggedInEvent) {
        if (!feature.isEnabled()) return

        println("hello world")
    }
}
```

***

### 4. When to use external listeners

Use external event listeners when feature logic must react to:

* player events
* world events
* Forge or mod integration events

Use OMS lifecycle methods when the logic belongs to OMS startup, ticking, or shutdown flow.

***

### Notes

* External listeners are regular Forge listeners
* They are registered through `createEventListeners()`
* They are not automatically gated by feature enabled state
* Enabled-state checks must be implemented by the feature if needed


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://conboi.gitbook.io/oms-wiki/developer-guide/implementation-guides/using-external-event-listeners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.