Dusk scripting

Getting started

The engine is Lua 5.2 (via LuaJ, bundled — nothing to install). Drop a .lua file in your Scripts folder, open the client, and it loads automatically. The folder ships with working example scripts you can edit.

Open the Scripts module (Scripts category) in the ClickGUI for two actions:

• Reload Scripts — re-scans and recompiles the folder without restarting.
• Open Folder — opens the folder in your file browser.

Scripts folder

Scripts live in:

%LOCALAPPDATA%\FLStudio\Local\Scripts

This folder is created on first launch and seeded with example scripts (example.lua, session_hud.lua, player_esp.lua, aim_assist.lua). Every *.lua file in it is loaded on startup.

Want them somewhere else? Set a path in the Scripts module's Folder field and press Reload Scripts — scripting (and the sandboxed files/storage APIs) will use that directory instead. Leave it blank for the default.

Script anatomy

A script is a .lua file that returns a table. The table holds metadata and callback functions. Every callback receives the module handle m as its first argument.

return {
  name        = "My Script",          -- becomes the module name in the GUI
  description = "What it does.",       -- tooltip
  category    = "SCRIPTS",             -- COMBAT / MOVEMENT / MISC / RENDER / SCRIPTS / CLIENT
  -- background = true,                -- optional: no GUI entry, always running

  on_load = function(m)               -- register settings here (runs once, at load)
    m:number("Range", 5.0, 1.0, 20.0, 0.5)
    m:bool("Silent", true)
  end,

  on_enable  = function(m) client.message("on")  end,
  on_disable = function(m) client.message("off") end,

  on_tick      = function(m) end,        -- every client tick while enabled
  on_render_2d = function(m, e) end,     -- HUD drawing; e = {width, height, tick_delta}
  on_render_3d = function(m, e) end,     -- in-world drawing; e = {tick_delta}
}

Foreground & background

• Foreground (default): the script becomes a toggleable module in the Scripts category, with settings, a keybind, and config persistence. Its event callbacks fire only while the module is enabled.
• Background (background = true): no module, no GUI entry. Its callbacks fire whenever the script is loaded. Good for pure utilities/HUDs.

Error handling

Callbacks

Define any of these as fields in your returned table. They fire automatically — each gets the handle m first, then any extra argument listed below.

The module handle: m

Every callback receives m as its first argument — it represents this script's own module. Use it to declare settings (which become real controls in the ClickGUI and are saved with your config), read those settings back at runtime, and control the module itself. Note the colon: settings are method calls, so write m:number(...), not m.number(...).

Registering settings — call these in on_load

Each call adds one control to the module's panel. The name you give is also the key you read it back with. Register once in on_load; they persist automatically.

on_load = function(m)
  m:section("Targeting")
  m:number("Range", 5.0, 1.0, 20.0, 0.5)
  m:range("Delay (ms)", 40, 60, 0, 500, 1)                 -- one min/max slider
  m:mode("Aim Point", "closest", { "closest", "head", "body" })
  m:bool("Auto Range", true)
  m:depends("Range", "Auto Range", false)                  -- hide "Range" while Auto Range is on
end

-- read a range back:
-- local d = m:get("Delay (ms)")   ->  { min = 40, max = 60 }

Reading & writing settings

local range = m:get("Range")          -- number
local c     = m:get("Color")          -- -> {r, g, b, a}
m:set("Range", 8.0)

Module control

Sandbox

All API tables are global. Values return nil/false/0 when you're not in a game, so guard with player.is_present() / world.is_present() before reading state.

The Lua standard library is available except the parts that reach outside the game: io and os.execute / os.exit / os.remove / os.rename / os.tmpname / os.getenv / os.setlocale are removed. math, string, table, os.time/os.clock/os.date, and pcall remain. For persistence, use the sandboxed files or storage API.

client

Talk to the game and the player's session: print to chat, send messages, read session info (FPS, ping, name), and trigger simple actions. Everything here works without a world loaded except the actions that need a player.

player

Read and control you — the local player: position, rotation, health, movement flags, and a few actions. Always call player.is_present() first; every other function returns nil/0/false when you're not in a game.

Presence & identity

Health & hunger

Position & rotation

Movement & combat flags

Actions

Status effects & held items

world & entities

Query the loaded world and the things in it — other players, mobs, items, blocks. Guard with world.is_present(). The entity-list functions return arrays of entity tables (described below), which you loop over with ipairs.

Entity tables

