Wsamiaw docs / Scripting

Scripting

A script is a .java file. No class, no imports. It shows up as a module under ClickGUI, in Scripts. Source of truth is the Java API under wsamiaw.script.api.

Trust boundary. Scripts are fully privileged. They can send packets and toggle modules. Only run code you wrote or fully trust.

Start

  1. .script create Radar
  2. Script Writer, or .script writer. Ctrl+S, then Ctrl+R.
  3. ClickGUI, Scripts, turn it on.

Files live in .minecraft/config/Wsamiaw/scripts/. A JDK is best. The jar also ships a compiler fallback.

Chat colors use &a green, &c red, &7 gray, &e yellow, &b aqua, &f white, &8 dark gray, &l bold, &r reset. Draw colors are 0xAARRGGBB — build with host.util.argb(a,r,g,b) or host.util.rgb(r,g,b).

A whole script

Settings are born in onLoad. Everything else reads them by name. host.every is true once per period, so this does not spam chat.

void onLoad() {
    host.bool("Whisper", true);
    host.slider("Range", 8f, 3f, 32f);
}

void onEnable() {
    host.say("&aRadar on");
}

void onUpdate(UpdateEvent e) {
    if (!host.on("Whisper") || !host.every("scan", 400)) return;
    var p = host.nearest();
    if (p == null || p.distance() > host.num("Range")) return;
    host.say("&7" + p.name() + " &8" + (int) p.distance() + "m");
}

void onChat(String text) {
    if (text.toLowerCase().contains("gg")) host.chat("gg");
}

void onRender2D(Render2DEvent e) {
    var g = e.getGraphics();
    var p = host.nearest();
    String line = p == null ? "alone" : p.name();
    host.render.rect(g, 8, 8, 140, 22, 0xCC141413);
    host.render.text(g, line, 14, 14, 0xFFE8E6E0);
}

What you actually call

CallDoes
host.bool / slider / choiceMake a ClickGUI setting, inside onLoad
host.on / num / textRead it later. text on a choice is the label
host.chat host.sayServer chat. A leading / is a command. say stays on your client
host.ground health food hurt pingYou
host.x y z yaw pitch lookWhere you are and where you look
host.held count jump sneaking sprintingHand, inventory, movement
host.key("w")w a s d space shift ctrl attack use, or key.keyboard.r
host.every("id", 1000)True once per period, in milliseconds
host.nearest() host.players()Other players. p.name() p.distance()
host.raycast(4.5)Block under the crosshair, or null. .x .y .z .side .block
host.inventory.slot() stack(i) click(slot, button, mode)Hotbar and the open chest. Mode 0 pickup, 1 shift, 2 swap, 4 drop
host.world.entity(id) scoreboard() tab()One entity, sidebar lines, tab names
host.friend("name") host.isFriend("name")Friend list
host.render.block(x, y, z, argb) line3(...)World box and line, from onRender3D
host.ui.claim("hud.arraylist") rounded textOwn a HUD/ClickGUI surface; draw on the native pass
host.theme.accent() bg() set("sage")Active theme colors and switcher (ClickGUI tokens only)
host.enabled("Sprint")Is that module on. enable and disable flip it
host.fill(...) / host.world.fill(...)Client-side box fill (visual only, max 12000 blocks)

Chat colors: &a green, &c red, &7 gray, &e yellow. Draw colors are 0xAARRGGBB.

Hooks

All optional. They run only while the module is on. onUpdate is already the pre-tick. Do not write a class or imports.

onLoad onEnable onDisable onUpdate onTick onRender2D onRender3D onPacket onAttack onJump onKnockback onMove onPostMotion onWindowClick onRenderLiving onLeftClick onRightClick onStrafe onHitSlow onSafeWalk onHitBlock onSwap onCancelUse onRaytrace onBlockBox onKey onChat onWorldLoad onDisconnect onScreen onScroll onClickGui onClickGuiClick onClickGuiRelease onClickGuiScroll onClickGuiKey

ClickGUI hooks require host.ui.claim("clickgui"). ESC still closes. The copy button below is the full surface for an AI: do not invent a method it does not list.

host.ui

Native HUD / ClickGUI pass. Claim a surface so the built-in plate hides; release or disable restores it. Colors are 0xAARRGGBB.

Claim surface ids

Surface idEffect
clickguiHides built-in ClickGUI; enables onClickGui* hooks
hudHides every hud.* plate
hud.arraylistArraylist plate
hud.targetTarget HUD
hud.scoreboardScoreboard overlay
hud.watermarkWatermark
hud.islandIsland HUD
hud.notificationsNotifications
hud.radarRadar
hud.musicMusic HUD
hud.staffStaff list
hud.potionsPotion list
hud.infoInfo strip
hud.newNew-HUD plate

