Events.txt

-- Events

-- BlockPlace

Parameters
player: Player | nil
Player placing the block (if placed by a player).
position: Vector3
Position in the world the block is being placed at.
blockType: ItemType
The type of the block being placed
cancelled: bool [modifiable]
If set to true, the block place will be denied.

-- Here is a script using this event:

-- Fortify all blocks placed by players to Stone Brick
Events.BlockPlace(function(event)
    -- Only fortify player blocks
    if (not event.player) then
        return
    end
    -- Only replace wool blocks
    if not string.includes(event.blockType, "wool") then
        return
    end
    
    
    BlockService.placeBlock(ItemType.STONE_BRICK, event.position)
    SoundService.playSound(Sound.FORTIFY_BLOCK, event.position)
    event.cancelled = true
end)

-- BlockBreak

Parameters
player: Player | nil
Player who broke the block.
position: Vector3
Position in the world the block was broken at.
blockType: ItemType
The type of the block being placed


-- Here is an example of a script using this event:

Events.BlockBreak(function(event)
    if (not event.player) then
        return
    end

    -- Only consider ceramic block breaks
    if (event.blockType == ItemType.BLASTPROOF_CERAMIC) then
        InventoryService.giveItem(event.player, ItemType.FIREBALL, 1, true)
    end
end)

-- BedAlarmTriggered

Parameters
intruder: Player
The intruder player that triggered the bed alarm.
team: Team
The team whose bed alarm went off.

-- Here is an example of a script that uses this event:

-- Send out a broadcast to the game server when a bed alarm is triggered
Events.BedAlarmTriggered(function(event)
    local alert = event.intruder.displayName .. " invaded " .. event.team.name .. "'s base!"
    MessageService.broadcast(alert)
end)

-- ConsumeItem

Parameters
player: Player
The player that consumed the item.
itemType: ItemType
The item that was consumed by the player.
cancelled: bool [modifiable]
If set to true the item consume will be cancelled.

-- Here is a script that uses this event:

-- Make a player jump twice as high every time they eat a pie item
Events.ConsumeItem(function(event)
    if (event.item == ItemType.PIE) then
        event.player:registerJumpHeightMultiplier("pie_jumps", 2)
    end
end)

-- Enchant

Parameters
player: Player
The player who researched the enchant.
enchant: EnchantType
Type of enchant researched by the player.
cancelled: bool [modifiable]
If set to true, the enchant research will be cancelled.

-- Here is a script that uses this event:

Events.Enchant(function(event)
    -- Play the Learn Fire sound if a player receives a Fire 3 Enchant
    if (event.enchant == EnchantType.FIRE_3) then
         SoundService.playSound(Sound.WHIM_LEARN_FIRE)
    end
end)

-- EntityDamage

Parameters
entity: Entity
The entity getting damaged.
fromEntity: Entity | nil
The attacker (if one exists).
damage: number [modifiable]
Amount of damage that will be dealt.
knockback: Knockback [modifiable]
Amount of knockback that will be applied.
cancelled: bool [modifiable]
If set to true the damage will be cancelled.

-- Here is a script using this event:

Events.EntityDamage(function(event)
    local matchDurationSec = MatchService.getMatchDurationSec()
    -- Double all damage in the game after 15 minutes
    if (matchDurationSec > 15 * 60) then
        event.damage = event.damage * 2
    end
    
    -- Disable damage in first 45s of the game
    if (matchDurationSec < 45) then
        event.cancelled = true;
    end
end)

-- EntityDeath

Parameters
entity: Entity
The killed entity.
killer: Entity | nil
The killer (or nil if not killed by anyone).
assists: Entity[]
List of entities who damaged the victim within the last 15s.
finalKill: bool
True if the killed entity is going to be eliminated after this kill.

-- Here is a script that uses this event:

-- Give players 10 emeralds when they eliminate another player
Events.EntityDeath(function(event)
    -- Only give payout if this is a player entity
    if (event.entity:getPlayer() == nil) then
        return
    end
    
    -- Only give payout if this is an elimination
    if not event.finalKill then
        return
    end

    -- Pay all assisting players 10 emeralds
    for i, entity in ipairs(event.assists) do
        if not entity:getPlayer() then
            continue
        end
        
        InventoryService.giveItem(entity:getPlayer(), ItemType.EMERALD, 10, true)
    end
end)

-- EntitySpawn

Parameters
entity: Entity
The spawning entity

-- Here is a script that uses this event:

-- Make all entities have only 1 health
Events.EntitySpawn(function(event)
    event.entity:setMaxHealth(1)
end)

-- Forged

Parameters
player: Player
The player who forged the upgrade.
upgrade: ForgeUpgrade
Type of upgrade researched by the player.
level: number
The level of upgrade forged by the player.

-- Here is a script that uses this event:

