Points tutorial

(Redirected from Points Tutorial)

Points are an award system in ROBLOX to showcase player achievements and participation. Each game will have an individual leaderboard which ranks players based on the amount of points they have earnt within that game.

Every game has an unlimited amount of player points that it can distribute and the game's developer has full discretion on how to award points to their players. This means that points can be awarded for playing for a certain amount of time, for reaching milestones in the game, winning tournaments, or anything else the developer feels is appropriate.

How to Use[edit]

Awarding Points[edit]

Points can be awarded to a specific player with the AwardPoints function. This function requires the userId of the player, as well as the number of points to award. Developers can award an unlimited amount of player points to their users.

Warning: Trying to award player points to guests will result in an error.

Key API[edit]

Functions[edit]

AwardPoints[edit]

Attempts to award points to a player. If successful it will return the updated point totals of the player. Also, if successful, this function will fire the PointsAwarded event. This function will only work in a server script.
Parameters

  • int userId - The userId of the player to award points to.
  • int amount - The number of points to award to the player.

Returns

  • tuple - This function returns the userId the points were awarded to, the new point total the user has in the game, and the total number of points the user now has.

GetGamePointBalance[edit]

Returns the total number of points a player has in the current game. Works with server scripts ONLY.
Parameters

  • int userId - The userId of the player.

Returns

  • int - The total number of points the player has earned in all places in the game.

GetPointBalance[edit]

Returns the total number of points the player has across all games. Works with server scripts ONLY.
Parameters

  • int userId - The userId of the player.

Returns

  • int - The total number of points the player has earned in all games.

Events[edit]

PointsAwarded[edit]

Fires when points are successfully awarded to a player. This event passes the updated balance of points the player has in the game and overall. This event fires both on the server and on all clients in the game that awarded the points (so it can be handled both in local and server scripts).
Parameters

  • int userId - The userId of the player who received points.
  • int userBalanceInGame - The total number of points the player has earned in the game.
  • int userTotalBalance - The total number of points the player has earned across all games.

Example Code[edit]

This sample will give a point to a player when he or she joins the game. The point will only be awarded if the game has points to give and if the player has not gotten any points in the game yet.

Select
-- declare service
local PointsService = Game:GetService("PointsService")
 
-- Bind function to player added event
game.Players.PlayerAdded:connect(function(player)
	-- Get total number of points this game has already awarded to the player
	local universeBalance = PointsService:GetGamePointBalance(player.userId)
	-- Check if the player hasn't gotten any points yet. If true, award the points.
	if ( universeBalance == 0) then
		PointsService:AwardPoints(player.userId, 1)
	end
end)
 
-- Bind function to when points are successfully awarded
PointsService.PointsAwarded:connect(function(userId, userBalanceinUni, userBalance)
	-- Show message indicating that a player has gotten points
	local message = Instance.new('Message')
	message.Text = "Point awarded to " .. userId .. ". This player now has " .. userBalance .. " points total!"
	message.Parent = workspace
	wait(5)
	message:Destroy()
end)

Restrictions[edit]

To ensure security the Points service will not be available in games where loadstrings are enabled in server scripts. By default games start with loadstrings disabled, so do not enable them if you want to use the Points service. For more regarding loadstrings and security, see Security#LoadStringEnabled.


Practice[edit]

Exercise

Instructions

Make a script that awards 5 points to every person who gets a kill with a specific weapon.

Solution
Select
--Add this to your weapon script and call it when a player is killed
local PointsService = game:GetService("PointsService")
 
function awardPoints(creator)
	if time() - lastAwardedTime < 5 then 
            return
	else
		lastAwardedTime = time()
		PointsService:AwardPoints(creator.Value, 1)
	end
end