Claiming hud also makes owns("hud.arraylist") (and other hud.*) true while the blanket claim is held. Another owner already holding a surface makes claim return false.

Ownership

MethodReturnsDescription
claim(surface)booleanTake ownership; true if you own it
release(surface)voidReturn the surface to the built-in plate
owns(surface)booleanThis script owns it, or owns blanket hud for hud.*

Drawing

MethodDescription
rect(x,y,w,h,argb)Filled rectangle
rounded(x,y,w,h,r,argb)Filled rounded rectangle
stroke(x,y,w,h,r,stroke,argb)Rounded outline
rectStroke(x,y,w,h,stroke,argb)Sharp-corner outline
line(x0,y0,x1,y1,w,argb)Line segment
circle(cx,cy,r,argb)Filled circle
gradient(x,y,w,h,top,bottom)Vertical gradient
gradientH(x,y,w,h,left,right)Horizontal gradient
frost(x,y,w,h,r) / frost(...,alpha)Frosted glass
glow(x,y,w,h,r,argb,strength)Soft glow
card(x,y,w,h,r,fillArgb,hud)Themed card
clip / unclipScissor stack
alpha(mul) / popAlphaAlpha stack
icon(x,y,size,glyph,argb)Glyph/icon
image(x,y,w,h,r,pngBytes)PNG image
text(text,x,y,size,argb)Native text
textWidth(text,size) textHeight(size)Measure text
hit(x,y,w,h,mx,my)Point-in-rect (half-open)
screenW() screenH()GUI-scaled size
closeGui()Close current screen

ClickGUI hooks

HookDescription
onClickGui(mx, my)Paint each frame
onClickGuiClick(mx, my, button)Mouse down
onClickGuiRelease(mx, my, button)Mouse up
onClickGuiScroll(mx, my, dir)Wheel (−1 / +1)
onClickGuiKey(key)Key; ESC still closes
void onEnable() {
    host.ui.claim("hud.arraylist");
}
void onDisable() {
    host.ui.release("hud.arraylist");
}
void onRender2D(Render2DEvent e) {
    if (!host.ui.owns("hud.arraylist")) return;
    host.ui.rounded(8, 8, 120, 18, host.theme.radius(), host.theme.bg());
    host.ui.text("array", 14, 12, 9, host.theme.accent());
}

host.theme

Active client theme tokens as ARGB ints. Caveat: every color/radius accessor reads only the active theme’s ClickGUI token group (theme.clickGui.*). HUD-specific sections are not exposed.

MethodReturnsDescription
name()StringActive theme name, or empty
list()List<String>Known theme names
set(name)booleanSwitch active theme without saving
save(name)booleanSave a copy under name
accent()intAccent (fallback 0xFF4FC3F7)
accentAlt()intSecondary accent (fallback 0xFF81C784)
bg()intPanel background (fallback 0xF20E0E12)
header()intHeader strip (fallback 0xFF14141A)
text()intPrimary text (fallback 0xFFEEEEF4)
textDim()intMuted text (fallback 0xFF9494A0)
row()intRow background (fallback 0xE6121217)
radius()floatCorner radius (fallback 9)
setAccent(argb)voidLive-apply accent without saving
setBg(argb)voidLive-apply background without saving

There is no setHeader, no HUD palette accessors, and no inventable token beyond this table.

host.player

MethodReturnsDescription
present()booleanLocal player exists
entity()ScriptEntityWrapped local player, or null
name() uuid()StringProfile identity
x() y() z()doublePosition
pos()ScriptVec3Position vector
yaw() pitch()floatLook angles
setYaw(float) setPitch(float)voidSet look
eye()floatEye height
health() maxHealth()floatHealth
absorption()floatAbsorption
armor()intArmor value
air()intAir supply
food()intFood level
saturation()floatSaturation
hurt()intHurt time
xp() xpBar()int / floatExperience
onGround()booleanOn ground
sprinting() setSprinting(b)Sprint
sneaking() setSneaking(b)Sneak
flying() setFlying(b) mayFly()Flight ability
moving() forward() strafe()Move input
setMove(strafe, forward) stopMove()voidOverride move vector
motion() motionX/Y/Z()Velocity
setMotion(x,y,z) setMotionX/Y/ZvoidSet velocity
speed() setSpeed(v)Horizontal speed
gamemode() gamemode(name)Get/set local mode
creative() survival() adventure() spectator()booleanMode checks
using() useTicks()Item use
onFire() inWater() inLava() riding()booleanEnvironment
fall() ticks()Fall distance / tick count
held() count(id) slot() slot(n)Hand / inventory
jump() swing() swingOffhand()voidActions
attack(entity) attack(entityId)voidAttack
drop() dropStack()booleanThrow items
place()booleanUse on looked-at block
raycast(distance) raycast(distance,yaw,pitch)ScriptHitBlock ray
rayEntity(distance) rayEntity(distance,yaw,pitch)ScriptEntityEntity ray
rotationsTo(entity) rotationsTo(x,y,z)float[]{yaw,pitch}
serverYaw() serverPitch()floatSent look
server() screen() closeScreen() ping()Session
sendChat(text) clientMessage(text)voidChat
effects() potion(id)Effects
attackStrength()floatCooldown cooldown 0..1
target()ScriptEntityKillAura target

