Skip to content

ScriptingIntroduction

A script is a plain .js file that bitchos loads at runtime. It becomes a module of its own, with a switch in the menu, a keybind, settings that survive reloads, HUD elements, commands and access to everything bitchos already knows about the lobby you are in.

Drop a file into ~/.bitchos/scripts/, run /bitchos script reload, and it is live. No JDK, no Gradle, no IDE, no compile step. Scripts hot-reload while the game is running.

Getting started

Where the folder is, the four example scripts, and how a file becomes a module.

Start here →

Events

Every event that fires, what it carries, and which are missing on purpose.

Catalogue →

bitchos data

Threat scores, player stats, tags, party and team state, straight from the host.

Read the data →

Compiled extensions

The unsandboxed .jar path for people who want a type checker and an IDE.

Extensions →

Why JavaScript

Other overlays make you write Java. One compiles .java files in-game and needs you to install a JDK and point your launcher at it. Another needs Gradle and an IDE to build a plugin jar. Neither works when Lunar Client is the one choosing the Java runtime.

bitchos ships its own JavaScript engine (Rhino 1.7.14 in ES6 mode) inside the mod. It runs on whatever Java the client already has, and a script is one text file you can edit with Notepad.

What a script can do

  • React to the game. Chat lines, game start and end, players joining the lobby, party changes, /who rosters, key presses, every tick, every frame.
  • Draw. HUD text through the same drag-and-drop editor every built-in element uses, and 3D boxes, tracers and lines in the world.
  • Read bitchos. The lobby threat model, Hypixel stats for anyone in the tab list, tags, your party, Bed Wars teams and bed state.
  • Have settings. Toggles, sliders, dropdowns, text, colours and keybinds that show up in the menu and persist in config.json.
  • Add commands under /bitchos <name>.
  • Talk to the web with asynchronous HTTP, and keep per-script storage on disk.
  • Decorate nametags and the tab list with a short coloured suffix.

What a script cannot do

Scripts run inside a class allowlist with no Java bridge at all. They cannot open files, sockets, threads or reflection, cannot reach net.minecraft, and cannot touch raw OpenGL. Every one of those capabilities is offered another way (storage, HTTP, scheduling, the render namespace), and the sandbox page spells out the rules.

If you need a mixin, or a type checker, there is a second path: compiled .jar extensions. Those are ordinary Java on the game's class loader and are not sandboxed, which is why they are off by default.

Lunar and Forge

Scripts behave identically on the Lunar Client build and the Forge build. The host hooks a script sees are the same on both.