@wunk/lb-script-api-types

@wunk/lb-script-api-types

TypeScript types for the LiquidBounce (nextgen, MC 1.21+) GraalJS script API: the Java/Kotlin/Minecraft surface a LiquidBounce script can reach at runtime (mc, Client, RotationUtil, Setting, every @Tag event, and so on).

A refined fork of CCBlueX's @ccbluex/liquidbounce-script-api, adding typed per-event on() overloads, KDoc-to-TSDoc hover docs, binding fixes, ambient globals, and more. See the improvements list for the full diff.

Install

npm i -D @wunk/lb-script-api-types

Use

Pull in the ambient script globals through tsconfig.json:

{
  "compilerOptions": {
    "lib": ["es2023"],            // no DOM — see below
    "types": ["@wunk/lb-script-api-types/ambient"]
  }
}

Use a DOM-less "lib" (es2022/es2023): the GraalJS runtime has no DOM, and if lib.dom is loaded its localStorage: Storage silently overrides the script API's localStorage (a Java ConcurrentHashMap with get/put, not getItem/setItem), plus DOM globals pollute autocomplete with APIs that don't exist at runtime.

Class-value bindings (Vec3i, BlockPos, Hand, MathHelper, RotationAxis, ...) are raw java.lang.Class values at runtime: construct directly (new Vec3i(1, 2, 3)), but statics — including enum constants — live behind .static (Hand.static.MAIN_HAND, RotationAxis.static.YP.rotationDegrees(90)). Direct static access compiles against older typings but is undefined at runtime; these types model the real reachable surface (verified in a live client).

Now mc, Client, RotationUtil, Setting, Java.type, and the rest are globally typed. Event handlers are typed per event, since ScriptModule.on() has one overload for each LiquidBounce event:

module.on("attack", (e) => {
  e.entity;          // typed as the AttackEntityEvent payload
});

Import individual classes or events by their JVM path:

import { AttackEntityEvent } from "@wunk/lb-script-api-types/types/net/ccbluex/liquidbounce/event/events/AttackEntityEvent";

The package ships one .d.ts per class (mirroring the JVM package layout), so tsc only parses the types a script actually imports.

Typed Java.type (opt-in registry)

By default Java.type(...) returns any (or takes an explicit generic). Opt into the string-literal registry and it is fully typed from the class name alone — autocomplete on the string, typed statics/constructors on the result. Works in plain JS too (the editor language service picks it up from jsconfig):

"types": [
  "@wunk/lb-script-api-types/ambient",
  "@wunk/lb-script-api-types/registry-lb"   // net.ccbluex.* (~2.6k classes, ~+1s tsc)
]

const SilentHotbar = Java.type("net.ccbluex.liquidbounce.utils.client.SilentHotbar");
SilentHotbar.INSTANCE.serversideSlot;   // typed — no generic, no import

registry-full covers every generated class (~49k) — great for editor use, but it adds tens of seconds to batch tsc runs, so prefer registry-lb in CI. Unknown class names fall back to the generic any overload either way.

LiquidBounce internals that have a generated type but are not runtime globals (e.g. SilentHotbar) are reached via Java.type, typed with the matching import:

import type { SilentHotbar } from "@wunk/lb-script-api-types/types/net/ccbluex/liquidbounce/utils/client/SilentHotbar";
const silentHotbar = Java.type<{ INSTANCE: SilentHotbar }>(
    "net.ccbluex.liquidbounce.utils.client.SilentHotbar").INSTANCE;

Versioning

<lb-major>.<lb-minor>.<iteration>: major.minor track the LiquidBounce release line; the patch is this package's own iteration counter (so type-only improvements can ship between LB releases). 0.38.2 = "3rd type build for the LB 0.38 line". The exact LB commit and Minecraft version are in the package.json liquidbounce block:

npm view @wunk/lb-script-api-types liquidbounce

Regenerate with the pipeline in the repository when LiquidBounce updates.

License and attribution

GPL-3.0-or-later. These types derive from LiquidBounce (Copyright CCBlueX, GPL-3.0). This is an independent, modified redistribution. It is not published or endorsed by CCBlueX. The original API types are @ccbluex/liquidbounce-script-api.