host.world

MethodReturnsDescription
present()booleanLevel loaded
dimension()StringDimension id
time() time(ticks)Read / set client clock
difficulty() hardcore()World rules
rain() thunder() rain(f) thunder(f)Client weather
spawnX() spawnY() spawnZ()intRespawn
players() player(name) nearestPlayer()Players
playersWithin(range) playerCount()Nearby / count
entities() living() entity(id)Entities
within(range) livingWithin(range)Range queries
blockAt(x,y,z) block(x,y,z)ScriptBlockBlock lookup
air(x,y,z) solid(x,y,z) biome(x,y,z)Convenience
scoreboard() tab() network()Sidebar / tab
set clear fill replace walls sphere undo undo(n)Client-only edits; prefer fill (not host.fill); cap 12000; sphere r ≤ 16
dig dig(side) digStop crack placeAgainst interactServer-visible actions
spawn remove clearSpawned prop shapeClient entities / props
particle burst explode lightning soundFX

Block ids accept stone or minecraft:stone. Dig sides: up down north south east west.

host.modules

MethodDescription
get(name)Module or null
isEnabled(name)Enabled state
setEnabled(name, bool)Enable/disable
enable(name) disable(name) toggle(name)Convenience power controls
names()Every module name
enabled()Names that are on
category(name)Category name
description(name)Description
key(name)Bound key code
hidden(name)Hidden from list
tag(name)Module tag
settings(name)Internal property names
getValue(module, property)Current value
setValue(module, property, value)Set value; types must match
button(module, setting) button(module, setting, bool)Read/write boolean property
slider(module, setting) slider(module, setting, double)Read/write numeric property
killAuraTarget()KillAura target, or null

Property names are internal keys (min-cps, range), not ClickGUI labels.

host.settings

Create only inside onLoad.

MethodReturnsDescription
slider(name, def, min, max)FloatPropertyFloat slider
toggle / boolBooleanPropertyToggle
mode / choiceModePropertyMode list
key(name, defKey)KeyPropertyKey property
on num text valuecurrentRead without storing a field
keybind(keyCode, IntConsumer)voidFires while enabled

Packets

void onPacket(ScriptPacketEvent e) {
    if (e.outgoing() && e.packet() instanceof MovePacket move) {
        // move.onGround();  e.cancel();
    }
}

host.packets.chat, swing, attack, move, look. sendNoEvent skips other client packet handlers.

host.packets

MethodDescription
send(Packet) sendNoEvent(Packet) send(ScriptPacket)Send paths
wrap(packet, outgoing)Convert to ScriptPacket
move(onGround) move(x,y,z,onGround) move(x,y,z,yaw,pitch,onGround) look(...)Move builders
swing() chat(String) attack(entityId)Other builders
sendChat sendSwing sendAttack sendMove sendLook sendPosLookBuild + send

ScriptPacket: name() raw() outgoing() incoming(). Subtypes: MovePacket (x y z yaw pitch onGround), AttackPacket (entityId), InteractPacket (entityId hand location), SwingPacket, ChatPacket (message), SystemChatPacket (text overlay), DigPacket (action x y z), PlacePacket, HotbarPacket (slot), PlayerCommandPacket (action), ClickSlotPacket, CloseScreenPacket. No C03/S08 names.

host.render

2D (onRender2D, e.getGraphics())

MethodDescription
rect(gfx, x, y, w, h, argb)Filled rect
rect(gfx, x, y, w, h, Color)Same with java.awt.Color
outline(gfx, x, y, w, h, thickness, argb)Outline
rounded(gfx, x, y, w, h, radius, argb)Rounded fill
gradient(gfx, x, y, w, h, top, bottom)Vertical gradient
text(gfx, text, x, y, argb)Vanilla font text
textWidth(text)Font width
textHeight()Font line height
line(gfx, x1,y1,x2,y2, thickness, argb)2D line
circle(gfx, cx, cy, radius, argb)Filled circle

3D (onRender3D)

MethodDescription
block(x,y,z, argb)Block outline
block(x,y,z, argb, throughWalls)Optional through walls
box(x1,y1,z1,x2,y2,z2, argb)AABB outline
filled(..., stroke, fill)Outline + fill
line3(...) / with width, throughWallsWorld line
entity(entity, argb) / with throughWallsEntity box
tracer(x,y,z, argb)From eyes
circle3(x,y,z, radius, argb)Horizontal circle
cylinder(x,y,z, radius, height, argb)Cylinder
arrow(x1,y1,z1,x2,y2,z2, argb)Direction arrow
text3(x,y,z, text, argb)World text
nametag(entity, text, argb)Text over entity

