Star Force

The core.starforce module drives the Auto Star Force state machine that lives 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.

TIP

Star Force runs on the equipped or inventory item at the configured slot. Negative slot numbers refer to equipped items (e.g. -11 = weapon); positive numbers refer to Equip Tab slot 1 → N in the inventory.

Insufficient meso protection

The state machine refuses to send a catch packet if the player can't cover the next attempt's cost — sending one without enough mesos disconnects the client. get_status().result.status will report "insufficient_meso" when this happens and the run will stop on its own.

Functions

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

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:

Field	Type	Description
slot	number	Equipment slot. Negative = equipped (e.g. -11 = weapon), positive = Equip inventory slot.
target	number	Stop at this star level (1-30).
safeguard	boolean	Use safeguard for 15→16, 16→17, 17→18 attempts (adds a non-discounted 2× base surcharge).
sunny_sunday	boolean	Apply the 30% Sunny Sunday discount.
mvp_tier	string | number	"none", "silver", "gold", "diamond" (or 0-3). Discount only applies up to 17 stars.

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

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

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

---

core.starforce.get_status() -> table

Returns a snapshot of the current run.

Field	Type	Description
running	boolean	Whether the Auto SF toggle is on.
state	string	State machine state: "idle", "waiting_catch", "waiting_result", "next_item", "done".
slot	number	Slot the run is targeting.
current_stars	number	Last-observed star count of the target item.
target_stars	number	Configured target.
attempts	number	Catch packets sent in this run.
spent	number	Total mesos billed in this run.
result	table	Live status object — see fields below.

result fields (mirrors what the web UI consumes; not every field is present in every state):

Field	Type	Description
status	string	"enhancing", "done", "item_not_found", "item_boomed", "insufficient_meso", or "timeout".
stars	number	Star count at the time of the status update.
attempts	number	Run attempt count.
spent	number	Run mesos spent.
lastCost	number?	Cost of the most recent attempt.
nextCost	number?	Cost of the next attempt (only on insufficient_meso).
currentMeso	number?	Player's meso pool (only on insufficient_meso).

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))

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

---

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

Returns the meso cost of one attempt at current_star stars on an item of the given required level. Uses the GMS formula with discounts and safeguard surcharge applied.

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

opts fields:

Field	Type	Description
safeguard	boolean	Override safeguard.
sunny_sunday	boolean	Override Sunny Sunday.
mvp_tier	string | number	Override MVP tier (same encoding as start()).

-- 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")

Example: stop on boom or low mesos

plugin = {
    name        = "SF Watchdog",
    version     = "1.0.0",
    author      = "you",
    description = "Logs SF progress and stops on boom",
    load        = true,
}

local last_attempts = 0

function on_tick()
    local s = core.starforce.get_status()
    if not s.running then return end

    if 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

    local r = s.result
    if r and (r.status == "item_boomed" or r.status == "insufficient_meso") then
        core.log_error("SF stopped: " .. tostring(r.status))
        core.starforce.stop()
    end
end