๐ช Tebex
Sell packages from your Tebex store in game and deliver them to your players.

๐ก About Tebexโ
Tebex is a monetization platform that lets players buy in-game packages (ranks, items, currency, etc.) from your store. nanos world supports it natively: players browse your store in the in-game menu, pay on Tebex's checkout, and your server delivers what they bought.
This page covers the technical side. For why to use Tebex, the fees, the rules of what you can sell and your responsibilities as a seller, see Monetization.
Getting a Secret Keyโ
First click Create Project in your Tebex Creator Panel, select I operate a game server and pick nanos world from the list of games. Then open the Game Servers page and click Edit (or Instructions) to reveal your Game Server Secret Key.
Keep this key private: anyone holding it can manage your store.
For more information, see the Tebex Quick Start Guide:
Tebex Quick Start Guidehttps://docs.tebex.io/developers/getting-startedInitializationโ
Set your secret key in the tebex_secret setting of your Config.toml, or start the server with --tebex_secret <your_secret_key>. No other setup is required.
On start the server connects to Tebex, logs Tebex initialized successfully! and starts delivering purchases. Players also get your store in the in-game menu.
Delivering Purchasesโ
When a payment is confirmed, Tebex queues the commands you configured in the package. The server fetches them at the interval Tebex asks for (around every minute):
- Online commands only run while the player is on the server. If they are offline, the commands wait for their next visit.
- Offline commands run as soon as they are fetched, whether or not the player is online.
- A command with a delay runs that many seconds after it is fetched. If the server restarts before it runs, it is fetched again.
Before a command runs, these placeholders are replaced: {id} and {steamid} by the player's Steam ID, {username} and {name} by the player's name.
By default each command runs as a server console command of your Packages: the ones registered with Console.RegisterCommand(), or handled in the PlayerSubmit (Console) event (return false there to mark it as handled). The built-in server commands (e.g. kick, stop) can't be called by a Tebex command. To deliver the purchase from your scripts instead, subscribe to OnlineCommand (Tebex) or OfflineCommand (Tebex) and return false.
Once a command is handled it is removed from the Tebex queue, so it is not delivered again. A command that no Package handled (no registered command matched it and no event returned false) stays in the queue and is tried again on the next fetch, with an error in the server log. This way a purchase made while your Package was not loaded, or with a typo in the command, is delivered as soon as you fix it.
Identify the player with {steamid}, never with {name} or {username}. A player picks their own name, and a name with spaces becomes extra arguments of your command.
When delivering with events, avoid hardcoding package IDs in your scripts. Read the command parameter instead (e.g. vip 30d or coins 1000), so a new package only needs a change in the Tebex panel.
Opening the Checkoutโ
Players can buy from your store in the in-game menu. You can also start the purchase of a specific package from your scripts (an NPC shop, a chat command, your own UI) with Tebex.OpenCheckoutOverlay(): the player's in-game menu opens with the checkout of that package, the same one the store shows, with a link to finish the payment in their browser. The player decides whether to pay.
๐ Examplesโ
Using Console Commandsโ
Register a console command in your package, then use it as the package command in the Tebex panel, for example giveitem {steamid} vip_rank:
-- Online commands only run while the player is connected, so the player is found
Console.RegisterCommand("giveitem", function(steam_id, item)
local player = Player.GetBySteamID(steam_id)
if (player) then
GivePlayerItem(player, item)
end
end, "Grants an item to a player", { "steam_id", "item" })
Implementing your own Delivery Logicโ
Without any console command, subscribe to the events and return false:
-- Online commands: the player is connected
Tebex.Subscribe("OnlineCommand", function(command_id, package_id, payment_id, command, player)
-- A special package handled here
if (package_id == 123456) then
player:SetValue("vip", true, true)
Chat.BroadcastMessage(player:GetName() .. " is now VIP, thank you!")
-- Prevents the command from running in the console
return false
end
end)
-- Offline commands: the player may not be connected
Tebex.Subscribe("OfflineCommand", function(command_id, package_id, payment_id, command, tebex_player_id, player_name, player_steam_id)
UpdatePlayerDatabase(player_steam_id, package_id)
-- Prevents the command from running in the console
return false
end)
Selling from a Chat Commandโ
-- Opens the checkout of the package 123456 when the player types /vip
Chat.Subscribe("PlayerSubmit", function(message, player)
if (message == "/vip") then
Tebex.OpenCheckoutOverlay(player, 123456)
return false
end
end)
๐ฟ Static Functionsโ
| Returns | Name | Description | |
|---|---|---|---|
OpenCheckoutOverlay | Opens the Tebex checkout of a package for a player, over the in-game menu | ||
| function | Subscribe | Subscribes to an Event | |
Unsubscribe | Unsubscribes from all subscribed Events in this Class and in this Package, optionally passing the function to unsubscribe only that callback |
Optimal

