Global scripts

-- Called once when the server process starts
xi.server.onServerStart = function()
    xi.events.handler.checkSeasonalEvents()
end

-- Called every Vana'diel midnight (JST)
xi.server.onJSTMidnight = function()
    xi.events.handler.checkSeasonalEvents()
end

-- Called every server tick (roughly every second)
xi.server.onTimeServerTick = function()
    xi.chocobo.onTimeServerTick()
end

-- Returns the login-screen server message for the given language
-- Used by SmallPacket0x04B
xi.server.getServerMessage = function(language)
    local serverMessage = ''
    if language == xi.language.ENGLISH then
        serverMessage = xi.settings.main.SERVER_MESSAGE
    end
    return serverMessage
end

xi.player.charCreate = function(player)
    -- Adds race-specific gear, job-specific starting weapon,
    -- nation map key item, job gesture key items, and nation ring.
end

-- Give one item
npcUtil.giveItem(player, xi.item.CHUNK_OF_COPPER_ORE)

-- Give multiple items
npcUtil.giveItem(player, { xi.item.CHUNK_OF_COPPER_ORE, xi.item.CHUNK_OF_TIN_ORE })

-- Give a specific quantity
npcUtil.giveItem(player, { { xi.item.CHUNK_OF_COPPER_ORE, 12 } })

-- Give with params (silent, fromTrade, multiple)
npcUtil.giveItem(player, items, { fromTrade = true })

npcUtil.giveKeyItem(player, xi.ki.ZERUHN_REPORT)
npcUtil.giveKeyItem(player, { xi.ki.BLUE_ACIDITY_TESTER, xi.ki.RED_ACIDITY_TESTER })

npcUtil.giveCurrency(player, 'gil', 500)
npcUtil.giveCurrency(player, 'bayld', 1000)

-- Returns true if the trade contains at least these items
npcUtil.tradeHas(trade, xi.item.CHUNK_OF_COPPER_ORE)
npcUtil.tradeHas(trade, { xi.item.CHUNK_OF_COPPER_ORE, xi.item.CHUNK_OF_TIN_ORE })
npcUtil.tradeHas(trade, { { xi.item.CHUNK_OF_COPPER_ORE, 2 }, { 'gil', 200 } })

-- Returns true only if the trade contains exactly these items
npcUtil.tradeHasExactly(trade, xi.item.CHUNK_OF_COPPER_ORE)

-- Returns true if only one item type is present (any quantity)
npcUtil.tradeHasOnly(trade, xi.item.CHUNK_OF_COPPER_ORE)

npcUtil.completeQuest(player, xi.questLog.SANDORIA, xi.quest.id.sandoria.ROSEL_THE_ARMORER, {
    item     = { { xi.item.CHUNK_OF_COPPER_ORE, 2 } },
    keyItem  = xi.ki.ZERUHN_REPORT,
    fameArea = xi.fameArea.BASTOK,
    fame     = 120,
    gil      = 200,
    exp      = 1000,
    title    = xi.title.ENTRANCE_DENIED,
})

npcUtil.completeMission(player, xi.questLog.SANDORIA, missionId, params)

npcUtil.popFromQM(player, qm, mobId, {
    radius = 5,   -- spawn randomly within 5 units of the QM
    claim  = true, -- auto-aggro the player
    hide   = 300,  -- hide QM for 300s after mob death
})

npcUtil.queueMove(npc, { x = 0, y = 0, z = 0 }, 3000) -- move after 3s delay
npcUtil.castingAnimation(npc, xi.magic.spellGroup.BLACK, 5, callback)
npcUtil.fishingAnimation(npc, 10, callback)

npcUtil.openCrate(crate, function() return false end) -- open and auto-disappear
npcUtil.showCrate(crate)
npcUtil.disappearCrate(crate)

-- General shop with optional fame-based discounts
-- stock format: { { itemId, basePrice }, ... }
xi.shop.general(player, {
    { xi.item.ANTIDOTE,            316 },
    { xi.item.FLASK_OF_ECHO_DROPS, 800 },
}, xi.fameArea.BASTOK)

-- Guild shop (requires guild skill ID)
xi.shop.generalGuild(player, stock, guildSkillId)

-- Nation shop (stock availability changes with conquest rank)
xi.shop.nation(player, stock, xi.nation.SANDORIA)

-- Outpost/standard stock shops
xi.shop.outpost(player)

-- Called from a chest/coffer NPC's onTrigger
-- (treasure.lua hooks this automatically via the NPC name pattern)

-- Called from the core for every mob death
xi.mob.onMobDeathEx = function(mob, player, isKiller, isWeaponSkillKill)
    -- extend for global death handling
end

-- Update a NM's spawn position from its lua-defined spawnPoints table
xi.mob.updateNMSpawnPoint(mobParam, spawnPointsOverride)

-- Called from a placeholder mob's onDespawn to potentially pop a lottery NM
xi.mob.phOnDespawn(ph, phNmId, chance, cooldown, params)

getCurePower(caster, isBlueMagic)   -- returns caster's cure potency value
getCureFinal(caster, spell, basecure, minCure, isBlueMagic) -- applies potency mods
isValidHealTarget(caster, target)    -- returns true if allegiance matches
applyResistanceAddEffect(actor, target, element, bonusMacc) -- resist rate for add-effects
finalMagicNonSpellAdjustments(caster, target, ele, dmg)     -- applies stoneskin/phalanx/etc