Weed API Reference

Coreweed.api.WeedMod

Mod Lifecycle

Every Weed mod starts with a class that implements `WeedMod`. The class name is declared in `manifest.weed` as `entrypoint`.

Methods

`void onInitialize(ModContext context) throws Exception`: required setup hook.
`default void onClientStart(ModContext context) throws Exception`: optional client startup hook.
`default void onServerStart(ModContext context) throws Exception`: optional server lifecycle hook.
`default void onShutdown(ModContext context) throws Exception`: optional shutdown hook.

Typical Use

Store the logger, register event listeners, validate metadata, and initialize lightweight services.

public final class MyMod implements WeedMod {
    private ModLogger logger;

    @Override
    public void onInitialize(ModContext context) {
        this.logger = context.getLogger();
        context.getEventBus().register(this);
        logger.info("MyMod initialized");
    }
}

Coreweed.api.context.ModContext

ModContext

`ModContext` is passed into lifecycle hooks and is the safest way for a mod to talk to Weed.

Method	Returns	Use
`getModId()`	`String`	The stable mod id from `manifest.weed`.
`getEventBus()`	`EventBus`	Register/unregister listeners and post custom events.
`getMetadata()`	`ModMetadataView`	Read manifest metadata at runtime.
`getLogger()`	`ModLogger`	Write Weed log messages.

Hooksweed.api.event

Events And EventBus

Listeners are normal Java objects. Methods annotated with `@SubscribeEvent` receive matching event classes.

context.getEventBus().register(this);

@SubscribeEvent
public void onTick(TickEvent event) {
    logger.debug("Tick " + event.getTick());
}

Event	Side	Payload
`GameInitEvent`	`COMMON`	Posted after mods initialize.
`TickEvent`	`CLIENT`	`getTick()` returns the client tick counter.
`PlayerJoinEvent`	`CLIENT`	`getPlayerName()` returns the detected local player name.
`BlockBreakEvent`	`CLIENT`	`getPlayerName()`, `getBlockId()`.
`ServerStartingEvent`	`SERVER`	Server lifecycle start.
`ServerStoppedEvent`	`SERVER`	Server lifecycle stop.
`ClientStoppingEvent`	`CLIENT`	Client shutdown notification.

All events inherit `getTimestamp()` and `getSide()` from `Event`.

Runtimeweed.api.logging.ModLogger

Logging

Use the logger from `ModContext`. Weed writes `.txt` files under the Minecraft logs folder.

logger.trace("Detailed diagnostic");
logger.debug("Tick debug");
logger.info("Loaded");
logger.warn("Optional feature unavailable");
logger.error("Failed");
logger.error("Failed", throwable);

Log files: `%APPDATA%\.minecraft\logs\weed-*.txt`.
Terminal logging can be toggled from Weed Settings in-game.
Use `debug` for noisy tick messages, `info` for lifecycle, `warn/error` for problems.

Metadataweed.api.metadata

Metadata Views

Metadata views expose parsed `manifest.weed` data without exposing loader internals.

ModMetadataView

`getId()`, `getName()`, `getVersion()`, `getAuthor()`
`getLicense()`, `getPicture()`, `getProjectUrl()`
`getEntrypoint()`, `getMinecraftVersion()`, `getWeedVersion()`
`getDependencies()`, `getLibraries()`
`getRequirements()`, `getDependencySpecs()`, `getLibrarySpecs()`

Spec Views

`RequirementsView`: Minecraft, Weed, Java version requirements.
`DependencySpecView`: dependency id, version range, optional flag.
`LibrarySpecView`: library id, version, type.

Manifestmanifest.weed

Manifest Format

`manifest.weed` lives at the root of the mod jar and tells the loader how to discover and initialize the mod.

{
  "id": "my_mod",
  "name": "My Mod",
  "version": "1.0.0",
  "author": "Your Name",
  "license": "MIT",
  "projectUrl": "https://github.com/you/my_mod",
  "picture": "assets/my_mod/icon.png",
  "minecraftVersion": "26.1.2",
  "weedVersion": "1.0.0 Beta",
  "requirements": {
    "minecraftVersion": "26.1.2",
    "weedVersion": "1.0.0 Beta",
    "javaVersion": "21+"
  },
  "dependencies": [],
  "libraries": [],
  "mixins": [],
  "entrypoint": "com.example.MyMod"
}

Field	Required	Meaning
`id`	Yes	Stable lowercase mod id.
`entrypoint`	Yes	Class implementing `WeedMod`.
`dependencies`	No	Strings or objects with `id`, `version`, `optional`.
`libraries`	No	Libraries loaded from `.minecraft/weed-libs`.
`mixins`	No	Mixin config file names.

Experimentalweed.api.mixin

Mixin Scaffold API

Weed exposes marker annotations for mixin-style classes. Runtime mixin execution is experimental in this branch, so treat this as scaffolding until the loader promotes full mixin support.

@Mixin("net.minecraft.client.Minecraft")
public final class ExampleMixin {
    @Inject(method = "tick", at = @At("RETURN"))
    private void afterTick() {
    }
}

`@Mixin(String value)`: target class name.
`@Inject(method = "...", at = @At("..."))`: target method and injection point.
`@At("HEAD")`, `@At("RETURN")`, `@At("TAIL")`: intended injection point names.

Servicesweed.api.services.PlayerService

PlayerService

PlayerService is a stable abstraction for player/client access. It avoids mods directly depending on obfuscated internals.

Method	Use
`getPlayer()`	Returns the current player object or `null`.
`sendChatMessage(String, boolean)`	Best-effort chat/system message delivery.
`getMinecraftInstance()`	Returns the client instance as an object.

BuildGradle

Build And Package

The generated template expects a local Weed checkout so it can compile against `weed-api`.

.\gradlew.bat --no-daemon buildAll
.\gradlew.bat build packageWeedMod -PweedHome=C:\Users\amesa\Desktop\Weed

Output jar: `build/weed-dist/<mod_id>.jar`.
Install folder: `%APPDATA%\.minecraft\mods\weed`.
Check runtime proof: `%APPDATA%\.minecraft\weed\loader-proof.txt`.

RecipesExamples

Common Recipes

Register Events

@Override
public void onInitialize(ModContext context) {
    context.getEventBus().register(this);
}

React To Blocks

@SubscribeEvent
public void onBlockBreak(BlockBreakEvent event) {
    logger.info(event.getPlayerName()
        + " broke " + event.getBlockId());
}

Searchable modding reference.