Getting Started

This page introduces the basics of Lua scripting on GTPS Cloud.
You will learn how to add scripts, reload them, and try a few simple examples.

Script Setup

Where Scripts Live

All Lua scripts must be uploaded through the Lua section in the server panel.
Once uploaded, they are automatically loaded by the server.

File Name Guidelines

Recommended	Avoid
hello.lua	hello world.lua
player-tools.lua	player@tools.lua
events_main.lua	events!.lua

TIP

Stick to lowercase names with _ or - to keep things consistent.

Your First Script

Create a file named hello.lua and add the following:

print("Hello script initialized")

onPlayerLoginCallback(function(player)
    player:onConsoleMessage(
        "`2Hello " .. player:getName() .. ", enjoy your time here!"
    )
end)

What Happens Here

• The server logs a message when the script loads
• Each player receives a message when they join

Reloading Scripts

After uploading or editing a script, reload Lua without restarting the server:

/rs

TIP

This command reloads all Lua scripts instantly and is safe to use during development.

Using Print for Debugging

You can inspect values directly in the server console:

print("Player joined:", #getOnlinePlayers())
print("Player gems:", player:getCoins())

WARNING

Printing too often inside repeating callbacks can slow down the server.

Adding a Simple Command

Below is an example of a basic command /bonus:

onPlayerCommandCallback(function(world, player, command)
    if command == "bonus" then
        player:addGems(250)
        player:onConsoleMessage("`250 gems added to your account!``")
        --- @return boolean     -- handle command
        return true
    end

    return false -- optionally you can avoid this
end)

Players can use it by typing:

/bonus

::: important If your script handles a command, always return true. :::

Simple Dialog Example

Dialogs are used to display UI menus.

Minimal Dialog Example

local function openMenu(player)
    local dialog = ""
    dialog = dialog .. "add_label|big|`wSimple Menu|left|\n"
    dialog = dialog .. "add_button|close|Close|noflags|0|0|\n"
    dialog = dialog .. "end_dialog|simple_menu|Close||\n"

    player:onDialogRequest(dialog)
end

More dialog elements can be found in: dialog-element

General Advice

TIP

• Reload scripts often while testing
• Keep scripts small and focused
• Comment code that may be reused later

WARNING

• Always check objects for nil
• Avoid heavy logic in frequently called callbacks
• Missing return values may cause unexpected behavior