For native HUD/ClickGUI plates prefer host.ui after a claim.

host.inventory

MethodDescription
slot() slot(n)Get/select hotbar 0–8
size()Player inventory size
stack(i)Player inventory index
hotbar(n)Hotbar stack
offhand()Offhand stack
armor(0..3)Helmet, chest, legs, boots
find(id) findHotbar(id)First match or −1
empty()First empty slot or −1
has(id)Any matching stack
chest()Open chest title, or empty
chestSize()Chest slots, or −1
chestStack(i)Chest menu slot
cursor()Item on the mouse
click(slot, button, mode)Mode 0 pickup, 1 shift, 2 swap, 4 drop, 5 quick craft, 6 pickup all
shift(slot)Quick move
swap(slot, hotbar)Swap with hotbar
throwSlot(slot)Drop stack

host.client

MethodDescription
fps()Frames per second
width() height()Screen pixels
guiWidth() guiHeight()GUI-scaled size
scale()GUI scale
paused()Game paused
singleplayer()Has integrated server
localServer()Local server
partial()Render partial tick
memoryUsed() memoryFree() memoryMax()JVM memory bytes
timer()Current timer speed
timer(speed)Set timer (1 = vanilla)
resetTimer()Reset timer
username()Player or session name
disconnect()Disconnect with reason script
millis() nanos()Clocks

host.keys

MethodDescription
down(name)Mapping held (same names as host.key)
set(name, pressed)Hold or release
tap(name)Press then release
attack(b) use(b)Mouse buttons
jump(b) sneak(b) sprint(b)Movement keys
forward(b) back(b) left(b) right(b)WASD
left() right()Attack / use currently down
mouseX() mouseY()Raw mouse position

host.util

MethodDescription
millis() nanos()Clocks
every(name, ms)True first time and each period
randomInt(min,max) randomFloat randomDoubleRNG
chance(percent)Percent probability
round(value, decimals) format(value, decimals)Formatting
clamp (int/float/double)Clamp overloads
lerp(a,b,t) wrap(degrees) angleDiff(from,to)Interpolation / angles
floor ceil hypot(x,z) distance(...)Geometry
rgb(r,g,b) argb(a,r,g,b)Build 0xAARRGGBB
alpha red green blueChannel extractors
color(text)& → section sign
strip(text)Remove color codes
key(name)Same names as host.key
setInterval(runnable, ms)Repeating timer id
setTimeout(runnable, ms)One-shot timer id
clearInterval(id)Cancel timer
addScroll(delta) consumeScroll()Wheel accumulation

Model types

ScriptVec3

MemberDescription
x y zPublic double fields
ZEROConstant (0,0,0)
length()Euclidean length
add(ox,oy,oz)New vector sum
toString()Vec3(...)

ScriptHit

FieldDescription
x y zBlock position (ints)
sideHit face name
blockBlock id
hitX hitY hitZExact hit location

ScriptNetworkPlayer

MethodDescription
name() uuid()Identity
ping() latency()Tab latency (aliases)
gamemode()Mode name, or empty
raw()Underlying PlayerInfo

ScriptBlock

MethodDescription
x() y() z()Block pos
id() name()Registry id / display name
air() solid() liquid() water() lava() full()State checks
hardness() emission() biome()Properties
state() pos()Raw Minecraft types

ScriptItemStack

MethodDescription
empty() id() name() count() maxStack() customName()Basics
damage() maxDamage() durability() damaged() damageable()Durability
block() food() sword() pickaxe() axe() shovel() hoe()Kinds / tags
enchants() enchant(id) raw()Enchantments / raw stack

ScriptEntity

GroupMethods
Identityid uuid name displayName type raw
Positionx y z prev* pos motion* yaw pitch headYaw eye width height fall age
Livinghealth maxHealth absorption armor air maxAir hurt hurtResistant living player alive dead removed baby onGround
Flagsfire water lava invisible glowing sprinting sneaking swimming elytra riding vehicle silent invulnerable team
Distance / AABBdistance distanceTo min*/max*
Gearheld offhand helmet chestplate leggings boots
Effects / mutatorseffects potion moveTo setMotion glow hide rename remove (remove refuses local player)

Commands

  • .script create <name> writes a file from the short template
  • .script load compiles everything
  • .script writer opens the editor. Ctrl+S saves, Ctrl+R compiles
  • .script enable and disable <name>
  • .script list .script folder

Prompt for an AI

Paste this into the model before you ask it to write a script. It is the whole easy API, and it tells the model not to invent methods. The file is scripting-prompt.md.

Loading the prompt…