Quick start - Essential Mod

Overview

Essential provides a powerful API for Minecraft mod developers, offering features like command registration, notifications, GUI components, and utilities. This guide will help you integrate Essential’s API into your mod.

For players: If you’re looking to install Essential Mod as a player, see the Installation guide instead.

Prerequisites

Before you begin, ensure you have:

Java development environment

JDK 8 or higher (JDK 17+ for Minecraft 1.18+)

Minecraft mod project

An existing Forge or Fabric mod project set up

Installation

Add Essential as a dependency

Add Essential to your build.gradle or build.gradle.kts file:

Gradle (Kotlin DSL)
Gradle (Groovy)

build.gradle.kts

repositories {
    maven("https://repo.essential.gg/repository/maven-public")
}

dependencies {
    // Use 'compileOnly' for runtime dependency (Essential required)
    compileOnly("gg.essential:essential-1.8.9-forge:+")
    
    // Or use 'implementation' to embed Essential
    // implementation("gg.essential:essential-1.8.9-forge:+")
}

build.gradle

repositories {
    maven {
        url "https://repo.essential.gg/repository/maven-public"
    }
}

dependencies {
    compileOnly "gg.essential:essential-1.8.9-forge:+"
}

Replace essential-1.8.9-forge with the appropriate artifact for your target Minecraft version and mod loader (e.g., essential-1.20.1-fabric).

Sync your project

Run ./gradlew build or refresh your Gradle project in your IDE to download the Essential dependency

Verify the setup

Ensure your IDE recognizes Essential classes by trying to import:

import gg.essential.api.EssentialAPI;

Your first Essential integration

Let’s create a simple command and notification using Essential’s API.

Creating a command

Essential’s Command API automatically handles argument parsing and type conversion:

Kotlin
Java

MyCommand.kt

import gg.essential.api.commands.Command
import gg.essential.api.commands.DefaultHandler
import gg.essential.api.EssentialAPI

object MyCommand : Command("mycommand") {
    
    @DefaultHandler
    fun handle() {
        // Send a notification when command is executed
        EssentialAPI.getNotifications().push(
            "My Mod",
            "Command executed successfully!"
        )
    }
}

MyCommand.java

import gg.essential.api.commands.Command;
import gg.essential.api.commands.DefaultHandler;
import gg.essential.api.EssentialAPI;

public class MyCommand extends Command {
    
    public MyCommand() {
        super("mycommand");
    }
    
    @DefaultHandler
    public void handle() {
        // Send a notification when command is executed
        EssentialAPI.getNotifications().push(
            "My Mod",
            "Command executed successfully!"
        );
    }
}

Registering the command

Kotlin
Java

ModInitializer.kt

import gg.essential.api.EssentialAPI
import net.minecraftforge.fml.common.Mod
import net.minecraftforge.fml.common.event.FMLInitializationEvent

@Mod(modid = "mymod")
class MyMod {
    
    @Mod.EventHandler
    fun init(event: FMLInitializationEvent) {
        // Register the command
        MyCommand.register()
        
        // Or register directly:
        // EssentialAPI.getCommandRegistry().registerCommand(MyCommand)
    }
}

MyMod.java

import gg.essential.api.EssentialAPI;
import net.minecraftforge.fml.common.Mod;
import net.minecraftforge.fml.common.event.FMLInitializationEvent;

@Mod(modId = "mymod")
public class MyMod {
    
    @Mod.EventHandler
    public void init(FMLInitializationEvent event) {
        // Register the command
        new MyCommand().register();
    }
}

Testing your integration

Build your mod

Run ./gradlew build to compile your mod

Launch Minecraft

Start Minecraft with your mod and Essential installed

Test the command

In-game, type /mycommand and press Enter. You should see a notification appear!

Core API components

Essential’s API is accessed through the EssentialAPI class, which provides:

EssentialAPI class

The central access point for all Essential APIs:

Essential API

import gg.essential.api.EssentialAPI;

// Get the API instance
EssentialAPI api = EssentialAPI.getInstance();

// Or use static convenience methods:
EssentialAPI.getNotifications();
EssentialAPI.getCommandRegistry();
EssentialAPI.getGuiUtil();

Available APIs

Commands

Create commands with automatic argument parsing

Notifications

Display beautiful in-game notifications

GUI utilities

