Skip to main content
Version: bleeding-edge ๐Ÿฉธ

๐Ÿช™ Tebex

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

๐Ÿ—ฟStatic ClassServer Only๐Ÿง‘โ€๐Ÿ’ปAPI Source

๐Ÿ’ก 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-started

Initializationโ€‹

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.

caution

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.

tip

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:

Server/Index.lua
-- 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:

Server/Index.lua
-- 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โ€‹

Server/Index.lua
-- 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โ€‹

ReturnsNameDescription
OpenCheckoutOverlayOpens the Tebex checkout of a package for a player, over the in-game menu
functionSubscribeSubscribes to an Event
UnsubscribeUnsubscribes 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

TypeParameterDefaultDescription
Playerplayer Required parameter The player who will buy the package
integerpackage_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

TypeParameterDefaultDescription
stringevent_name Required parameter Event to subscribe to
functioncallback Required parameter Callback to run on the event occurring

Returns

TypeDescription
functionThe 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

TypeParameterDefaultDescription
stringevent_name Required parameter Event to unsubscribe to
functioncallback?nil
Optional callback to specifically unsubscribe to

๐Ÿš€ Eventsโ€‹

NameDescription
OfflineCommandCalled when an offline command of a purchase is about to run
OnlineCommandCalled 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 in command.

Return false to handle the purchase in your script instead of running command in the server console. A handled command is removed from the Tebex queue. If you don't return false and no Package handles command in 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

TypeArgumentDescription
integercommand_idThe ID of this command in the Tebex queue
integerpackage_idThe ID of the package bought
integerpayment_idThe ID of the payment
stringcommandThe command configured in the Tebex package, with its placeholders replaced
stringtebex_player_idThe internal Tebex ID of the player
stringplayer_nameThe name of the player
stringplayer_steam_idThe 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 in command.

Return false to handle the purchase in your script instead of running command in the server console. A handled command is removed from the Tebex queue. If you don't return false and no Package handles command in 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

TypeArgumentDescription
integercommand_idThe ID of this command in the Tebex queue
integerpackage_idThe ID of the package bought
integerpayment_idThe ID of the payment
stringcommandThe command configured in the Tebex package, with its placeholders replaced
PlayerplayerThe player who receives the purchase