Star Force

The core.starforce module controls Auto Star Force, the feature under the Autos → Auto Starforce panel. It writes through the same settings the web UI exposes, so changes show up in the menu and persist across sessions.

#How a run works

• Server price and odds. Before every attempt, the run asks the server for that attempt's price and odds and uses the server's price for the meso check. The quoted terms are available as get_status().result.quote. If the server doesn't answer the price check, the rest of that run uses estimated prices, including for the meso check: costSource is "estimate" and there is no quote. The MVP and Sunny Sunday settings only affect estimates (estimate_cost(), the panel's cost preview, and a run that is using estimated prices).
• In-game enhancement window. While the in-game equipment enhancement window is open, the run pauses (status = "paused", reason = "native_ui_open") and resumes on its own once the window is closed.
• Enhancement mode (0-3 = Level 1-Level 4) only applies to 15-21 star attempts, and Level 4 is only available from 18 stars. A level that isn't available for the item at its current star count is lowered to the highest one that is; items that can't use enhancement mode (such as Superior equipment) always use Level 1. It is ignored while safeguard applies.
• Safeguard only applies to 15-17 star attempts, and only when the attempt can destroy the item. Other attempts are made without it and without its extra cost. While a run is using estimated prices, safeguard is requested, and its cost counted, on every 15-17 star attempt the item allows it on.
• Equipped items need one free Equip inventory slot on attempts that can destroy them. If there is none, the run stops with "equip_tab_full".

#Functions

#core.starforce.start([opts: table]) -> boolean, string?

Available on GMSGMS

Configures and starts an Auto Star Force run. All opts fields are optional — anything you omit keeps its current setting. The slot must be non-zero (either passed in opts or already configured) or start() returns false with an error message.

opts fields:

Returns: true on success, or false, "<error message>" if the slot isn't set or the autos module isn't ready.

-- Tap the trigger using existing settings
core.starforce.start()

-- Configure everything in one shot
local ok, err = core.starforce.start({
    slot         = -11,        -- weapon
    target       = 17,
    safeguard    = true,
    mvp_tier     = "gold",
    sunny_sunday = false,
})
if not ok then core.log_error(err) end

#core.starforce.stop() -> boolean

Available on GMSGMS

Disables Auto Star Force. Returns true if the toggle was flipped, false if the autos module isn't loaded. Safe to call when not running.

#core.starforce.is_running() -> boolean

Available on GMSGMS

Convenience wrapper for "is the Enable Auto SF checkbox on right now?". Returns true while a run is active.

#core.starforce.get_status() -> table

Available on GMSGMS

Returns a snapshot of the current run.

result fields (status, stars, attempts and spent are always present; the others depend on the status):

result.status values:

"stops" means the Auto SF toggle is turned off.

result.quote fields:

local s = core.starforce.get_status()
core.log(string.format("[%s] %d★ → %d★  (%d attempts, %d mesos)",
    s.state, s.current_stars, s.target_stars or 0, s.attempts, s.spent))

local r = s.result
if r and r.quote then
    core.log(string.format("Next: %d mesos, %.1f%% success, %.2f%% destroy",
        r.quote.cost, r.quote.successPct, r.quote.destroyPct))
end

if r and r.status == "item_boomed" then
    core.log_error("Item went boom!")
end

#core.starforce.estimate_cost(item_level: number, current_star: number [, opts: table]) -> number

Available on GMSGMS

Returns the estimated meso cost of one attempt at current_star stars on an item of the given required level. Uses the GMS formula with discounts, safeguard surcharge and enhancement mode applied; the base price is rounded to the nearest 100 mesos before they are applied. The server's price can differ; a run uses the server's price unless the server didn't answer its first price check.

If opts is omitted, the live settings (safeguard, sunny_sunday, mvp_tier, enhancement mode) are used — handy for asking "what would the next click cost right now?".

opts fields:

-- Cost of going 16 → 17 on a level-150 weapon with safeguard + Gold MVP
local cost = core.starforce.estimate_cost(150, 16, {
    safeguard = true,
    mvp_tier  = "gold",
})
core.log("Next attempt: " .. tostring(cost) .. " mesos")

-- Cost of going 18 → 19 at Level 4
local lv4 = core.starforce.estimate_cost(200, 18, { enhance_mode = 3 })

#Example: log progress and report why a run stopped

plugin = {
    name        = "SF Watchdog",
    version     = "1.0.0",
    author      = "you",
    description = "Logs SF progress and reports why a run stopped",
    load        = true,
}

local last_attempts = 0
local was_running = false

function on_tick()
    local s = core.starforce.get_status()

    if s.running and s.attempts ~= last_attempts then
        last_attempts = s.attempts
        core.log(string.format("Attempt %d  ★%d  spent=%d",
            s.attempts, s.current_stars, s.spent))
    end

    -- Stopping statuses turn the toggle off, so look for the on -> off edge
    if was_running and not s.running then
        local r = s.result or {}
        if r.status == "insufficient_meso" then
            core.log_error(string.format("SF stopped: next attempt costs %d, you have %d",
                r.nextCost or 0, r.currentMeso or 0))
        elseif r.status == "item_boomed" then
            core.log_error("SF stopped: the item was destroyed")
        else
            core.log("SF stopped: " .. tostring(r.status))
        end
        last_attempts = 0
    end
    was_running = s.running
end