lua api
Drop a script at %APPDATA%\feral\script.lua and switch Lua scriptson in the dashboard. The runtime ticks on the same thread as aim, relax and replay, so a script can read the live game state and move the cursor. Nothing is injected into osu!.
lifecycle
The whole file runs once when the script starts. Anything that should repeat goes inside osu.loop. osu.stop() ends the loop and the script.
osu.loop(function()
if not osu.is_playing then return end
log(string.format("%d ms", osu.cur_time))
end)| osu.loop(fn) | Call fn every tick until the script stops. |
| osu.stop() | Stop the loop and unload the script. |
| osu.sleep(ms) | Yield the calling thread for ms milliseconds. |
| osu.log(...) | Write a line to %APPDATA%\feral\cheat_log.txt. |
game state
Read-only fields on the osu table. They refresh every tick.
| osu.cur_time | Game clock, milliseconds. |
| osu.cur_state | osu! status enum. 2 is playing. |
| osu.cur_mods | Active mod bitmask. 16 is HardRock. |
| osu.is_playing | true while a map is running. |
| osu.ar / cs / od / hp | Difficulty values after mods. |
| osu.preempt | Approach time in milliseconds. |
| osu.object_count | Hit objects in the current map. |
| osu.map | Beatmap file name. |
| osu.px_per_osu | Screen pixels per playfield pixel. |
| osu.left_key / right_key | Your osu! tap keys as virtual key codes. |
input
Cursor positions are in playfield space: 512 wide, 384 tall, origin top-left. Keys are virtual key codes.
| osu.cursor() | Returns x, y of the real cursor in playfield units. |
| osu.set_cursor(x, y) | Move the cursor to a playfield position. |
| osu.press(vk) | Hold a key down. |
| osu.release(vk) | Release a key. |
| osu.click(vk) | Press and release once. |
| osu.has_mod(bit) | true when the live mod mask contains bit. |
| osu.beatmap | Beatmap table. Index it or call beatmap.get(). |
vectors and maths
Vector2 supports field access plus +, - and scalar *. v.length is a property, not a call.
local a = Vector2(osu.cursor()) local b = Vector2(256, 192) local step = normalize(b - a) * 4 osu.set_cursor(a.x + step.x, a.y + step.y)
| Vector2(x, y) | Construct a vector. A table with x/y also works. |
| getDistance(a, b) | Euclidean distance. |
| normalize(v) | Unit vector. |
| dot(a, b) | Dot product. |
| min / max / clamp | Scalar helpers. clamp(v, lo, hi). |
example: walk to a slider ball
local X = 0
osu.loop(function()
if not osu.is_playing then
X = 0
return
end
-- HardRock mirrors the playfield vertically
local mirror = osu.has_mod(16)
local cx, cy = osu.cursor()
local tx, ty = 256, mirror and 96 or 288
local dx, dy = tx - cx, ty - cy
local d = math.sqrt(dx * dx + dy * dy)
if d > 2 then
osu.set_cursor(cx + dx / d * 3, cy + dy / d * 3)
end
X = X + 1
end)