Every entity returned above is a snapshot table. Read fields directly (ent.x, ent.health, ent.distance). Always skip dead/removed ones and yourself:

local self_id = player.get_id()
for _, ent in ipairs(world.get_players()) do
  if ent.is_player and ent.alive and not ent.removed and ent.id ~= self_id then
    -- use ent.x, ent.y, ent.z, ent.health, ent.distance ...
  end
end

Block-state table

world.get_block_state(x, y, z) returns a snapshot of one block. properties is a sub-table of the live block-state values (keys vary by block), each typed as a number, boolean, or string. break_delta/instant_break account for your currently-held tool.

-- harvest ripe wheat within 6 blocks:
for _, b in ipairs(world.find_blocks("wheat", 6)) do
  local s = world.get_block_state(b.x, b.y, b.z)
  if s and s.properties.age == 7 then interaction.attack_block(b.x, b.y, b.z) break end
end

render

Draw on screen. render.color works anywhere, but drawing calls only work inside a render callback: 2D shapes/text in on_render_2d, in-world boxes in on_render_3d. Coordinates are GUI pixels with (0,0) at the top-left; e.width/e.height (passed to on_render_2d) give the screen size.

Colors

2D — inside on_render_2d

3D — inside on_render_3d

input

Read the keyboard/mouse and send genuine key/mouse presses. "Down" checks read raw hardware keys; "pressed" checks read the player's bound controls (so they respect a remapped keybind). The press/click functions can drive the input three different ways via a mode argument.

Reading state

Mouse output

Keyboard output

Keycodes are GLFW codes — get one from keybinds.get_key_code("W"). mode is "game" (default — drives the vanilla keybind, so movement/hotbar/use work and no focus is needed) or "os" (a real OS keystroke, needs focus).

-- hold W for 500ms via the game input, then a real OS spacebar tap:
input.key_press(keybinds.get_key_code("W"))
-- ... later:
input.key_release(keybinds.get_key_code("W"))
input.key_click(keybinds.get_key_code("SPACE"), 40, "os")

rotation & silent aim

Compute the angles needed to look at something, measure how far off your current aim is, and — with the silent-aim engine — actually move your aim there smoothly and server-side. The maths helpers are cheap and safe; the silent-aim functions drive the real rotation engine and should be called every tick while aiming.

Aim maths

Drives Dusk's rotation engine (the same one the combat modules use, with its priority arbiter). Call it every tick from on_tick (or on_send_movement) while you want to hold the aim, then rotation.reset() when done so it smoothly returns.

rotation.aim_at(x, y, z [, opts])        -- -> bool (got control)
rotation.aim_at_entity(id [, opts])      -- -> bool
rotation.reset([silent])                 -- rotate back + release; true while still moving back
rotation.stop()                          -- hard stop
rotation.is_tracking()   rotation.is_controlling()
rotation.get_silent_yaw()   rotation.get_silent_pitch()

Tune the aim with an opts table (all optional):

-- silent aim at the crosshair target, held while attack is pressed:
on_tick = function(m)
  if not input.is_attack_pressed() then rotation.reset() return end
  local t = combat.crosshair_target(4.0) or combat.nearest_player(4.0)
  if t then rotation.aim_at_entity(t.id, { yaw_speed = 40, pitch_speed = 40, silent = true })
  else rotation.reset() end
end

targeting

Find out what you're looking at. The get_* functions read your live crosshair (what the game itself is targeting); the raycast functions cast a fresh ray from your eyes so you can test an arbitrary angle or reach.

combat

Combat-timing helpers and target-finding — the building blocks of an aura or trigger-bot. Pair can_swing() with crosshair_target() to attack only when your hit will land at full damage.

interaction

Actually do things to entities and blocks — attack, right-click, use items, place/break. These send the real interaction packets, so they respect reach and the server. Aim first (with your view or silent aim), then interact.

inventory

Inspect and manage your items — read slots, switch your held item, search for an item, and click slots inside open containers.

Every slot is returned as an item table: empty (bool), count, max_count, item (registry id like "minecraft:diamond_sword") and name (display name). A query matches the registry id or its short path — "totem" matches minecraft:totem_of_undying.

Non-empty items also carry durability — damageable (bool), damage, max_damage, durability (hits left) and durability_percent — and enchantments: enchantments is a table like { ["minecraft:sharpness"] = 5 }, and item:get_enchantment(id) returns a level (0 if absent), matching the full id or its short path.

