Forem: w4t3r

How to Develop Minecraft Mods Using Temporal API?

w4t3r — Mon, 02 Mar 2026 14:27:24 +0000

This article is intended for those who have developed Minecraft mods before or are planning to try it out of personal interest. The topic is simplifying development with NeoForge using the Temporal API library.

Introduction

What Is NeoForge?

Before discussing Temporal API, it makes sense to briefly explain what NeoForge is.

If you search Google for “What is NeoForge?”, you’ll find something like this:

NeoForge is a modern open-source API and mod loader for Minecraft: Java Edition, created as a fork of the popular Forge loader.

In simpler terms, NeoForge is one of the most widely used mod loaders (a layer between mods and the game), alongside Fabric, Quilt, and Minecraft Forge.

NeoForge was released relatively recently and is developed by part of the former Forge team. It is actively maintained and updated, and most modern mods are now built with NeoForge. For that reason, I strongly recommend it for new mod development.

One of the Main Problems with NeoForge

One of the main challenges when developing mods with NeoForge is the large amount of repetitive boilerplate code. It often prevents you from focusing on creating something interesting and unique.

As an example, let’s create a basic item and add a simple model in Minecraft 1.21.1 (ignoring project setup and focusing only on the Java side):

@Mod(ExampleMod.MOD_ID)
public class ExampleMod { // 1
    public static final String MOD_ID = "example";

    public ExampleMod(IEventBus modEventBus, ModContainer modContainer) {
        ExampleItems.ITEMS.register(modEventBus); // 5
        NeoForge.EVENT_BUS.register(this); // 10
    }

    @SubscribeEvent
    public static void gatherData(GatherDataEvent event) { // 8
        DataGenerator generator = event.getGenerator();
        PackOutput output = generator.getPackOutput();
        ExistingFileHelper existingFileHelper = event.getExistingFileHelper();

        generator.addProvider(
            event.includeClient(),
            new ExampleItemModelProvider(output, existingFileHelper) // 9
        );
    }
}

public class ExampleItems {  // 2
    public static final DeferredRegister.Items ITEMS = DeferredRegister.createItems(MODID);  // 3

    public static final DeferredItem<Item> EXAMPLE_ITEM = ITEMS.registerSimpleItem("example_item", new Item.Properties()); // 4
}

public class ExampleItemModelProvider extends ItemModelProvider { // 6
    public ExampleItemModelProvider(PackOutput output, ExistingFileHelper existingFileHelper) {
        super(output, "examplemod", existingFileHelper);
    }

    @Override
    protected void registerModels() {
        basicItem(ExampleItems.EXAMPLE_ITEM.get()); // 7
    }
}

What is happening here:

We create the main mod class. Its constructor effectively acts as the main method of the mod.
We create a class to hold our items.
We create a DeferredRegister for items — essentially a container so NeoForge can properly register them in the game.
We create a basic item.
We register the item container with NeoForge.
We create a class responsible for model generation.
We define the basic model.
We subscribe to GatherDataEvent to hook into data generation.
We register our model provider.
We register all events inside ExampleMod.

The code is manageable and clear in small examples. However, once the project grows and includes more complex scenarios, this structure scales significantly and becomes harder to maintain.

Temporal API

What Is Temporal API?

This is where Temporal API comes in — a framework designed to automate many routine tasks in mod development.

Temporal API relies on reflection and annotations. Conceptually, it resembles Spring Framework, but in the modding world.

The best way to understand its value is to see it in action.

How Temporal API Solves This Problem

Let’s rewrite the same example using Temporal API:

@Mod(ExampleMod.MOD_ID)
public class ExampleMod { // 1
    public static final String MOD_ID = "example";

    public ExampleMod(IEventBus modEventBus, ModContainer modContainer) {
        TemporalEngine.run(ExampleMod.class, modEventBus, modContainer); // 2
    }
}

