Skip to content

script_en

Jump to bottom
User670 edited this page Sep 5, 2023 · 1 revision

Quatrack Beatmap Scripting Guide

Quatrack beatmap scripts are written with Lua, and with file extension .lua.

Hello world

    function drawFront()
        gc.print("Hello world!",0,0)
    end

This is a basic Hello World script. It only defined a foreground drawing routine.

In the metadata of the beatmap file (.qbp), add $script=script_file_name.lua (replace the file name), and load the beatmap, you'll see "Hello world!" on the top left.

Overview of how scripting works

When the beatmap is opened, your entire script file will run once, and register "what to do when something happens", like what to draw before drawing tracks and notes, and what to draw after.

All event callbacks

init() - initialize. This function will be called once after the file is loaded. (MrZ: in most cases this doesn't seem necessary, it's just here because an init function seems to be a standard)

drawFront() - draw foreground. Every frame after drawing other elements, this will be called. Things drawn here will be in the front, covering up what's already drawn

drawBack() - draw background. Every frame before drawing other elements, this will be called. Things drawn here will be in the background, not covering up other things.

update(dt) - called every update frame. Note that drawing frame and update frame might not be the same, and it depends on the player's "update frame rate" settings. Use the dt that is passed in if necessary.

trackPress(id) - called once when the track is pressed. id is the ID of the track being pressed. It will be called ONCE ONLY when the key is PRESSED, including when autoplay presses it and including when player presses it without a note.

trackRelease(id) - called once when track is released. id is like above

List of functions and variables you can access

Lua native functions

    -- These are native Lua functions and libraries. If you need, search an online tutorial/documentation for Lua
    print();
    assert();error();
    tonumber();tostring();
    select();
    next();
    ipairs();pairs();
    type();
    pcall();xpcall();
    rawget();rawset();rawlen();rawequal();
    setfenv();setmetatable();
    math.xxx();
    string.xxx();
    table.xxx();
    bit.xxx();
    coroutine.xxx();

Game variables

Game data are in the game table. Note that this table is read-only, attempting to edit the values will do nothing.

    game.needSaveSetting
    game.autoPlay

    game.playSongTime
    game.songLength
    game.playSpeed

    game.hitLV
    game.hitTextTime

    game.safeAreaTimer
    game.time
    game.isSongPlaying
    game.hitOffests
    game.curAcc
    game.fullAcc
    game.accText
    game.combo
    game.maxCombo
    game.score
    game.score0
    game.hitCount
    game.totalDeviateTime
    game.bestChain

    game.map -- temporary and will delete later. Very complex, use at your own risk!
    game.hits -- temporary and will delete later. Very complex, use at your own risk!

Player settings

Player settings are in the setting table. Like game, this is read-only.

    -- These are pretty self-explanatory. Just guess the variable type and range based on the
    -- in-game settings, I'm too lazy to explain (ask me if you need)
    setting.clickFX
    setting.powerInfo
    setting.cleanCanvas
    setting.fullscreen
    setting.maxFPS
    setting.updRate
    setting.drawRate

    setting.sysCursor
    setting.locale
    setting.slowUnfocus

    setting.bgAlpha
    setting.musicDelay
    setting.dropSpeed
    setting.noteThick
    setting.chordAlpha
    setting.holdAlpha
    setting.holdWidth
    setting.scaleX
    setting.trackW
    setting.safeX
    setting.safeY
    setting.showHitLV
    setting.dvtCount

    setting.autoMute
    setting.mainVol
    setting.sfx
    setting.sfx_spawn
    setting.sfx_warn
    setting.bgm
    setting.stereo
    setting.vib
    setting.voc

Other advanced-ish functions

    -- Display a system message on top left
    -- time is number of seconds to display, defaults to 3
    message(message,time);

    -- These are extension libraries by me, similar to native functions, for math/strings/tables
    -- respectively. There are some commonly-used functions that are a bit advanced. I won't go
    -- into details here, you can just go and read source code. Has comments, should be easy to
    -- understand.
    MATH.xxx;
    STRING.xxx;
    TABLE.xxx;

    -- Here are some drawing functions you might need. I provided input parameters.
    -- should be self-explanatory by function name
    gc.setColor=function(r,g,b,a);
    gc.setLineWidth=function(w);
    gc.setFont=function(f);
    gc.line=function(...);
    gc.rectangle=function(mode,x,y,w,h);
    gc.circle=function(mode,x,y,r);
    gc.polygon=function(mode,x,y,r,sides,phase);
    gc.print=function(text,x,y,mode);

Other notes

  1. When drawing, the default window coordinates on PC is (0,0) on the top left, (1280, 720) on the bottom right.
    After stretching the window, this "standard rectangle" will be centered on the screen, with the size being the largest that can fit. There might be blank areas on the side, and those out-of-bound areas might be visible. In the future I might block off these areas so that it's easier to work with / avoid cheating
  2. If script has an error when initializing, there will be an error pop-up, and the scripts will be discarded (not ran).
  3. If script has an error during runtime, there will be an error pop-up, and an error count on the bottom right. To avoid error spam, there will be at most one pop-up per second (might cause some errors to not display; will change later)
Clone this wiki locally