Inventory

Provides access to inventory items and slot information. For item usage, see Input.

#Item Object Structure

All item-returning functions provide objects with the following properties:

#Inventory Tabs

#Functions

#Slot Management

#core.inventory.get_total_slots(tab_id: number) -> number

Available on GMS and CWGMSCW

Returns total slots in the specified tab.

#core.inventory.get_free_slots(tab_id: number) -> number

Available on GMS and CWGMSCW

Returns free slots in the specified tab.

local free_slots = core.inventory.get_free_slots(2) -- Use tab
if free_slots < 5 then
    core.log_warning("Low inventory space!")
end

#Item Queries

#core.inventory.has_item(item_id: number) -> boolean

Available on GMS and CWGMSCW

Returns true if the item exists in any inventory tab.

#Retrieving Items

#core.inventory.get_all_items() -> table<item>

Available on GMS and CWGMSCW

Returns all items across all tabs. Equip items include potentials and star count fields.

#core.inventory.get_equip_items() -> table<item>

Available on GMS and CWGMSCW

Returns all unequipped equip items in your inventory (tab_id=1) including potentials and star count fields. These are equips sitting in your bag, not currently worn.

#core.inventory.get_equipped_items() -> table<item>

Available on GMS and CWGMSCW

Returns all items currently worn by the character. These have negative position values representing equipment slots (e.g. -1 = hat, -5 = top, -7 = shoes, etc.). Includes potentials and star count fields.

local equipped = core.inventory.get_equipped_items()
for _, item in ipairs(equipped) do
    core.log(string.format("Slot %d: %s [%d★]",
        item.position, item.name, item.current_star_count))
end

#core.inventory.get_use_items() -> table<item>

Available on GMS and CWGMSCW

Returns all use items (tab_id=2).

#core.inventory.get_etc_items() -> table<item>

Available on GMS and CWGMSCW

Returns all etc items (tab_id=4).

#core.inventory.get_setup_items() -> table<item>

Available on GMS and CWGMSCW

Returns all setup items (tab_id=3).

#core.inventory.get_cash_items() -> table<item>

Available on GMS and CWGMSCW

Returns all cash items (tab_id=5).

#core.inventory.get_required_level(item_id: number) -> number | nil

Available on GMS and CWGMSCW

Returns the required level to equip/use the specified item. Returns nil if item info is unavailable.

local level = core.inventory.get_required_level(1002140)
core.log("Required level: " .. tostring(level))

#core.inventory.can_equip(item_id: number) -> boolean | nil

Available on GMS and CWGMSCW

Returns true if the current character meets all requirements to equip/use the specified item (level, job, stats, etc.). Returns nil if item info or character context is unavailable.

if core.inventory.can_equip(1302000) then
    core.input.use_item(1302000)
end

#core.inventory.get_item_combat_power(tab_id: number, position: number) -> number | nil

Available on GMS and CWGMSCW

Returns the estimated combat power change from equipping the item at position in the specified inventory tab. Positive values indicate the item is stronger than the currently equipped item for that slot, negative values indicate it is weaker, and nil is returned if the item or character context is unavailable.

local delta = core.inventory.get_item_combat_power(1, 5)
if delta and delta > 0 then
    core.log("Upgrade found: +" .. delta)
end

#Equipping gear

#core.inventory.equip(position: number) -> boolean, string?

Available on CWCW

Sends a request to wear the Equip-tab item at position in an automatically selected body slot. true means sent, not equipped; check get_equipped_items() on later ticks. Returns false and an error on refusal. position is a signed 32-bit integer identifying an occupied Equip-tab slot.

No confirmation is requested for an item becoming untradeable. Item-specific restrictions can still prevent the change; do not assume a sent request succeeded. Close any shop or other dialog first.

Refusals are checked in this order: scrolling_busy (scrolling owns inventory), no_item (invalid integer), unavailable (equipment support or character/item data unavailable), no_item (invalid or empty position), not_equip (not equipment or no suitable body slot), requirements (level, stats or job requirements unmet), blocked_map (equipment changes forbidden or stats forced), busy (dialog open), conflict (conflicting equipment no longer present), inventory_full (no Equip-tab space for conflicting gear), then the shared move checks below.