Open screens and access GUI components

Minecraft utils

Minecraft-specific utility functions

Mojang API

Interact with Mojang’s player API

Web utilities

HTTP utilities and trusted hosts

Dependency injection

Modern DI system for clean architecture

Configuration

Access Essential’s internal settings

Common use cases

Sending notifications

Display notifications to users without cluttering the chat:

Basic notification
With duration
With click action
Advanced configuration

EssentialAPI.getNotifications().push(
    "Title",
    "Message content"
)

EssentialAPI.getNotifications().push(
    "Title",
    "This notification stays for 6 seconds",
    duration = 6f
)

EssentialAPI.getNotifications().push(
    title = "Click me!",
    message = "This notification does something when clicked",
    action = {
        println("Notification clicked!")
        // Open a GUI, execute a command, etc.
    }
)

EssentialAPI.getNotifications().push(
    title = "Advanced Notification",
    message = "Fully customized",
    duration = 5f,
    configure = {
        // Set notification type (changes color)
        type = NotificationType.WARNING
        
        // Trim long messages
        trimMessage = true
        
        // Custom action
        onAction = {
            println("Clicked!")
        }
        
        // Custom close callback
        onClose = {
            println("Notification closed")
        }
    }
)

Creating commands with arguments

Essential automatically parses and converts command arguments based on parameter types:

With required argument
With optional argument
With subcommands

object TeleportCommand : Command("teleport") {
    
    @DefaultHandler
    fun handle(distance: Int) {
        // User must provide an integer
        // Usage: /teleport <distance>
        EssentialAPI.getNotifications().push(
            "Teleport",
            "Teleporting $distance blocks!"
        )
    }
}

object GreetCommand : Command("greet") {
    
    @DefaultHandler
    fun handle(name: String?) {
        // Name is optional (nullable type)
        // Usage: /greet [name]
        val message = if (name != null) {
            "Hello, $name!"
        } else {
            "Hello!"
        }
        
        EssentialAPI.getNotifications().push("Greet", message)
    }
}

object ConfigCommand : Command("config") {
    
    @DefaultHandler
    fun handleDefault() {
        EssentialAPI.getNotifications().push(
            "Config",
            "Use /config <reload|save>"
        )
    }
    
    @SubCommand("reload")
    fun handleReload() {
        // /config reload
        EssentialAPI.getNotifications().push(
            "Config",
            "Configuration reloaded!"
        )
    }
    
    @SubCommand("save")
    fun handleSave() {
        // /config save
        EssentialAPI.getNotifications().push(
            "Config",
            "Configuration saved!"
        )
    }
}

The Command API automatically generates usage messages when arguments are invalid. For example, if the user types /teleport abc, they’ll see: Usage: /teleport <distance>

Opening GUI screens

Use GuiUtil to safely open Minecraft screens:

import gg.essential.api.EssentialAPI
import net.minecraft.client.gui.GuiScreen

// Queue a screen to open
EssentialAPI.getGuiUtil().openScreen(myCustomScreen)

// Get the currently open screen
val currentScreen = EssentialAPI.getGuiUtil().openedScreen()

Using Mojang API utilities

Essential provides utilities for interacting with Mojang’s API:

import gg.essential.api.EssentialAPI
import java.util.UUID

val mojangAPI = EssentialAPI.getMojangAPI()

// Get UUID from username
val uuid: UUID? = mojangAPI.getUUIDFromUsername("Notch")

// Get username from UUID
val username: String? = mojangAPI.getUsernameFromUUID(uuid)

// Get game profile
val profile = mojangAPI.getProfile(uuid)

Best practices

Use compileOnly for optional Essential dependency

If you want your mod to work without Essential installed, use compileOnly in your dependencies and check if Essential is loaded before using the API:

fun isEssentialLoaded(): Boolean {
    return try {
        Class.forName("gg.essential.api.EssentialAPI")
        true
    } catch (e: ClassNotFoundException) {
        false
    }
}

if (isEssentialLoaded()) {
    MyCommand.register()
}

Leverage dependency injection

For larger projects, use Essential’s DI system for cleaner architecture:

import gg.essential.api.EssentialAPI
import gg.essential.api.gui.Notifications

class MyService(private val notifications: Notifications) {
    fun doSomething() {
        notifications.push("Title", "Message")
    }
}