-- run a command once when the backpack fills up:
on_tick = function(m)
  if player.is_present() and inventory.is_full() and not m._sent then
    client.send_chat("/sellall")   m._sent = true
  elseif not inventory.is_full() then m._sent = false end
end

container

Read and click the slots of whatever screen is open — a chest, a shop menu, a villager trade GUI. Slot indices are handler-relative: the container's own slots come first, then your inventory. container.is_open() is false while only your own inventory handler is active, so you can tell "a chest is open" from "nothing".

modules

Read and drive the client's other modules from a script — toggle KillAura, check whether ESP is on, or read another module's HUD label. Names are the module's display name.

friends · teams · antibot

Decide who not to target. Use these to filter out friends, teammates, and bots before you aim or attack.

files

Read and write files for your script's own data (configs, logs, caches). Everything is sandboxed to the Scripts folder — a path that tries to escape it (..\, absolute paths) is rejected. Paths are relative to that folder.

json · http · bridge · storage

Work with data: parse/build JSON, call web APIs, share state between scripts, and save state across restarts.

json — parse & build JSON

http — call web APIs

bridge — share data between scripts (in-memory)

A key/value store shared by every loaded script, cleared on reload/restart. Use it to let two scripts coordinate (e.g. one sets a target, another reads it).

storage — persist across restarts

A string key/value store saved to Scripts/storage.json. Survives restarts. Values are strings — wrap tables with json.stringify going in and json.parse coming out. config.get/config.set are aliases (Raven compatibility).

util · keybinds · network

Small helpers: value/colour utilities, raw key/mouse access with key-name lookup, and other-player info from the tab list.

util — value helpers

keybinds — raw input

network — other players by tab name

server · accounts · blink

Drive your session from a script: hop between servers, rotate accounts through the switcher, and hold your own packets. Together these are what an account-rotating auto-mine loop needs.

server — join / leave / switch

accounts — the account switcher

-- sketch: hop to the next account and rejoin the same server
if done_mining then
  local addr = server.get_address()
  accounts.switch(next_account, function(ok)
    if ok then server.join(addr) end       -- rejoin after the session swaps
  end)
end

blink — hold your own packets (fake ping / stall)

The scripting equivalent of the Blink module: holds outbound packets so the server keeps seeing you where you were. A rolling delay reads like high ping; a zero delay holds everything until you let go.

Packet payloads

The p argument given to on_packet_send / on_packet_receive lets you inspect the raw network packet before it's sent or processed — and return false to cancel it. It's read-only and works by reflection, so field names come from Minecraft's obfuscation mappings: call p:fields() first to discover what a given packet exposes.

on_packet_send = function(m, p)
  if p.name == "PlayerMoveC2SPacket" then
    -- inspect: client.message(table.concat(p:fields(), ", "))
    -- cancel every move packet (freezes you server-side):
    -- return false
  end
end

Examples

The seeded scripts in your folder are the best reference. A few short ones:

Minimal HUD — coordinates

return {
  name = "Coords", category = "SCRIPTS",
  on_render_2d = function(m, e)
    if not player.is_present() then return end
    local xyz = string.format("%.1f %.1f %.1f", player.get_x(), player.get_y(), player.get_z())
    render.text(xyz, 6, e.height - 20, render.color(255,255,255), true, 16)
  end,
}

Player ESP tags

return {
  name = "Player ESP", category = "SCRIPTS",
  on_load = function(m) m:number("Max Distance", 64, 8, 256, 1) end,
  on_render_2d = function(m, e)
    if not player.is_present() or not world.is_present() then return end
    local max, self_id = m:get("Max Distance"), player.get_id()
    for _, ent in ipairs(world.get_players()) do
      if ent.is_player and ent.alive and ent.id ~= self_id and ent.distance <= max then
        local pt = render.world_to_screen(ent.x, ent.eye_y + 0.4, ent.z)
        if pt and pt.on_screen then
          local label = ent.name .. "  " .. string.format("%.1f", ent.distance) .. "m"
          render.text(label, pt.x - render.measure_text(label, 14) / 2, pt.y,
            render.color(255,255,255), true, 14)
        end
      end
    end
  end,
}

Persist a counter across restarts

return {
  name = "Launch Counter", category = "SCRIPTS",
  on_enable = function(m)
    local n = tonumber(storage.get("launches") or "0") + 1
    storage.set("launches", tostring(n))
    client.message("Enabled " .. n .. " time(s)")
  end,
}