Events.Forged(function(event)
    if (event.upgrade == ForgeUpgrade.SCYTHE) then
        -- Give the player the Life Steal effect if they forge a Scythe upgrade
        StatusEffectService.giveEffect(event.player:getEntity(), StatusEffect.LIFE_STEAL_3)
        -- Give the player a Sky Scythe item if they don't already have one
        local currentAmount = InventoryService.getAmount(event.player, ItemType.SKY_SCYTHE)
        if (currentAmount == 0) then
            InventoryService.giveItem(event.player, ItemType.SKY_SCYTHE, 1, false)
        end
    end
end)

-- InventoryItemAdded

Parameters
player: Player
The player who received a new item.
item: ItemType
The type of item received by the player.
amount: number
The amount of the item received by the player.

-- Here is a script using this event:

Events.InventoryItemAdded(function(event)
    -- Sends a notification to a player that receives the Laser Sword item
    if (event.item == ItemType.LASER_SWORD) then
        MessageService.sendInfo(event.player, "You have unlocked the power of the force!")
    end
end)

-- ItemPurchase

Parameters
player: Player
The player who received a new item.
itemType: ItemType
The type of item received by the player.
amount: number
The amount of the item received by the player.
costItem: ItemType
The type of item used to purchase the specified item.
price: number
 The amount of the cost item used to purchase the specified item.

-- Here is a script using this event:

-- Refund 50% of all Iron purchases in the shop
Events.ItemPurchase(function(event)
    -- Only refund the player if the resource used to purchase the item is Iron
    if (event.costItem == ItemType.IRON) then
        -- Round 50% of the price to the closest smaller integer
        local refund = math.floor(event.price * 0.5);
        InventoryService.giveItem(event.player, ItemType.IRON, refund, true)
    end
end)

-- MatchStart

-- Here is an example of a script that uses this event:

-- Play halloween music at the start of the game
Events.MatchStart(function(event)
    SoundService.playSound(Sound.HALLOWEEN_2022_BOSS_MUSIC)
end)

-- PlayerChatted

Parameters
player: Player
The player that sent the message
message: string
The message sent by the player


-- Here is a script that uses this event:


-- Add "/rain {item}" command that rains a resource on all players
Events.PlayerChatted(function(event)
    -- Split out command from args
    local commandArgs = string.split(event.message, " ")
    
    local command = string.lower(commandArgs[1])
    
    -- Check that command is "/rain"
    if string.lower(command) ~= "/rain" then
        return
    end
    
    -- Verify message at least has 2 arguments (command & item type)
    if #commandArgs < 2 then
        MessageService.sendInfo(event.player, 'Format: /rain <Item Type>')
        return
    end
    local itemType = string.lower(commandArgs[2])
    
    -- Check that item exists
    if not ItemType[itemType] then
        MessageService.sendInfo(event.player, 'No item exists named ' .. itemType)
        return
    end
    
    local numDrops = 25
    task.spawn(function()
        for i=1,numDrops,1 do
            for i,player in ipairs(PlayerService.getPlayers()) do
                local entity = player:getEntity()
                if not entity then
                    continue
                end
                
                local pos = entity:getPosition()
                pos = pos + Vector3.new(math.random(-5, 5), 8, math.random(-5, 5))
                ItemService.dropItem(itemType, pos)
            end
            task.wait(0.2)
        end
    end)
end)

-- PlayerAdded

Parameters
player: Player
The player that joined the game server.

-- Here is a script that uses this event:

Events.PlayerAdded(function (event)
    ChatService.sendMessage(event.player.name .. " joined the game!")
end)

Events.PlayerRemoving(function (event)
    ChatService.sendMessage(event.player.name .. " left the game.")
end)

-- PlayerRemoving

Parameters
player: Player
The player that is about to leave the game server.

-- Here is a script that uses this event:


Events.PlayerAdded(function (event)
    ChatService.sendMessage(event.player.displayName .. " joined the game!")
end)

Events.PlayerRemoving(function (event)
    ChatService.sendMessage(event.player.displayName .. " left the game.")
end)

-- PlayerDropItem

Parameters
player: Player
The player that is dropping the item.
itemType: ItemType
The type of item being dropped by the player.
amount: number
The amount of the item being dropped by the player.
cancelled: bool [modifiable]
If set to true, the item drop event will be cancelled.

-- Here is a script that uses this event:

Events.PlayerDropItem(function(event)
    if (event.itemType == ItemType.TENNIS_BALL) then
        event.cancelled = true
        MessageService.sendInfo(event.player, "Be more careful! Those can explode!")
    end
end)

-- PlayerPickupItem

Parameters
player: Player
The player that is picking up the item.
itemType: ItemType
The type of item that is being picked up by the player.
amount: number
The amount of the item that is being picked up by the player.
cancelled: bool [modifiable]
If set to true, the item pickup event will be cancelled.

-- Here is a script that uses this event:

Events.PlayerPickupItem(function(event)
    if (event.player:getEntity() == nil) then
        return
    end
    if (event.itemType == ItemType.GLITCH_TRUMPET) then
        EntityService.spawnKitEntity(KitType.MELODY, event.player:getEntity():getPosition())
        AnnouncementService.sendAnnouncement("Let's jam!")
    end
end)