// Get service via DI
val di = EssentialAPI.getDI()
val notifications = di.get<Notifications>()
val service = MyService(notifications)

Handle command errors gracefully

Always validate command input and provide helpful feedback:

@DefaultHandler
fun handle(amount: Int) {
    if (amount <= 0) {
        EssentialAPI.getNotifications().push(
            title = "Error",
            message = "Amount must be positive!",
            configure = { type = NotificationType.ERROR }
        )
        return
    }
    
    // Process valid amount...
}

Use notification types appropriately

Choose the right notification type for better user experience:

GENERAL: Default, neutral notifications
INFO: Informational messages
WARNING: Warnings that need attention
ERROR: Error messages
DISCORD: Discord-related notifications

API reference

For detailed documentation on all available APIs, see:

Essential API

Core API documentation and reference

Commands API

Complete command creation guide

GUI API

GUI components and Elementa integration

Utilities

Utility functions and helpers

Examples

Here are some complete examples to help you get started:

Complete command with multiple argument types

CompleteCommand.kt

import gg.essential.api.commands.Command
import gg.essential.api.commands.DefaultHandler
import gg.essential.api.commands.SubCommand
import gg.essential.api.commands.DisplayName
import gg.essential.api.EssentialAPI
import gg.essential.api.gui.NotificationType

object ItemCommand : Command("item", autoHelpSubcommand = true) {
    
    @DefaultHandler
    fun handleDefault() {
        EssentialAPI.getNotifications().push(
            "Item Command",
            "Use /item give or /item list"
        )
    }
    
    @SubCommand("give")
    fun handleGive(
        @DisplayName("itemName") item: String,
        @DisplayName("count") amount: Int?
    ) {
        val count = amount ?: 1
        
        if (count <= 0 || count > 64) {
            EssentialAPI.getNotifications().push(
                title = "Error",
                message = "Amount must be between 1 and 64",
                configure = { type = NotificationType.ERROR }
            )
            return
        }
        
        // Give item logic here...
        
        EssentialAPI.getNotifications().push(
            title = "Item Given",
            message = "Gave $count x $item",
            configure = { type = NotificationType.INFO }
        )
    }
    
    @SubCommand("list")
    fun handleList() {
        // List items logic...
        EssentialAPI.getNotifications().push(
            "Items",
            "Check chat for item list"
        )
    }
}

GUI integration example

CustomGUI.kt

import gg.essential.api.EssentialAPI
import gg.essential.api.gui.EssentialGUI
import gg.essential.elementa.ElementaVersion
import gg.essential.elementa.components.UIText
import gg.essential.elementa.dsl.*

class MyCustomGUI : EssentialGUI(
    ElementaVersion.V2,
    "My Custom GUI",
    discordActivityDescription = "Managing settings"
) {
    
    init {
        // Add content to the GUI
        val text = UIText("Hello from Essential GUI!").constrain {
            x = CenterConstraint()
            y = CenterConstraint()
        } childOf content
    }
}

// Open the GUI
fun openMyGUI() {
    EssentialAPI.getGuiUtil().openScreen(MyCustomGUI())
}

Next steps

Build from source

Learn how to build Essential from source code

Core concepts

Understand Essential’s architecture

Join Discord

Get help and connect with other developers

View source

Explore the Essential source code

Get Started

Building

Core Concepts

​Overview

​Prerequisites

Java development environment

Minecraft mod project

​Installation

​Your first Essential integration

​Creating a command

​Registering the command

​Testing your integration

​Core API components

​EssentialAPI class

​Available APIs

Commands

Notifications

GUI utilities

Minecraft utils

Mojang API

Web utilities

Dependency injection

Configuration

​Common use cases

​Sending notifications

​Creating commands with arguments

​Opening GUI screens

​Using Mojang API utilities

​Best practices

​API reference

Essential API

Commands API

GUI API

Utilities

​Examples

​Next steps

Build from source

Core concepts

Join Discord

View source

Build docs developers (and LLMs) love

Overview

Prerequisites

Installation

Your first Essential integration

Creating a command

Registering the command

Testing your integration

Core API components

EssentialAPI class

Available APIs

Common use cases

Sending notifications

Creating commands with arguments

Opening GUI screens

Using Mojang API utilities

Best practices

API reference

Examples

Next steps