iridium-script

Original：🇨🇳 Chinese

Translated

Write JavaScript scripts for Iridium (a Minecraft 1.20.1/1.21.10 Forge client), covering module/HUD/command registration, event listening, Nashorn-style Java interop, and the IridiumMCP debugging toolchain. Use this skill in any of the following scenarios: the user mentions Iridium or client-side scripting; requests registration of modules, HUD elements, or chat commands; involves .js files under %APPDATA%\scripts; the current working directory is in %APPDATA%\scripts; or the user only describes functional requirements (e.g., "write me an auto sprint feature") without mentioning Iridium, but the context indicates it is for this client.

9installs

Sourcecubk1/iridiumskill

Added on2026-09-26

NPX Install

npx skill4agent add cubk1/iridiumskill iridium-script

SKILL.md Content (Chinese)

View Translation Comparison →

Introduction

Iridium is a Minecraft 1.20.1/1.21.10 client running on Forge, with a JavaScript-based script executor.

Scripts can register modules, settings, HUD elements, and chat commands, listen to game events, and directly call Java APIs.

Before You Start

Make sure you have the following resources:

```
types.d.ts
```
: General definitions for all script APIs and Minecraft APIs, most of which are Minecraft APIs. You need to at least read the Client API chapter, and the Minecraft Types chapter is for quick reference.
```
IridiumMCP
```
: Provides tools to assist you with development.

You must first consult the user (if not provided) which version the script is intended for, download the corresponding

types.d.ts

according to the version, and familiarize yourself with the corresponding Minecraft API.

If the user requires compatibility with both versions, use

client.getMinecraftVersion()

to determine the version and execute the corresponding logic.

All API definitions are in

types.d.ts

— be sure to read it.

File locations:

Purpose	Path
Scripts	`%APPDATA%\scripts\*.js`
Local libraries	`%APPDATA%\scripts\.libs\*.js`

MCP

MCP provides an interface for Harness to interact with the client, which is very helpful for development.

Even if the client is not open, MCP can still connect because MCP and the client are separate. You can use the

ping

tool to ensure the client is online.

If you cannot use IridiumMCP, follow the steps below to install it or troubleshoot:

MCP Not Installed

Download

https://iridium.styles.wtf/assets/IridiumMCP.exe

to the current directory. Do not place it in a temporary directory, otherwise it may not be found next time.

Configure it in any way, add it to your harness MCP configuration, and complete the configuration on your own as much as possible. Only ask the user for operations if you really cannot complete them independently, such as permission issues.

