Gorilla Tag Luau API Reference

This is a simplified, community-compiled documentation for Gorilla Tag custom map Luau scripting. All logic must be written in Luau and assigned via the Custom Gamemode TextAsset field in Unity.

🔄 Lifecycle Functions

function OnGameStart()

Called when the game session starts. Use it to initialize timers, player data, or GameObjects.

function OnGameStart()
  print("Game has started!")
end

function OnGameEnd()

Called when the game session ends. Great for cleanup or final scoring.

function OnGameEnd()
  print("Game over!")
end

function tick(dt)

Called every frame. Use this for time-based logic like hunger decay or cooldowns. Avoid expensive operations.

function tick(dt)
  timer = timer + dt
  if timer > 5 then
    print("5 seconds passed!")
    timer = 0
  end
end

🧍 Player Events

function OnPlayerJoin(player)

Triggered when a new player joins. Useful for sending welcome messages or initializing per-player data.

function OnPlayerJoin(player)
  player:SendMessage("Welcome, " .. player.name .. "!")
end

function OnPlayerTagged(victim, tagger)

Fired when a player is tagged. Can be used for scoring or special tag rules.

function OnPlayerTagged(victim, tagger)
  tagger:SendMessage("You tagged someone!")
end

🛰 Networking

emitEvent(tag: string, data: table)

Broadcasts a custom event to all clients. You can sync state or trigger reactions.

emitEvent("buttonPressed", { who = player.name })

function onEvent(tag, data)

Handles events emitted via emitEvent or triggered by map interactions.

function onEvent(tag, data)
  if tag == "buttonPressed" then
    print(data.who .. " pressed a button")
  end
end

🎮 Player Utilities

player:SendMessage(text: string)

Displays a message on the player's screen in VR.

player:SendMessage("You got a point!")

player.position

Returns the player’s current position as a Vector3. Useful for proximity-based logic.

if player.position.y > 10 then
  player:SendMessage("You climbed high!")
end

🧱 GameObject Control

findGameObject(name: string)

Returns a reference to a GameObject by name. You can then change its visibility or collision.

local obj = findGameObject("FloppaButton")
if obj then obj:setVisibility(false) end

gameObject:setVisibility(true/false)

Shows or hides the GameObject in the scene.

gameObject:setVisibility(true)

gameObject:setCollision(true/false)

Enables or disables collisions for that GameObject.

gameObject:setCollision(false)

🔊 Audio

playSound(index: number, position: Vector3, volume: number)

Plays a registered sound at a specific location in the map.

playSound(1, player.position, 1.0)

📟 Input Events

onEvent("touchedGameObject", {player, gameObject})

Triggered when a player touches a collider in the scene (usually buttons or zones).

function onEvent(tag, data)
  if tag == "touchedGameObject" then
    data.player:SendMessage("You touched " .. data.gameObject.name)
  end
end

💾 Saving and Loading Player Data

player:GetPersistentTable()

Retrieves a persistent table for storing player-specific data across sessions.

local data = player:GetPersistentTable()
data.coins = (data.coins or 0) + 10

player:GetPlayerID()

Returns a unique ID for the player, useful for tracking or saving data manually.

local id = player:GetPlayerID()
print("Player ID:", id)

player:SetPersistentTable(table)

Optionally used to overwrite the player's persistent data with a new table.

player:SetPersistentTable({ coins = 100, level = 2 })

🚫 Ban System Example

Ban players by their ID using a manual list

You can block players from joining or playing if their PlayerID matches a banned list.

local bannedIDs = {
  ["playerid123"] = true,
  ["playerid456"] = true
}

function OnPlayerJoin(player)
  local id = player:GetPlayerID()
  if bannedIDs[id] then
    return
  end
end

🎁 Special Item Unlocks

Give special items only to specific players

Lock a cosmetic, sound, or area behind a player ID.

local specialIDs = {
  ["devplayer001"] = true
}

function OnPlayerJoin(player)
  local id = player:GetPlayerID()
  local specialItem = findGameObject("GoldenBanana")
  if specialIDs[id] and specialItem then
    specialItem:setVisibility(true)
    specialItem:setCollision(true)
  else
    if specialItem then
      specialItem:setVisibility(false)
      specialItem:setCollision(false)
    end
  end
end

Gorilla Tag Custom Map Luau API (Simplified)