OpenCheckoutOverlayโ
Opens the Tebex checkout of a package for a player, over the in-game menu.
The server creates a basket with the package for the player's Steam ID, so the purchase is linked to that player without any login. Once Tebex answers, the player's in-game menu opens with the checkout popup, the same one the in-game store shows, and the player decides whether to pay.
Tebex.OpenCheckoutOverlay(player, package_id)
Parameters
| Type | Parameter | Default | Description |
|---|---|---|---|
| Player | player | Required parameter | The player who will buy the package |
| integer | package_id | Required parameter | The ID of the package in your Tebex store |
Optimal

Subscribeโ
Subscribes to an Event
local ret = Tebex.Subscribe(event_name, callback)
Parameters
| Type | Parameter | Default | Description |
|---|---|---|---|
| string | event_name | Required parameter | Event to subscribe to |
| function | callback | Required parameter | Callback to run on the event occurring |
Returns
| Type | Description |
|---|---|
| function | The function callback |
Optimal

Unsubscribeโ
Unsubscribes from all subscribed Events in this Class and in this Package, optionally passing the function to unsubscribe only that callback
Tebex.Unsubscribe(event_name, callback?)
Parameters
| Type | Parameter | Default | Description |
|---|---|---|---|
| string | event_name | Required parameter | Event to unsubscribe to |
| function | callback? | nil | Optional callback to specifically unsubscribe to |
๐ Eventsโ
| Name | Description | |
|---|---|---|
OfflineCommand | Called when an offline command of a purchase is about to run | |
OnlineCommand | Called when an online command of a purchase is about to run for a connected player |

OfflineCommandโ
Called when an offline command of a purchase is about to run.
Offline commands run whether or not their player is on the server, so the player is given by their Steam ID and name. The{id},{steamid},{username}and{name}placeholders are already replaced incommand.
Returnfalseto handle the purchase in your script instead of runningcommandin the server console. A handled command is removed from the Tebex queue. If you don't returnfalseand no Package handlescommandin the console, it stays in the queue and this event is called again on the next fetch.
Return false to prevent the command from running in the server console
Tebex.Subscribe("OfflineCommand", function(command_id, package_id, payment_id, command, tebex_player_id, player_name, player_steam_id)
-- OfflineCommand was called
return true
end)
Arguments
| Type | Argument | Description |
|---|---|---|
| integer | command_id | The ID of this command in the Tebex queue |
| integer | package_id | The ID of the package bought |
| integer | payment_id | The ID of the payment |
| string | command | The command configured in the Tebex package, with its placeholders replaced |
| string | tebex_player_id | The internal Tebex ID of the player |
| string | player_name | The name of the player |
| string | player_steam_id | The Steam ID of the player |

OnlineCommandโ
Called when an online command of a purchase is about to run for a connected player.
Online commands only run while their player is on the server. The{id},{steamid},{username}and{name}placeholders are already replaced incommand.
Returnfalseto handle the purchase in your script instead of runningcommandin the server console. A handled command is removed from the Tebex queue. If you don't returnfalseand no Package handlescommandin the console, it stays in the queue and this event is called again on the next fetch.
Return false to prevent the command from running in the server console
Tebex.Subscribe("OnlineCommand", function(command_id, package_id, payment_id, command, player)
-- OnlineCommand was called
return true
end)
Arguments
| Type | Argument | Description |
|---|---|---|
| integer | command_id | The ID of this command in the Tebex queue |
| integer | package_id | The ID of the package bought |
| integer | payment_id | The ID of the payment |
| string | command | The command configured in the Tebex package, with its placeholders replaced |
| Player | player | The player who receives the purchase |