#core.inventory.unequip(body_slot: number) -> boolean, string?

Available on CWCW

Sends a request to move worn gear to the first empty Equip-tab slot. body_slot is the negative position returned by get_equipped_items(), from -32768 through -1. true means sent, not unequipped; re-read get_equipped_items() on later ticks. Returns false and an error on refusal.

Refusals are checked in this order: scrolling_busy, no_item (not a signed 32-bit integer), unavailable (equipment support or character/item data unavailable), no_item (not a negative body slot in range, or nothing worn there), blocked_map, busy (dialog open), inventory_full, then the shared move checks.

Shared move checks, in order: busy while crafting; unavailable when a move involving weapon slot -11 cannot read the Soul gauge; soul_gauge when that gauge is above zero; busy while another request is pending or equipment movement is held back (including a 500 ms interval, death, a chair or a mount). Neither function waits for server confirmation. Check API availability before using these additions on an older core or another game.

#Item Movement

#core.inventory.change_slot_position(tab_id: number, old_pos: number, new_pos: number, count?: number)

Available on GMS and CWGMSCW

Sends a request to move an item from one slot position to another within the same inventory tab. Can also be used to equip items by moving them to equipped slots (negative positions).

-- Equip an item from equip tab slot 5 to hat slot (-1)
core.inventory.change_slot_position(1, 5, -1)

-- Move a use item from slot 3 to slot 10
core.inventory.change_slot_position(2, 3, 10)

-- Drop 100 etc items from slot 2
core.inventory.change_slot_position(4, 2, 0, 100)

#Star Force

#core.inventory.starforce_start(equip_slot: number, target_stars: number, use_safeguard?: boolean) -> boolean

Available on GMSGMS

Configures and starts an Auto Star Force run on the given equipment slot.

Returns: true on success, false if the Autos module isn't ready.

#core.inventory.starforce_stop() -> boolean

Available on GMSGMS

Stops the Auto Star Force run (clears the Enable Auto SF toggle and resets state to idle). Safe to call when not running.

Returns: true (a no-op when the Autos module isn't loaded).

#Examples

#Basic Item Check

-- Check if player has red potions
local RED_POTION = 2000000

if core.inventory.has_item(RED_POTION) then
    local free_slots = core.inventory.get_free_slots(2)
    core.log("Red potions found. Free use slots: " .. free_slots)
else
    core.log_warning("Out of red potions!")
end

#Working with Equipment Potentials

-- Find all equipment with potentials
local equips = core.inventory.get_equip_items()

for _, item in ipairs(equips) do
    if item.potentials and #item.potentials > 0 then
        core.log(item.name .. " [" .. item.current_star_count .. "★]")

        for i, potential in ipairs(item.potentials) do
            core.log("  Line " .. i .. ": " .. potential)
        end
    end
end

#Selling and Equip Slots

-- List Etc items a shop will buy, and where each bag equip can be worn
for _, item in ipairs(core.inventory.get_etc_items()) do
    if item.is_sellable then
        core.log("Sellable: " .. item.name .. " x" .. item.count)
    end
end

for _, item in ipairs(core.inventory.get_equip_items()) do
    if #item.equip_slots > 0 then
        core.log(item.name .. " fits: " .. table.concat(item.equip_slots, ", "))
    end
end

#Inventory Space Monitor

-- Monitor inventory space across all tabs
local function check_inventory_space()
    local tabs = {
        {id = 1, name = "Equip"},
        {id = 2, name = "Use"},
        {id = 3, name = "Etc"},
        {id = 4, name = "Setup"},
        {id = 5, name = "Cash"}
    }

    for _, tab in ipairs(tabs) do
        local total = core.inventory.get_total_slots(tab.id)
        local free = core.inventory.get_free_slots(tab.id)
        local used = total - free
        local percent = math.floor((used / total) * 100)

        local status = percent > 80 and "[!]" or "[OK]"
        core.log(string.format("%s %s: %d/%d (%d%%)",
            status, tab.name, used, total, percent))
    end
end