After installation, inform the user with the following message (translate according to the language of the user's prompt):

┌─ IridiumMCP Server Setup Complete ────────────────────┐
│  ✓ Config  <path>                                    │
│  ✓ MCPs    <path>                                    │
│                                                      │
│  ⚡ Restart your agent to load the MCP servers       │
└──────────────────────────────────────────────────────┘

StreamHTTP

MCP will run at

http://127.0.0.1:6767/mcp

If port

is occupied, use:

IridiumMCP.exe -http 127.0.0.1:6768

stdio

IridiumMCP.exe -stdio

MCP Not Working

First check if the HTTP URL is written incorrectly. The correct URL should include
```
/mcp
```
; if it does not include
```
/mcp
```
, it is wrong.
Focus on checking the proxy settings in tools like Claude Code, Open Code, etc. — whether you forgot to configure NO_PROXY to allow
```
127.0.0.1
```
.

Libraries

First read

reference/library.md

which contains a directory of pre-built libraries. If you think the user's request may require a library, use the

get_library

tool to obtain the source code to confirm usage, then import it with

client.import

. Example:

var clip = client.import("cubk/clipboard");
log("import ok, keys: " + Object.keys(clip).join(", "));
log("write: " + clip.write("MARKER-8964"));

Development Workflow

Understand the user's request: whether to create a new script or modify an existing one.
Try to connect to MCP and use the
```
ping
```
tool to ensure the client is online. If the client is offline, inform the user that the client needs to be started to use MCP. Of course, you can still write scripts without MCP, but debugging will be very difficult.
Read
```
types.d.ts
```
to understand the client API.
Locate the file directory, find the script the user wants to modify or create a new script. You can use the MCP
```
list_scripts
```
tool for quick viewing.
Write a test version of the script to ensure all logic works. During this process, you can debug using tools like
```
eval
```
,
```
get_errors
```
,
```
grep_logs
```
, and
```
get_logs
```
. Logs output via the
```
log()
```
interface can be retrieved via
```
grep_logs
```
and
```
get_logs
```
; prioritize using
```
grep_logs
```
to save context.
If the user is developing a visual feature, use
```
screenshot
```
to get an in-game screenshot to confirm the effect.
After modifying the script, use
```
reload_script
```
to reload it. The client does not auto-reload.
Use
```
get_library
```
to view the source code of a library.
After ensuring all features work, ask the user to confirm that the requirements are met.
If the user raises further modification suggestions, implement them.
If the user confirms that the requirements are met, ask the user if they want to clean up debugging code, etc. Clean up debugging code and other unnecessary content for the user's convenience.

Script Structure

A script is a single

.js

file that executes entirely once when loaded: first register modules and settings, then attach behaviors with

events.on(...)

client.registerModule("Auto Sprint", -1, "Movement", false);
client.registerSlider("Auto Sprint", "Delay", 5, 1, 20, 1);

events.on("tick", function () {
    if (!client.isEnabled("Auto Sprint")) return;
    // ...
});

Scripts are automatically preprocessed and wrapped in an IIFE for execution (

(function(){ ...your code... })()

), so top-level

var

and

function

declarations are private and will not overwrite each other across different scripts. To share code across scripts, use libraries.

Use one of these six categories:

Combat

Movement

Render

World

Player

Inventory

A single script can register multiple modules, commands, and HUD elements.

Java Interop

The engine provides Nashorn-style Java interoperation.

mc

and everything obtained from it (players, entities, items, worlds) are Java objects — you can directly call their methods:

mc.player.getX();
mc.player.getMainHandItem().getCount();
mc.level.getBlockState(pos).getBlock();

Getting Classes

Use

Java.type()

to get a class, which can be used for

new

instances, reading static fields, and calling static methods:

var BlockPos = Java.type("net.minecraft.core.BlockPos");
var Items = Java.type("net.minecraft.world.item.Items");
var Component = Java.type("net.minecraft.network.chat.Component");

var pos = new BlockPos(100, 64, 200);          // Constructor
var stick = Items.STICK;                        // Static field
var text = Component.literal("hello");          // Static method

Write fully qualified names with dots (

net.minecraft.core.BlockPos

), not slashes.

For array types, write

"int[]"

"java.lang.String[]"

Inner classes (nested classes, enums) are separated by
$
, not dots. The engine directly passes the name to

Class.forName

and does not automatically convert dots to

. Incorrect names will throw

Java class not found

Java.type("com.mojang.blaze3d.vertex.VertexFormat$Mode");        // Correct
Java.type("net.minecraft.world.entity.Entity$RemovalReason");     // Correct
Java.type("com.mojang.blaze3d.vertex.VertexFormat.Mode");         // Wrong, class not found

Enum constants are accessed as static fields:

var Mode = Java.type("com.mojang.blaze3d.vertex.VertexFormat$Mode");
var quads = Mode.QUADS;

The result of

Java.type

is cached, so repeated calls have no extra overhead. You can safely write it in event callbacks, though placing it at the top level of the script is clearer.

Name Mapping

The engine performs remapping automatically when looking up fields and methods, so use Mojang names (

getX

getMainHandItem

If you are sure you have written the correct Mojang name but still have issues, you can use

eval

to probe first, as the mapper does not map 100% of all fields and methods.

The same applies to class names — just write

net.minecraft.core.BlockPos

Overloading and Type Conversion

Parameters are automatically converted according to Java method signatures: JS numbers convert to

int

float

double

, strings convert to

String

, and JS functions can be passed to functional interfaces (single-method interfaces). When there are overloads, the engine selects a matching one based on the number and type of parameters.

If you are unsure whether a method exists or what it returns, test it on the spot with

eval

mc.player.getMainHandItem().getItem().toString()

Arrays

Java arrays are more user-friendly than collections: they have

.length

and can be accessed by index:

var arr = someJavaMethodReturningArray();
arr.length;
arr[0];

But collections are not arrays — see the Tips section below.

Type Checking

var Player = Java.type("net.minecraft.world.entity.player.Player");
if (Java.isType(entity, Player)) { ... }

instanceof

does not work with Java types (it follows the JS prototype chain). Always use

Java.isType

to check Java types.

Java.isJavaObject(x)

checks whether a value is a Java object.

Tips

Some specifications and notes for the script system.

Java Collections Are Not JS Arrays

mc.level.players()

returns a

java.util.List

, which does not have
.length
. When you write

for (var i = 0; i < list.length; i++)

, the condition becomes

0 < undefined

, so the loop never executes, and no error is thrown — this is one of the hardest types of bugs to find.

var players = mc.level.players();
players.length                   // undefined
players.size(); players.get(0)   // Works
Java.from(players).length        // Works, converts to a real JS array

Java.from()

accepts Java arrays and any

Iterable

(List/Set/Collection). To iterate over a

Map

, you first need to call

.entrySet()

.values()

Setting IDs Are Always

"ModuleName:SettingName"

Registration takes two parameters, but reading uses a concatenated string:

client.registerSlider("My Module", "Speed", 1, 0, 5, 0.1);
client.getNumber("My Module:Speed");

HUD settings do not belong to the module itself. You must use

client.hudProperty(hud, label)

to generate the ID — do not concatenate it manually.

HUD Must Write Back

ctx.width

ctx.height

Without these, the element has no hitbox, and users cannot drag or click it in HUD edit mode, even though it looks normal on screen.

client.registerHud("Coords", { anchor: "Left Bottom", x: 4, y: 4 }, function (graphics, ctx) {
    var text = "X " + Math.round(mc.player.getX());
    render.drawString(graphics, text, ctx.x, ctx.y, 0xFFFFFFFF);
    ctx.width = render.getStringWidth(text);   // Required
    ctx.height = render.fontHeight();          // Required
});

3D Tags Should Take an Entity, Not Coordinates

When passing an entity, the engine uses

partialTicks

for interpolation, so the tag follows the entity smoothly when it moves. If you pass coordinates obtained from

getX()

yourself, you get the position at the end of the tick, causing the tag to jitter and not align with the entity's rendered position.

render.drawTag("§e" + p.getName().getString(), p, 0.4, { autoScale: true });   // Recommended
render.drawTag("§aSpawn", 100.5, 65, 200.5, {});                               // Only use for fixed positions

The third parameter is the extra offset above the entity's height; the engine already accounts for the hitbox height.

Colors Are ARGB, Alpha First

0xFF55FF55

is opaque green. If you omit the alpha channel and write

0x55FF55

, the alpha value is 0, making it completely transparent — it looks like "nothing was drawn".

Text color codes use

§

(U+00A7), e.g.,

"§cRed"

"§lBold"

Module Enable/Disable Must Be Checked Manually

Registering a module does not make events only fire when it is enabled. Every callback must check this on its own:

events.on("tick", function () {
    if (!client.isEnabled("My Module")) return;
    // ...
});

You can also listen to

enable

disable

events for initialization and cleanup.

Of course, you can write auxiliary features for other modules — logic that only executes when another existing module is enabled.

Events

There are three types, with different usage patterns:

Notification type — only informs you that something happened:

events.on("tick", function () { ... });
events.on("render3d", function (partialTicks) { ... });

Cancelable type —

return true

to prevent the default behavior:

events.on("chat", function (text) {
    return text === "secret";     // true = do not send
});

Modifiable type — receives an object, modify its fields:

events.on("movementInput", function (e) { e.jump = true; });
events.on("fov", function (e) { e.factor = 1.5; });

In modifiable events,

return

has no effect — you must modify the fields. Which category each event belongs to and what its fields are called are noted in each

on(...)

overload in

types.d.ts

There are two rendering events:

render2d

for drawing screen UI (provides

graphics

), and

render3d

for drawing world content (

render.drawTag

render.drawBox

can only be called here).

3.2.0 Update Notes

Client version 3.2.0 brings major updates to the script system (it is a mandatory update, no version check is needed — all the following features can be used directly). If you have memories of previous versions, you need to understand the new features below:

Java Features

Feature	Example
Method Reference	`list.stream().map(java.lang.String::length)` , `java.lang.Integer::parseInt` , `'text'::length` , `X::new`
Direct class access via package name	`var File = java.io.File;` `net.minecraft.core.BlockPos`
`Packages` root	`new Packages.java.util.HashMap()`
`JavaImporter` + `with`	`with (new JavaImporter(java.io, java.util)) { new File('a'); new HashMap(); }`
Automatic function-to-interface conversion (SAM)	`new java.lang.Thread(function () { ... }).start()`
Anonymous classes	`new java.lang.Runnable() { run: function () { ... } }`
Class inheritance / implementing multiple interfaces	`Java.extend(java.util.ArrayList, { add: function (x) { return Java.super(this).add(x); } })`
`Java.super`	Call the parent class implementation in an overridden method
`Java.to`	`Java.to([1, 2], 'int[]')`
`X.class`	`java.util.ArrayList.class` (Nashorn compatible)
Iterating Java collections	`for (var p of mc.level.players())` , `[...list]` , `var [a, b] = list` ; Maps yield `[key, value]` , also supports Iterator, Stream, Java arrays
Object equality	`mc.player === mc.player` is true; `===` , `Object.is` , and Map/Set keys all compare based on the underlying Java object
`instanceof` keyword	`p instanceof net.minecraft.world.entity.player.Player` ; also supported for classes generated by `Java.extend`
Passing JS arrays to Java	Automatically converted to Java arrays or `List` ; varargs methods can directly accept arrays: `LongStream.of([1, 2, 3])`
Static fields	Read and write in real time, with type conversion based on field type (previously, reads returned snapshots); final fields are read-only

Client API

All old flat interfaces like

client.getBool(...)

are fully retained, and a new set of object-oriented interfaces has been added:

var aura = moduleManager.getModule('Legit Aura');
aura.enabled = true;                         // Consistent with clicking the GUI (triggers notification)
aura.key = 'R';                              // Supports key names
for (var p of aura.getProperties()) {
    log(p.label, p.type, p.value, p.visible);
}
var mode = aura.getProperty('Mode');
mode.cycle();                                // Single -> Switch
mode.children;                               // Only returns child settings visible under current conditions

moduleManager
:

getModule

getModules(category?)

getEnabledModules

getCategories

getCategoryParents

getProperty(id)

hasModule

Module

Basic info:

name

category

categoryParent

categoryLeaf

description

(writable),

icon

inline

script

keyName

Read/write:
```
enabled
```
,
```
key
```
.

Methods:

toggle

enable

disable

setEnabled(v, silent)

getProperties

getAllProperties

getProperty

getBinds

bind(key, options)

Property
- Read/write:
```
value
```
  , which is validated on write: sliders are limited to range and aligned to step size, mode rejects unknown options, multi discards unknown options.
- Read-only info:
```
type
```
  ,
```
defaultValue
```
  ,
```
min
```
  /
```
max
```
  /
```
inc
```
  ,
```
options
```
  ,
```
optionIcons
```
  ,
```
hint
```
  ,
```
condition
```
  .
- UI-related:
```
visible
```
  (includes parent conditions),
```
hidden
```
  (writable),
```
label
```
  (writable).
- Hierarchy:
```
parent
```
  ,
```
children
```
  ,
```
swatch
```
  .
- Methods:
```
reset
```
  ,
```
toggle
```
  ,
```
cycle
```
  ,
```
select
```
  /
```
deselect
```
  /
```
isSelected
```
  /
```
toggleOption
```
  .
Wrapper objects are cached (the same module/property always returns the same object), and each read gets the real-time state; accessing an object after it has been unregistered will throw a
```
ReferenceError
```
.

var bind = keybindManager.add(aura, 'KP_8', { mode: 'hold' });
bind.key = 'MOUSE4';
bind.remove();

var m = macroManager.add('Message', { name: 'gg', message: '/hub', key: 'H' });
m.run();

keybindManager

getBinds

getBind

find(target)

add

remove

keyCode

keyName

Bind

target

key

mode

value

visible

isModule

module

property

update()

remove()

macroManager

getMacros

getMacro

add('Message' | 'Item', options)

remove

run

Macro

name

key

message

item

match

rotation

switchMode

yawOffset

pitch

update()

run()

remove()

Event	Parameters	Description
`click`	`(button, action, x, y)`	All mouse button presses/releases, return true to cancel
`scroll`	`(delta, x, y)`	Mouse wheel, return true to cancel (e.g., prevent hotbar switching)
`charTyped`	`(char, codepoint)`	Character input (supports Chinese), return true to cancel
`keyInput`	`(key, action)`	All keyboard events (press 1 / release 0 / repeat 2), triggered in any interface, return true to consume the key

The semantics of the original

key

event remain unchanged (only triggered in-game or in container interfaces, only reports presses).

input

provides:

getMouseX/Y

(same GUI coordinate system as

render2d

getScreenWidth/Height

getGuiScale

isMouseDown

isKeyDown

isMouseGrabbed

setMouseGrabbed

(release or grab mouse),

isScreenOpen

keyCode

keyName

Key names: Anywhere a key is required, it accepts

'R'

'F5'

'LSHIFT'

'KP_9'

'NUMPAD9'

'M4'

'MOUSE4'

'key.keyboard.r'

, or directly passing a key code.

keyName

and

keyCode

can be converted to each other.

render.bloom(graphics, x, y, w, h, radius, color, spread, intensity)

: Rounded rectangle glow effect.

client.getUsername()

client.getVersion()

client.getMinecraftVersion()

Forge Event Hook

var id = events.onForge('LivingDeathEvent', function (e) { log(e.getEntity()); });
events.onForge('ClientChatReceivedEvent', function (e) { return /spam/.test(e.getMessage().getString()); }); // true = cancel
events.offForge(id);

Event types can be passed as Java classes or by name: simple name (
```
LivingDeathEvent
```
), nested name (
```
RenderGuiOverlayEvent.Pre
```
), or full name. Subclasses will also be matched.
Options:
```
phase: 'pre' | 'post'
```
(before or after Forge's own listeners),
```
receiveCanceled
```
,
```
anyThread
```
(default only receives events from the main thread).

Event Loop

setTimeout

setInterval

clearTimeout

clearInterval

queueMicrotask

, Promise/async.

Fetch (WHATWG)

const res = await fetch('https://example.com/api', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ a: 1 }),
});
const data = await res.json();

Redirects support three modes:
```
follow
```
,
```
manual
```
,
```
error
```
, with a maximum of 20 hops.

Supports

AbortController

AbortSignal

, including

AbortSignal.timeout

any

Streaming read: Resolves as soon as response headers arrive, and the response body arrives in chunks via
```
res.body
```
(
```
ReadableStream
```
).
Automatically sends
```
accept-encoding: gzip, deflate
```
and automatically decompresses responses.

Supporting objects:

Request

Response

(including

json

redirect

error

clone

Headers

URL

URLSearchParams

Blob

TextEncoder

TextDecoder

DOMException

Deno

const server = Deno.serve({ port: 8080 }, async (req) => {
  const url = new URL(req.url);
  switch (url.pathname) {
    case '/hello': return new Response('hi');
    case '/echo':  return Response.json(await req.json());
    case '/sse':   return new Response(new ReadableStream({
      async pull(c) { await new Promise(r => setTimeout(r, 1000)); c.enqueue('data: tick\n\n'); },
      cancel() { log('client left'); }
    }), { headers: { 'content-type': 'text/event-stream' } });
    default: return new Response('not found', { status: 404 });
  }
});

Introduction

Iridium is a Minecraft 1.20.1/1.21.10 client running on Forge, with a JavaScript-based script executor.

Scripts can register modules, settings, HUD elements, and chat commands, listen to game events, and directly call Java APIs.

Before You Start

Make sure you have the following resources:

```
types.d.ts
```
: General definitions for all script APIs and Minecraft APIs, most of which are Minecraft APIs. You need to at least read the Client API chapter, and the Minecraft Types chapter is for quick reference.
```
IridiumMCP
```
: Provides tools to assist you with development.

You must first consult the user (if not provided) which version the script is intended for, download the corresponding

types.d.ts

according to the version, and familiarize yourself with the corresponding Minecraft API.

If the user requires compatibility with both versions, use

client.getMinecraftVersion()

to determine the version and execute the corresponding logic.

All API definitions are in

types.d.ts

— be sure to read it.

File locations:

Purpose	Path
Scripts	`%APPDATA%\scripts\*.js`
Local libraries	`%APPDATA%\scripts\.libs\*.js`

MCP

MCP provides an interface for Harness to interact with the client, which is very helpful for development.

Even if the client is not open, MCP can still connect because MCP and the client are separate. You can use the

ping

tool to ensure the client is online.

If you cannot use IridiumMCP, follow the steps below to install it or troubleshoot:

MCP Not Installed

Download

https://iridium.styles.wtf/assets/IridiumMCP.exe

to the current directory. Do not place it in a temporary directory, otherwise it may not be found next time.

After installation, inform the user with the following message (translate according to the language of the user's prompt):

┌─ IridiumMCP Server Setup Complete ────────────────────┐
│  ✓ Config  <path>                                    │
│  ✓ MCPs    <path>                                    │
│                                                      │
│  ⚡ Restart your agent to load the MCP servers       │
└──────────────────────────────────────────────────────┘

StreamHTTP

MCP will run at

http://127.0.0.1:6767/mcp

If port

is occupied, use:

IridiumMCP.exe -http 127.0.0.1:6768

stdio

IridiumMCP.exe -stdio

MCP Not Working

First check if the HTTP URL is written incorrectly. The correct URL should include
```
/mcp
```
; if it does not include
```
/mcp
```
, it is wrong.
Focus on checking the proxy settings in tools like Claude Code, Open Code, etc. — whether you forgot to configure NO_PROXY to allow
```
127.0.0.1
```
.

Libraries

First read

reference/library.md

which contains a directory of pre-built libraries. If you think the user's request may require a library, use the

get_library

tool to obtain the source code to confirm usage, then import it with

client.import

. Example:

var clip = client.import("cubk/clipboard");
log("import ok, keys: " + Object.keys(clip).join(", "));
log("write: " + clip.write("MARKER-8964"));

Development Workflow

Understand the user's request: whether to create a new script or modify an existing one.
Try to connect to MCP and use the
```
ping
```
tool to ensure the client is online. If the client is offline, inform the user that the client needs to be started to use MCP. Of course, you can still write scripts without MCP, but debugging will be very difficult.
Read
```
types.d.ts
```
to understand the client API.
Locate the file directory, find the script the user wants to modify or create a new script. You can use the MCP
```
list_scripts
```
tool for quick viewing.
Write a test version of the script to ensure all logic works. During this process, you can debug using tools like
```
eval
```
,
```
get_errors
```
,
```
grep_logs
```
, and
```
get_logs
```
. Logs output via the
```
log()
```
interface can be retrieved via
```
grep_logs
```
and
```
get_logs
```
; prioritize using
```
grep_logs
```
to save context.
If the user is developing a visual feature, use
```
screenshot
```
to get an in-game screenshot to confirm the effect.
After modifying the script, use
```
reload_script
```
to reload it. The client does not auto-reload.
Use
```
get_library
```
to view the source code of a library.
After ensuring all features work, ask the user to confirm that the requirements are met.
If the user raises further modification suggestions, implement them.
If the user confirms that the requirements are met, ask the user if they want to clean up debugging code, etc. Clean up debugging code and other unnecessary content for the user's convenience.

Script Structure

A script is a single

.js

file that executes entirely once when loaded: first register modules and settings, then attach behaviors with

events.on(...)

client.registerModule("Auto Sprint", -1, "Movement", false);
client.registerSlider("Auto Sprint", "Delay", 5, 1, 20, 1);

events.on("tick", function () {
    if (!client.isEnabled("Auto Sprint")) return;
    // ...
});

Scripts are automatically preprocessed and wrapped in an IIFE for execution (

(function(){ ...your code... })()

), so top-level

var

and

function

declarations are private and will not overwrite each other across different scripts. To share code across scripts, use libraries.

Use one of these six categories:

Combat

Movement

Render

World

Player

Inventory

A single script can register multiple modules, commands, and HUD elements.

Java Interop

The engine provides Nashorn-style Java interoperation.

mc

and everything obtained from it (players, entities, items, worlds) are Java objects — you can directly call their methods:

mc.player.getX();
mc.player.getMainHandItem().getCount();
mc.level.getBlockState(pos).getBlock();

Getting Classes

Use

Java.type()

to get a class, which can be used for

new

instances, reading static fields, and calling static methods:

var BlockPos = Java.type("net.minecraft.core.BlockPos");
var Items = Java.type("net.minecraft.world.item.Items");
var Component = Java.type("net.minecraft.network.chat.Component");

var pos = new BlockPos(100, 64, 200);          // Constructor
var stick = Items.STICK;                        // Static field
var text = Component.literal("hello");          // Static method

Write fully qualified names with dots (

net.minecraft.core.BlockPos

), not slashes.

For array types, write

"int[]"

"java.lang.String[]"

Inner classes (nested classes, enums) are separated by
$
, not dots. The engine directly passes the name to

Class.forName

and does not automatically convert dots to

. Incorrect names will throw

Java class not found

Java.type("com.mojang.blaze3d.vertex.VertexFormat$Mode");        // Correct
Java.type("net.minecraft.world.entity.Entity$RemovalReason");     // Correct
Java.type("com.mojang.blaze3d.vertex.VertexFormat.Mode");         // Wrong, class not found

Enum constants are accessed as static fields:

var Mode = Java.type("com.mojang.blaze3d.vertex.VertexFormat$Mode");
var quads = Mode.QUADS;

The result of

Java.type

is cached, so repeated calls have no extra overhead. You can safely write it in event callbacks, though placing it at the top level of the script is clearer.

Name Mapping

The engine performs remapping automatically when looking up fields and methods, so use Mojang names (

getX

getMainHandItem

If you are sure you have written the correct Mojang name but still have issues, you can use

eval

to probe first, as the mapper does not map 100% of all fields and methods.

The same applies to class names — just write

net.minecraft.core.BlockPos

Overloading and Type Conversion

Parameters are automatically converted according to Java method signatures: JS numbers convert to

int

float

double

, strings convert to

String

, and JS functions can be passed to functional interfaces (single-method interfaces). When there are overloads, the engine selects a matching one based on the number and type of parameters.

If you are unsure whether a method exists or what it returns, test it on the spot with

eval

mc.player.getMainHandItem().getItem().toString()

Arrays

Java arrays are more user-friendly than collections: they have

.length

and can be accessed by index:

var arr = someJavaMethodReturningArray();
arr.length;
arr[0];

But collections are not arrays — see the Tips section below.

Type Checking

var Player = Java.type("net.minecraft.world.entity.player.Player");
if (Java.isType(entity, Player)) { ... }

instanceof

does not work with Java types (it follows the JS prototype chain). Always use

Java.isType

to check Java types.

Java.isJavaObject(x)

checks whether a value is a Java object.

Tips

Some specifications and notes for the script system.

Java Collections Are Not JS Arrays

mc.level.players()

returns a

java.util.List

, which does not have
.length
. When you write

for (var i = 0; i < list.length; i++)

, the condition becomes

0 < undefined

, so the loop never executes, and no error is thrown — this is one of the hardest types of bugs to find.

var players = mc.level.players();
players.length                   // undefined
players.size(); players.get(0)   // Works
Java.from(players).length        // Works, converts to a real JS array

Java.from()

accepts Java arrays and any

Iterable

(List/Set/Collection). To iterate over a

Map

, you first need to call

.entrySet()

.values()

Setting IDs Are Always

"ModuleName:SettingName"

Registration takes two parameters, but reading uses a concatenated string:

client.registerSlider("My Module", "Speed", 1, 0, 5, 0.1);
client.getNumber("My Module:Speed");

HUD settings do not belong to the module itself. You must use

client.hudProperty(hud, label)

to generate the ID — do not concatenate it manually.

HUD Must Write Back

ctx.width

ctx.height

Without these, the element has no hitbox, and users cannot drag or click it in HUD edit mode, even though it looks normal on screen.

client.registerHud("Coords", { anchor: "Left Bottom", x: 4, y: 4 }, function (graphics, ctx) {
    var text = "X " + Math.round(mc.player.getX());
    render.drawString(graphics, text, ctx.x, ctx.y, 0xFFFFFFFF);
    ctx.width = render.getStringWidth(text);   // Required
    ctx.height = render.fontHeight();          // Required
});

3D Tags Should Take an Entity, Not Coordinates

When passing an entity, the engine uses

partialTicks

for interpolation, so the tag follows the entity smoothly when it moves. If you pass coordinates obtained from

getX()

yourself, you get the position at the end of the tick, causing the tag to jitter and not align with the entity's rendered position.

render.drawTag("§e" + p.getName().getString(), p, 0.4, { autoScale: true });   // Recommended
render.drawTag("§aSpawn", 100.5, 65, 200.5, {});                               // Only use for fixed positions

The third parameter is the extra offset above the entity's height; the engine already accounts for the hitbox height.

Colors Are ARGB, Alpha First

0xFF55FF55

is opaque green. If you omit the alpha channel and write

0x55FF55

, the alpha value is 0, making it completely transparent — it looks like "nothing was drawn".

Text color codes use

§

(U+00A7), e.g.,

"§cRed"

"§lBold"

Module Enable/Disable Must Be Checked Manually

Registering a module does not make events only fire when it is enabled. Every callback must check this on its own:

events.on("tick", function () {
    if (!client.isEnabled("My Module")) return;
    // ...
});

You can also listen to

enable

disable

events for initialization and cleanup.

Of course, you can write auxiliary features for other modules — logic that only executes when another existing module is enabled.

Events

There are three types, with different usage patterns:

Notification type — only informs you that something happened:

events.on("tick", function () { ... });
events.on("render3d", function (partialTicks) { ... });

Cancelable type —

return true

to prevent the default behavior:

events.on("chat", function (text) {
    return text === "secret";     // true = do not send
});

Modifiable type — receives an object, modify its fields:

events.on("movementInput", function (e) { e.jump = true; });
events.on("fov", function (e) { e.factor = 1.5; });

In modifiable events,

return

has no effect — you must modify the fields. Which category each event belongs to and what its fields are called are noted in each

on(...)

overload in

types.d.ts

There are two rendering events:

render2d

for drawing screen UI (provides

graphics

), and

render3d

for drawing world content (

render.drawTag

render.drawBox

can only be called here).

3.2.0 Update Notes

Java Features

Feature	Example
Method Reference	`list.stream().map(java.lang.String::length)` , `java.lang.Integer::parseInt` , `'text'::length` , `X::new`
Direct class access via package name	`var File = java.io.File;` `net.minecraft.core.BlockPos`
`Packages` root	`new Packages.java.util.HashMap()`
`JavaImporter` + `with`	`with (new JavaImporter(java.io, java.util)) { new File('a'); new HashMap(); }`
Automatic function-to-interface conversion (SAM)	`new java.lang.Thread(function () { ... }).start()`
Anonymous classes	`new java.lang.Runnable() { run: function () { ... } }`
Class inheritance / implementing multiple interfaces	`Java.extend(java.util.ArrayList, { add: function (x) { return Java.super(this).add(x); } })`
`Java.super`	Call the parent class implementation in an overridden method
`Java.to`	`Java.to([1, 2], 'int[]')`
`X.class`	`java.util.ArrayList.class` (Nashorn compatible)
Iterating Java collections	`for (var p of mc.level.players())` , `[...list]` , `var [a, b] = list` ; Maps yield `[key, value]` , also supports Iterator, Stream, Java arrays
Object equality	`mc.player === mc.player` is true; `===` , `Object.is` , and Map/Set keys all compare based on the underlying Java object
`instanceof` keyword	`p instanceof net.minecraft.world.entity.player.Player` ; also supported for classes generated by `Java.extend`
Passing JS arrays to Java	Automatically converted to Java arrays or `List` ; varargs methods can directly accept arrays: `LongStream.of([1, 2, 3])`
Static fields	Read and write in real time, with type conversion based on field type (previously, reads returned snapshots); final fields are read-only

Client API

All old flat interfaces like

client.getBool(...)

are fully retained, and a new set of object-oriented interfaces has been added:

var aura = moduleManager.getModule('Legit Aura');
aura.enabled = true;                         // Consistent with clicking the GUI (triggers notification)
aura.key = 'R';                              // Supports key names
for (var p of aura.getProperties()) {
    log(p.label, p.type, p.value, p.visible);
}
var mode = aura.getProperty('Mode');
mode.cycle();                                // Single -> Switch
mode.children;                               // Only returns child settings visible under current conditions

moduleManager
:

getModule

getModules(category?)

getEnabledModules

getCategories

getCategoryParents

getProperty(id)

hasModule

Module

Basic info:

name

category

categoryParent

categoryLeaf

description

(writable),

icon

inline

script

keyName

Read/write:
```
enabled
```
,
```
key
```
.

Methods:

toggle

enable

disable

setEnabled(v, silent)

getProperties

getAllProperties

getProperty

getBinds

bind(key, options)

Property
- Read/write:
```
value
```
  , which is validated on write: sliders are limited to range and aligned to step size, mode rejects unknown options, multi discards unknown options.
- Read-only info:
```
type
```
  ,
```
defaultValue
```
  ,
```
min
```
  /
```
max
```
  /
```
inc
```
  ,
```
options
```
  ,
```
optionIcons
```
  ,
```
hint
```
  ,
```
condition
```
  .
- UI-related:
```
visible
```
  (includes parent conditions),
```
hidden
```
  (writable),
```
label
```
  (writable).
- Hierarchy:
```
parent
```
  ,
```
children
```
  ,
```
swatch
```
  .
- Methods:
```
reset
```
  ,
```
toggle
```
  ,
```
cycle
```
  ,
```
select
```
  /
```
deselect
```
  /
```
isSelected
```
  /
```
toggleOption
```
  .
Wrapper objects are cached (the same module/property always returns the same object), and each read gets the real-time state; accessing an object after it has been unregistered will throw a
```
ReferenceError
```
.

var bind = keybindManager.add(aura, 'KP_8', { mode: 'hold' });
bind.key = 'MOUSE4';
bind.remove();

var m = macroManager.add('Message', { name: 'gg', message: '/hub', key: 'H' });
m.run();

keybindManager

getBinds

getBind

find(target)

add

remove

keyCode

keyName

Bind

target

key

mode

value

visible

isModule

module

property

update()

remove()

macroManager

getMacros

getMacro

add('Message' | 'Item', options)

remove

run

Macro

name

key

message

item

match

rotation

switchMode

yawOffset

pitch

update()

run()

remove()

Event	Parameters	Description
`click`	`(button, action, x, y)`	All mouse button presses/releases, return true to cancel
`scroll`	`(delta, x, y)`	Mouse wheel, return true to cancel (e.g., prevent hotbar switching)
`charTyped`	`(char, codepoint)`	Character input (supports Chinese), return true to cancel
`keyInput`	`(key, action)`	All keyboard events (press 1 / release 0 / repeat 2), triggered in any interface, return true to consume the key

The semantics of the original

key

event remain unchanged (only triggered in-game or in container interfaces, only reports presses).

input

provides:

getMouseX/Y

(same GUI coordinate system as

render2d

getScreenWidth/Height

getGuiScale

isMouseDown

isKeyDown

isMouseGrabbed

setMouseGrabbed

(release or grab mouse),

isScreenOpen

keyCode

keyName

Key names: Anywhere a key is required, it accepts

'R'

'F5'

'LSHIFT'

'KP_9'

'NUMPAD9'

'M4'

'MOUSE4'

'key.keyboard.r'

, or directly passing a key code.

keyName

and

keyCode

can be converted to each other.

render.bloom(graphics, x, y, w, h, radius, color, spread, intensity)

: Rounded rectangle glow effect.

client.getUsername()

client.getVersion()

client.getMinecraftVersion()

Forge Event Hook

var id = events.onForge('LivingDeathEvent', function (e) { log(e.getEntity()); });
events.onForge('ClientChatReceivedEvent', function (e) { return /spam/.test(e.getMessage().getString()); }); // true = cancel
events.offForge(id);

Event types can be passed as Java classes or by name: simple name (
```
LivingDeathEvent
```
), nested name (
```
RenderGuiOverlayEvent.Pre
```
), or full name. Subclasses will also be matched.
Options:
```
phase: 'pre' | 'post'
```
(before or after Forge's own listeners),
```
receiveCanceled
```
,
```
anyThread
```
(default only receives events from the main thread).

Event Loop

setTimeout

setInterval

clearTimeout

clearInterval

queueMicrotask

, Promise/async.

Fetch (WHATWG)

const res = await fetch('https://example.com/api', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ a: 1 }),
});
const data = await res.json();

Redirects support three modes:
```
follow
```
,
```
manual
```
,
```
error
```
, with a maximum of 20 hops.

Supports

AbortController

AbortSignal

, including

AbortSignal.timeout

any

Streaming read: Resolves as soon as response headers arrive, and the response body arrives in chunks via
```
res.body
```
(
```
ReadableStream
```
).
Automatically sends
```
accept-encoding: gzip, deflate
```
and automatically decompresses responses.

Supporting objects:

Request

Response

(including

json

redirect

error

clone

Headers

URL

URLSearchParams

Blob

TextEncoder

TextDecoder

DOMException

Deno

const server = Deno.serve({ port: 8080 }, async (req) => {
  const url = new URL(req.url);
  switch (url.pathname) {
    case '/hello': return new Response('hi');
    case '/echo':  return Response.json(await req.json());
    case '/sse':   return new Response(new ReadableStream({
      async pull(c) { await new Promise(r => setTimeout(r, 1000)); c.enqueue('data: tick\n\n'); },
      cancel() { log('client left'); }
    }), { headers: { 'content-type': 'text/event-stream' } });
    default: return new Response('not found', { status: 404 });
  }
});

iridium-script

NPX Install

Tags

SKILL.md Content (Chinese)

Introduction

Before You Start

MCP

MCP Not Installed

StreamHTTP

stdio

MCP Not Working

Libraries

Development Workflow

Script Structure

Java Interop

Getting Classes

Name Mapping

Overloading and Type Conversion

Arrays

Type Checking

Tips

Java Collections Are Not JS Arrays

Setting IDs Are Always "ModuleName:SettingName"

HUD Must Write Back ctx.width / ctx.height

3D Tags Should Take an Entity, Not Coordinates

Colors Are ARGB, Alpha First

Module Enable/Disable Must Be Checked Manually

Events

3.2.0 Update Notes

Java Features

Client API

Forge Event Hook

Event Loop

Fetch (WHATWG)

Deno

iridium-script

NPX Install

Tags

SKILL.md Content (Chinese)

Introduction

Before You Start

MCP

MCP Not Installed

StreamHTTP

stdio

MCP Not Working

Libraries

Development Workflow

Script Structure

Java Interop

Getting Classes

Name Mapping

Overloading and Type Conversion

Arrays

Type Checking

Tips

Java Collections Are Not JS Arrays

Setting IDs Are Always "ModuleName:SettingName"

HUD Must Write Back ctx.width / ctx.height

3D Tags Should Take an Entity, Not Coordinates

Colors Are ARGB, Alpha First

Module Enable/Disable Must Be Checked Manually

Events

3.2.0 Update Notes

Java Features

Client API

Forge Event Hook

Event Loop

Fetch (WHATWG)

Deno

Setting IDs Are Always
`"ModuleName:SettingName"`

HUD Must Write Back
`ctx.width`
/
`ctx.height`

Setting IDs Are Always
`"ModuleName:SettingName"`

HUD Must Write Back
`ctx.width`
/
`ctx.height`