public final class ExampleItems { // 3
    private static final ItemFactory ITEM_FACTORY = InjectionPool.getFromInstance(ItemFactory.class); // 4

    @GenerateBasicItemModel // 6
    public static final DeferredItem<?> EXAMPLE_ITEM = ITEM_FACTORY.create("example_item"); // 5
}

The code becomes significantly shorter while preserving the same functionality:

We create the mod class.
We initialize Temporal API via TemporalEngine.run(...). This acts as the entry point, allowing the framework to collect metadata and required components.
We create an items class.
We obtain an ItemFactory, which wraps DeferredRegister.Items (internally, more precisely, TemporalRegister.Items).
We create a simple item.
We generate the model using the @GenerateBasicItemModel annotation.

And this is just one example. Temporal API includes many utilities and a flexible annotation system that can be extended if needed.

Drawbacks of Temporal API

The main drawback is version support.

The latest version of Temporal API currently targets Minecraft 1.21.1. Porting the entire functionality to newer and older versions requires significant effort and contributor support.

Where to Learn More

Temporal API is an open-source project:

Source code: https://github.com/maksymuimanov/Temporal-API
Wiki: https://github.com/maksymuimanov/Temporal-API/wiki

Conclusion

To wrap up, I’d like to ask a few questions:

Have you developed Minecraft mods before?
If yes, which mod loader and game version did you use?
If not, would you like to try?
Should I write a detailed article explaining what happens under the hood of Temporal API?

Thank you for reading, and have a great day.

Spring Boot Python Executor: Integrating Java and Python

w4t3r — Thu, 14 Aug 2025 09:43:54 +0000

Introduction

If you have an idea or experience with Java + Python integration, I am going to show you how to make a simple connection between these programming languages in the Spring Boot ecosystem.

Also, for additional information about spring-boot-python-executor you can check out the repository of the project: https://github.com/w4t3rcs/spring-boot-python-executor

Project Setup

Add the starter dependency in pom.xml:

<dependency>
    <groupId>io.github.w4t3rcs</groupId>
    <artifactId>spring-boot-python-executor-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Or to your build.gradle:

implementation 'io.github.w4t3rcs:spring-boot-python-executor-starter:1.0.0'

Also, I'd like to suggest using Docker as a sandbox for Python script execution, so add to your docker-compose.yaml this:

services:
  python-grpc-server:
    image: "w4t3rcs/spring-boot-python-executor-python-grpc-server:latest"
    ports:
      - "50051:50051"
    environment:
      PYTHON_SERVER_TOKEN: secret
      PYTHON_ADDITIONAL_IMPORTS: scikit-learn,numpy,pandas,scipy

And your basic application.yaml should look like this:

spring:
  python:
    executor:
      type: grpc
      grpc:
        token: secret

Developing the first Services with Python

In this chapter, I'll show you how to communicate with Python code by coding out first simple classes that use Python.
Our first example is going to be just a simple class that executes Python code without any difficult logic:

SimplePythonService

@Slf4j
@Service
@RequiredArgsConstructor
public class SimplePythonService {
    private static final String SIMPLE_SCRIPT = "simple_script.py";
    private static final String NUMERIC_SCRIPT = "numeric_script.py";
    private static final String DICT_SCRIPT = "dict_script.py";
    private final PythonProcessor pythonProcessor;

    @PythonBefores({
            @PythonBefore(SIMPLE_SCRIPT),
            @PythonBefore(NUMERIC_SCRIPT),
            @PythonBefore(DICT_SCRIPT),
    })
    public void doSomethingWithPythonBefore() {
        log.info("doSomethingWithPythonBefore()");
    }

    public void doSomethingWithPythonInside() {
        log.info("doSomethingWithPythonInside()");
        log.info("1 --> {}", pythonProcessor.process(SIMPLE_SCRIPT, String.class));
        log.info("2 --> {}", pythonProcessor.process(NUMERIC_SCRIPT, Float.class));
        log.info("3 --> {}", pythonProcessor.process(DICT_SCRIPT, DictScriptResponse.class));
    }

    @PythonAfters({
            @PythonAfter(SIMPLE_SCRIPT),
            @PythonAfter(NUMERIC_SCRIPT),
            @PythonAfter(DICT_SCRIPT),
    })
    public void doSomethingWithPythonAfter() {
        log.info("doSomethingWithPythonAfter()");
    }
}

simple_script.py

hello_world = 'Hello World'
print(hello_world)
o4java{hello_world}

numeric_script.py

a = 2.3462
b = 14.151
c = a + b
o4java{c}

dict_script.py

result = {
    "x": "Hello World",
    "y": 12345
}

o4java{result}

In this example, we can see different types of executing Python scripts using PythonBefore or PythonAfter annotations, or PythonProcessor object.

Use PythonBefore if you want to execute a Python script before a Java method and forget about it.
PythonProcessor is used for advanced purposes: getting the result of the Python script execution as a Java object and argument configuration. It is a centralized object for executing Python scripts in the library.
Use PythonAfter if you want to execute a Python script after a Java method.
o4java{…} means that this Python field will be returned as a Java object.

More advanced example with Spelython usage

PriceCalculatorPythonService

@Service
@RequiredArgsConstructor
public class PriceCalculatorPythonService {
    private static final String CALCULATOR_SCRIPT = "price_calculator.py";
    private final PythonProcessor pythonProcessor;

    public double calculatePrice(ProductDto product, CustomerDto customer) {
        int randomMultiplier = new Random().nextInt(10);
        product.setBasePrice(product.getBasePrice() * randomMultiplier);
        Map<String, Object> arguments = Map.of(
                "product", product,
                "customer", customer
        );

        PythonExecutionResponse<Double> response = pythonProcessor.process(CALCULATOR_SCRIPT, Double.class, arguments);
        return response.body();
    }
}

price_calculator.py

base_price = spel{#product.getBasePrice()}
discount = 0

# Apply customer loyalty discount
if spel{#customer.loyaltyYears()} > 2:
    discount += 0.05

# Apply volume discount
if spel{#product.getQuantity()} > 10:
    discount += 0.03

final_price = base_price * (1 - discount)

# Return the calculated price to Java
o4java{final_price}

This example shows how to use Spelython (SpEL + Python) in your Python script. Write SpEL expressions inside spel{…}, and the special SpelythonResolver object will resolve it as a JSON object in your Python script.

Advanced machine learning example

MLPythonService

@Slf4j
@Service
@RequiredArgsConstructor
public class MLPythonService {
    private static final String ML_SCRIPT = "ml_script.py";
    private final PythonProcessor pythonProcessor;

    public double processMLScript(String text) {
        Map<String, Object> arguments = Map.of("text", text);
        PythonExecutionResponse<Double> response = pythonProcessor.process(ML_SCRIPT, Double.class, arguments);
        return response.body();
    }
}

ml_script.py

# Required imports
import numpy as np
from sklearn.feature_extraction.text import CountVectorizer

# Simple sentiment analysis using predefined positive and negative words
positive_words = ['good', 'great', 'excellent', 'amazing', 'wonderful', 'best', 'love']
negative_words = ['bad', 'terrible', 'awful', 'worst', 'hate', 'poor', 'disappointing']

# Get the input text from Java
text = spel{#text}.lower()

# Count positive and negative words
positive_count = sum(1 for word in positive_words if word in text)
negative_count = sum(1 for word in negative_words if word in text)

# Calculate sentiment score (-1 to 1)
total = positive_count + negative_count
if total == 0:
    sentiment = 0
else:
    sentiment = (positive_count - negative_count) / total

# Return the sentiment score to Java
o4java{sentiment}

Conclusion

spring-boot-python-executor enables safe and modular Python integration into Spring Boot applications. With AOP, REST, and gRPC support, the library is production-ready and easily extensible for custom use cases.