mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-23 22:11:38 +00:00
1594 lines
54 KiB
YAML
1594 lines
54 KiB
YAML
# This file is automatically generated. Please don't edit it manually.
|
|
# To submit a bug report on the content, see
|
|
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
|
|
|
|
name: Players
|
|
type: class
|
|
memory_category: Instances
|
|
summary: |
|
|
A service that contains presently connected `Class.Player` objects.
|
|
description: |
|
|
The `Class.Players` service contains `Class.Player` objects for presently
|
|
connected clients to a Roblox server. It also contains information about a
|
|
place's configuration. It can fetch information about players not connected to
|
|
the server, such as character appearances, connections, and avatar thumbnail.
|
|
code_samples: []
|
|
inherits:
|
|
- Instance
|
|
descendants: []
|
|
tags:
|
|
- NotCreatable
|
|
- Service
|
|
deprecation_message: ''
|
|
properties:
|
|
- name: Players.BanningEnabled
|
|
summary: |
|
|
Enables or disables the three `Class.Players` methods
|
|
(`Class.Players:BanAsync()|BanAsync()`,
|
|
`Class.Players:UnbanAsync()|UnbanAsync()`, and
|
|
`Class.Players:GetBanHistoryAsync()|GetBanHistoryAsync()`) that constitute
|
|
the ban API. This property is not scriptable and can only be modified in
|
|
Studio.
|
|
description: |
|
|
Enables or disables the three `Class.Players` methods
|
|
(`Class.Players:BanAsync()|BanAsync()`,
|
|
`Class.Players:UnbanAsync()|UnbanAsync()`, and
|
|
`Class.Players:GetBanHistoryAsync()|GetBanHistoryAsync()`) that constitute
|
|
the ban API. This property is not scriptable and can only be modified in
|
|
Studio.
|
|
code_samples: []
|
|
type: boolean
|
|
tags:
|
|
- NotScriptable
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Behavior
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Players
|
|
- name: Players.BubbleChat
|
|
summary: |
|
|
Indicates whether or not bubble chat is enabled. It is set with the
|
|
`Class.Players:SetChatStyle()` method.
|
|
description: |
|
|
This property indicates whether or not bubble chat is enabled. It is set
|
|
with the `Class.Players:SetChatStyle()` method using the `Enum.ChatStyle`
|
|
enum.
|
|
|
|
When this chat mode is enabled, the experience displays chats in the chat
|
|
user interface at the top-left corner of the screen.
|
|
|
|
There are two other chat modes, `Class.Players.ClassicChat` and a chat
|
|
mode where both classic and bubble chat are enabled.
|
|
code_samples: []
|
|
type: boolean
|
|
tags:
|
|
- ReadOnly
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Chat
|
|
- Players
|
|
- name: Players.CharacterAutoLoads
|
|
summary: |
|
|
Indicates whether `Class.Player.Character|characters` will respawn
|
|
automatically.
|
|
description: |
|
|
This property indicates whether `Class.Player.Character|characters` will
|
|
respawn automatically. The default value is true.
|
|
|
|
If this property is disabled (false), player
|
|
`Class.Player.Character|characters` will not spawn until the
|
|
`Class.Player:LoadCharacterAsync()` function is called for each
|
|
`Class.Player`, including when players join the experience.
|
|
|
|
This can be useful in experiences where players have finite lives, such as
|
|
competitive experiences in which players do not respawn until a round
|
|
ends.
|
|
code_samples:
|
|
- player-respawn-timer
|
|
type: boolean
|
|
tags:
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Behavior
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Players
|
|
- name: Players.ClassicChat
|
|
summary: |
|
|
Indicates whether or not classic chat is enabled; set by the
|
|
`Class.Players:SetChatStyle()` method.
|
|
description: |
|
|
Indicates whether or not classic chat is enabled. This property is set by
|
|
the `Class.Players:SetChatStyle()` method using the `Enum.ChatStyle` enum.
|
|
|
|
When this chat mode is enabled, the experience displays chats in a bubble
|
|
above the sender's head.
|
|
|
|
There are two other chat modes, `Class.Players.BubbleChat` and a chat mode
|
|
where both classic and bubble chat are enabled.
|
|
code_samples: []
|
|
type: boolean
|
|
tags:
|
|
- ReadOnly
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Chat
|
|
- Players
|
|
- name: Players.LocalPlayer
|
|
summary: |
|
|
The `Class.Player` that the `Class.LocalScript` is running for.
|
|
description: |
|
|
This read-only property refers to the `Class.Player` whose client is
|
|
running the experience.
|
|
|
|
This property is only defined for `Class.LocalScript|LocalScripts` and
|
|
`Class.ModuleScript|ModuleScripts` required by them, since they run on the
|
|
client. For the server, on which `Class.Script` objects run their code,
|
|
this property is `nil`.
|
|
code_samples: []
|
|
type: Player
|
|
tags:
|
|
- ReadOnly
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Players
|
|
- name: Players.localPlayer
|
|
summary: ''
|
|
description: ''
|
|
code_samples: []
|
|
type: Player
|
|
tags:
|
|
- Hidden
|
|
- ReadOnly
|
|
- NotReplicated
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This property is a deprecated variant of `Class.Players.LocalPlayer` which
|
|
should be used instead.
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Players
|
|
- name: Players.MaxPlayers
|
|
summary: |
|
|
The maximum number of players that can be in a server.
|
|
description: |
|
|
This property determines the maximum number of players that can be in a
|
|
server. This property can only be set through a specific place's settings
|
|
on the [Creator Dashboard](https://create.roblox.com/dashboard/creations)
|
|
or through [Experience Settings](../../../studio/experience-settings.md).
|
|
code_samples: []
|
|
type: int
|
|
tags:
|
|
- ReadOnly
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Players
|
|
- name: Players.NumPlayers
|
|
summary: |
|
|
Returns the number of people in the server at the current time.
|
|
description: |
|
|
This property indicates the number of people in the server at the current
|
|
time. It is read only. Meaning it cannot be written to, only read.
|
|
code_samples: []
|
|
type: int
|
|
tags:
|
|
- ReadOnly
|
|
- NotReplicated
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This item is deprecated. Instead, of using this item, you should count the
|
|
number of players returned by `Class.Players:GetPlayers()`.
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Players
|
|
- name: Players.numPlayers
|
|
summary: |
|
|
Returns the number of people in the server at the current time.
|
|
description: |
|
|
This property indicates the number of people in the server at the current
|
|
time. It is read only. Meaning it cannot be written to, only read.
|
|
code_samples: []
|
|
type: int
|
|
tags:
|
|
- Hidden
|
|
- ReadOnly
|
|
- NotReplicated
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This property is a deprecated variant of `Class.Players.NumPlayers` which
|
|
has also been deprecated. Neither property should be used in new work.
|
|
Instead, you should count the number of players returned by
|
|
`Class.Players:GetPlayers()`.
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Players
|
|
- name: Players.PreferredPlayers
|
|
summary: |
|
|
The preferred number of players for a server.
|
|
description: |
|
|
This property indicates the number of players to which Roblox's matchmaker
|
|
will fill servers. This number will be less than the maximum number of
|
|
players (`Class.Players.MaxPlayers`) supported by the experience.
|
|
code_samples: []
|
|
type: int
|
|
tags:
|
|
- ReadOnly
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Players
|
|
- name: Players.RespawnTime
|
|
summary: |
|
|
Controls the amount of time taken for a players character to respawn.
|
|
description: |
|
|
This property controls the time, in seconds, it takes for a player to
|
|
respawn when `Class.Players.CharacterAutoLoads` is true. It defaults to
|
|
5.0 seconds.
|
|
|
|
This is useful when you want to change how long it takes to respawn based
|
|
on the type of your experience but don't want to handle spawning players
|
|
individually.
|
|
|
|
Although this property can be set from within a `Class.Script`, you can
|
|
more easily set it directly on the `Class.Players` object in Studio's
|
|
[Explorer](../../../studio/explorer.md) window.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Players
|
|
- name: Players.UseStrafingAnimations
|
|
summary: ''
|
|
description: ''
|
|
code_samples: []
|
|
type: boolean
|
|
tags:
|
|
- NotScriptable
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Behavior
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Players
|
|
methods:
|
|
- name: Players:BanAsync
|
|
summary: |
|
|
Bans users from your experience, with options to specify duration, reason,
|
|
whether the ban applies to the entire universe or just the current place,
|
|
and more. This method is enabled and disabled by the
|
|
`Class.Players.BanningEnabled` property, which you can toggle in Studio.
|
|
description: |
|
|
The `Class.Players:BanAsync()` method allows you to easily ban users who
|
|
violate your experience's guidelines. You can specify the ban duration,
|
|
enable the ban to propagate to suspected alternate accounts, and provide a
|
|
message to the banned user in accordance with the
|
|
[Usage Guidelines](../../../players/index.md#banning-users). You should
|
|
also post your experience rules somewhere accessible to all users and
|
|
provide a way for them to appeal. This method is enabled and disabled by
|
|
the `Class.Players.BanningEnabled` property, which you can toggle in
|
|
Studio.
|
|
|
|
##### Banning and Messaging
|
|
|
|
Banned users will be immediately evicted and prevented from rejoining your
|
|
experiences. They will be presented with an error modal displaying the
|
|
time left on their ban and your `DisplayReason`. Roblox's backend systems
|
|
will evict players across all servers from the place(s) that you specify.
|
|
`DisplayReason` can have a maximum length of 400 characters and is subject
|
|
to a text filter. For more information on acceptable modal text, see
|
|
[ban messaging](../../../players/index.md#message-guidelines).
|
|
|
|
##### Places and Universe
|
|
|
|
By default, bans extend to any place within that universe. To limit the
|
|
ban to only the place from which this API is called, configure
|
|
`ApplyToUniverse` to `false`. However, if a user is banned in the start
|
|
place of the universe, it effectively results in the user being excluded
|
|
from the entirety of the universe, irrespective of whether a universal ban
|
|
is in place or not.
|
|
|
|
##### Alternative Accounts
|
|
|
|
Users often play under multiple different accounts, known as alternate
|
|
accounts or alt accounts, which are sometimes used to circumvent account
|
|
bans. To help you keep banned users out, the default behavior of this API
|
|
will propagate all bans from the source account you banned to any of their
|
|
suspected alt accounts. You can turn off ban propagations to alt accounts
|
|
by configuring `ExcludeAltAccounts` to `true`.
|
|
|
|
##### Ban Duration
|
|
|
|
Not all transgressions are the same, so not all bans should be the same
|
|
length. This API lets you configure the duration of the ban, in seconds,
|
|
with the `Duration` field. To specify a permanent ban, set the field to
|
|
`-1`. You may also want to dynamically configure the ban duration based on
|
|
the user's ban history, which you can query for using
|
|
`Class.Players:GetBanHistoryAsync()`. For example, you may want to
|
|
consider the number of bans, the duration of previous bans, or build logic
|
|
off of the notes you save under `PrivateReason` which can be up to 1000
|
|
characters and are not text filtered. `PrivateReason` notes are never
|
|
shared with the client and can be considered safe from attackers.
|
|
|
|
##### Errors and Throttling
|
|
|
|
This method invokes an HTTP call to backend services which are subject to
|
|
throttling and may fail. If you're calling this API with more than one
|
|
`Class.Player.UserId|UserId`, this method will attempt to make the HTTP
|
|
call for each ID. It will then aggregate any error messages and join them
|
|
as a comma separated list. For example, if this method is invoked for five
|
|
users and requests for those with `Class.Player.UserId|UserIds` 2 and 4
|
|
fail, the following error message appears:
|
|
|
|
`HTTP failure for UserId 2: Timedout, HTTP 504 (Service unavailable) failure for UserId 4: Service exception`
|
|
|
|
The message will always include `failure for UserId {}` if it is an HTTP
|
|
error.
|
|
|
|
##### Client-Side Requirement
|
|
|
|
Because of the risks associated with banning users, this method may only
|
|
be called on the backend experience server (client-side calls will result
|
|
in an error). You may test this API in Studio, during
|
|
[collaborative](../../../projects/collaboration.md) creation, or in a
|
|
[team test](../../../studio/testing-modes.md#collaborative-testing), but
|
|
the bans will not apply to production.
|
|
|
|
This API uses the
|
|
[User Restrictions Open Cloud API](/cloud/reference/UserRestriction). You
|
|
will be able to utilize these APIs to manage your bans in third party
|
|
applications.
|
|
code_samples:
|
|
- Players-Ban
|
|
parameters:
|
|
- name: config
|
|
type: Dictionary
|
|
default:
|
|
summary: |
|
|
- `UserIds` (required; array) — Array of `Class.Player.UserId|UserIds`
|
|
of players to be banned. Max size is `50`.
|
|
|
|
- `ApplyToUniverse` (optional; boolean) — Whether ban propagates to
|
|
all places within the experience universe. Default is `true`.
|
|
|
|
- `Duration` (required; integer) — Duration of the ban, in seconds.
|
|
Permanent bans should have a value of `-1`. `0` and all other
|
|
negative values are invalid.
|
|
|
|
- `DisplayReason` (required; string) — The message that will be
|
|
displayed to users when they attempt to and fail to join an
|
|
experience. Maximum string length is `400`.
|
|
|
|
- `PrivateReason` (required; string) — Internal messaging that will be
|
|
returned when querying the user's ban history. Maximum string length
|
|
is `1000`.
|
|
|
|
- `ExcludeAltAccounts` (optional; boolean) — When `true`, Roblox does
|
|
not attempt to ban alt accounts. Default is `false`.
|
|
returns:
|
|
- type: ()
|
|
summary: ''
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- Consequences
|
|
- name: Players:Chat
|
|
summary: |
|
|
Makes the local player chat the given message.
|
|
description: |
|
|
This function makes the local player chat the given message. Since this
|
|
item is protected, attempting to use it in a `Class.Script` or
|
|
`Class.LocalScript` will cause an error.
|
|
|
|
Instead, when creating a custom chat system, or a system that needs access
|
|
to the chat, you can use the `Class.Chat` service's `Class.Chat:Chat()`
|
|
function instead.
|
|
code_samples:
|
|
- Players-Chat1
|
|
parameters:
|
|
- name: message
|
|
type: string
|
|
default:
|
|
summary: |
|
|
The message chatted.
|
|
returns:
|
|
- type: ()
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: PluginSecurity
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:CreateHumanoidModelFromDescriptionAsync
|
|
summary: |
|
|
Returns a character `Class.Model` equipped with everything specified in
|
|
the passed in `Class.HumanoidDescription`.
|
|
description: |
|
|
Returns a character `Class.Model` equipped with everything specified in
|
|
the passed in `Class.HumanoidDescription`, and is R6 or R15 as specified
|
|
by `rigType`.
|
|
code_samples:
|
|
- create-humanoid-model-from-description
|
|
parameters:
|
|
- name: description
|
|
type: HumanoidDescription
|
|
default:
|
|
summary: |
|
|
Specifies the appearance of the returned character.
|
|
- name: rigType
|
|
type: HumanoidRigType
|
|
default:
|
|
summary: |
|
|
Specifies whether the returned character will be R6 or R15.
|
|
- name: assetTypeVerification
|
|
type: AssetTypeVerification
|
|
default: Default
|
|
summary: |
|
|
The asset type verification mode.
|
|
returns:
|
|
- type: Model
|
|
summary: |
|
|
A `Class.Humanoid` character `Class.Model`.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Avatar
|
|
- Players
|
|
- name: Players:CreateHumanoidModelFromDescription
|
|
summary: |
|
|
Returns a character `Class.Model` equipped with everything specified in
|
|
the passed in `Class.HumanoidDescription`.
|
|
description: ''
|
|
code_samples: []
|
|
parameters:
|
|
- name: description
|
|
type: HumanoidDescription
|
|
default:
|
|
summary: |
|
|
Specifies the appearance of the returned character.
|
|
- name: rigType
|
|
type: HumanoidRigType
|
|
default:
|
|
summary: |
|
|
Specifies whether the returned character will be R6 or R15.
|
|
- name: assetTypeVerification
|
|
type: AssetTypeVerification
|
|
default: Default
|
|
summary: |
|
|
The asset type verification mode.
|
|
returns:
|
|
- type: Model
|
|
summary: |
|
|
A `Class.Humanoid` character `Class.Model`.
|
|
tags:
|
|
- Yields
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This method has been superseded by
|
|
`Class.Players:CreateHumanoidModelFromDescription()|CreateHumanoidModelFromDescription()`.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Avatar
|
|
- Players
|
|
- name: Players:CreateHumanoidModelFromUserIdAsync
|
|
summary: |
|
|
Returns a character Model set-up with everything equipped to match the
|
|
avatar of the user specified by the passed in userId.
|
|
description: |
|
|
Returns a character Model set-up with everything equipped to match the
|
|
avatar of the user specified by the passed in userId. This includes
|
|
whether that character is currently R6 or R15.
|
|
code_samples:
|
|
- create-humanoid-model-from-userid
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The userId for a Roblox user. (The UserId is the number in the profile
|
|
of the user e.g www.roblox.com/users/1/profile).
|
|
returns:
|
|
- type: Model
|
|
summary: |
|
|
A Humanoid character Model.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:CreateHumanoidModelFromUserId
|
|
summary: |
|
|
Returns a character Model set-up with everything equipped to match the
|
|
avatar of the user specified by the passed in userId.
|
|
description: ''
|
|
code_samples:
|
|
- create-humanoid-model-from-userid
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The userId for a Roblox user. (The UserId is the number in the profile
|
|
of the user e.g www.roblox.com/users/1/profile).
|
|
returns:
|
|
- type: Model
|
|
summary: |
|
|
A Humanoid character Model.
|
|
tags:
|
|
- Yields
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This method has been superseded by
|
|
`Class.Players:CreateHumanoidModelFromUserIdAsync()|CreateHumanoidModelFromUserIdAsync()`.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetBanHistoryAsync
|
|
summary: |
|
|
Retrieves the ban and unban history of any user within the experience's
|
|
universe. This method is enabled and disabled by the
|
|
`Class.Players.BanningEnabled` property, which you can toggle in Studio.
|
|
description: |
|
|
Retrieves the ban and unban history of any user within the experience's
|
|
universe. This method returns a `Class.BanHistoryPages` instance that
|
|
inherits from `Class.Pages`. This method is enabled and disabled by the
|
|
`Class.Players.BanningEnabled` property, which you can toggle in Studio.
|
|
|
|
This function call will only succeed on production servers and not on
|
|
client devices or in Studio.
|
|
|
|
This API uses the
|
|
[User Restrictions Open Cloud API](/cloud/reference/UserRestriction). You
|
|
will be able to utilize these APIs to manage your bans in third party
|
|
applications.
|
|
code_samples: []
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: BanHistoryPages
|
|
summary: |
|
|
See `Class.BanHistoryPages` for return reference.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- Consequences
|
|
- name: Players:GetCharacterAppearanceAsync
|
|
summary: |
|
|
Returns a `Class.Model` containing the assets which the player is wearing,
|
|
excluding gear.
|
|
description: |
|
|
This function returns a `Class.Model` containing the assets which the
|
|
player is wearing, excluding gear.
|
|
|
|
If you prefer a Luau table of information about these assets instead of a
|
|
model, use `Class.Players:GetCharacterAppearanceInfoAsync()`.
|
|
|
|
This method behaves similar to `Class.InsertService:LoadAsset()`, and is
|
|
like using `Class.InsertService:LoadAsset()|LoadAsset` on the asset
|
|
information returned by `Class.Players:GetCharacterAppearanceInfoAsync()`
|
|
except faster.
|
|
code_samples:
|
|
- how-to-get-a-character-s-appearance
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The `Class.Player.UserId` of the specified player.
|
|
returns:
|
|
- type: Model
|
|
summary: ''
|
|
tags:
|
|
- Yields
|
|
- Deprecated
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetCharacterAppearanceInfoAsync
|
|
summary: |
|
|
Returns information about the character appearance of a given user.
|
|
description: |
|
|
This function returns information about a player's avatar on the Roblox
|
|
website in the form of a dictionary. It is not to be confused with
|
|
`Class.Players:GetCharacterAppearanceAsync()|GetCharacterAppearanceAsync`,
|
|
which actually loads the assets described by this method. You can use
|
|
`Class.InsertService:LoadAsset()` to load the assets that are used in the
|
|
player's avatar. The structure of the returned dictionary is as follows:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tr>
|
|
<td><code>assets</code></td>
|
|
<td>table (see below)</td>
|
|
<td>Describes the equipped assets (hats, body parts, etc)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>bodyColors</code></td>
|
|
<td>table (see below)</td>
|
|
<td>Describes the BrickColor values for each limb</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>bodyColor3s</code></td>
|
|
<td>table (see below)</td>
|
|
<td>Describes the Color3 instance for each limb which may not match perfectly with bodyColors</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>defaultPantsApplied</code></td>
|
|
<td>bool</td>
|
|
<td>Describes whether default pants are applied</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>defaultShirtApplied</code></td>
|
|
<td>bool</td>
|
|
<td>Describes whether default shirt is applied</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>emotes</code></td>
|
|
<td>table (see below)</td>
|
|
<td>Describes the equipped emote animations</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>playerAvatarType</code></td>
|
|
<td>string</td>
|
|
<td>Either "R15" or "R6"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>scales</code></td>
|
|
<td>table (see below)</td>
|
|
<td>Describes various body scaling factors</td>
|
|
</tr>
|
|
</table>
|
|
|
|
##### Assets Sub-Table
|
|
|
|
The `assets` table is an array of tables containing the following keys
|
|
that describe the assets currently equipped by the player:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tr>
|
|
<td><code>id</code></td>
|
|
<td>number</td>
|
|
<td>The asset ID of the equipped asset</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>assetType</code></td>
|
|
<td>table</td>
|
|
<td>A table with <code>name</code> and <code>id</code> fields, each describing the kind of asset equipped ("Hat", "Face", etc.)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>name</code></td>
|
|
<td>string</td>
|
|
<td>The name of the equipped asset</td>
|
|
</tr>
|
|
</table>
|
|
|
|
##### Scales Sub-Table
|
|
|
|
The `scales` table has the following keys, each a number corresponding to
|
|
one `Class.Humanoid` scaling property: `bodyType`, `head`, `height`,
|
|
`proportion`, `depth`, `width`.
|
|
|
|
##### Body Colors Sub-Table
|
|
|
|
The `bodyColors` table has the following keys, each a number corresponding
|
|
to a `Datatype.BrickColor` ID number which can be used with
|
|
`Datatype.BrickColor.new(id)`: `leftArmColorId`, `torsoColorId`,
|
|
`rightArmColorId`, `headColorId`, `leftLegColorId`, `rightLegColorId`.
|
|
code_samples:
|
|
- example-return-dictionary
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The \*_userId_ of the specified player.
|
|
returns:
|
|
- type: Dictionary
|
|
summary: |
|
|
A dictionary containing information about the character appearance of
|
|
a given user.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetFriendsAsync
|
|
summary: |
|
|
Returns a `Class.FriendPages` object which contains information for all of
|
|
the given player's connections.
|
|
description: |
|
|
The GetFriends `Class.Players` function returns a `Class.FriendPages`
|
|
object which contains information for all of the given user's connections.
|
|
The items within the `Class.FriendPages` object are tables with the
|
|
following fields:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tr>
|
|
<td>Id</td>
|
|
<td>int64</td>
|
|
<td>The connections's UserId</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Username</td>
|
|
<td>string</td>
|
|
<td>The connections's username</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DisplayName</td>
|
|
<td>string</td>
|
|
<td>The <code>Class.Player.DisplayName|display name</code> of the connections.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
See the code samples for an easy way to iterate over all a player's
|
|
connections.
|
|
code_samples:
|
|
- print-roblox-friends
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The user ID of the player being specified.
|
|
returns:
|
|
- type: FriendPages
|
|
summary: ''
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- Social
|
|
- name: Players:GetHumanoidDescriptionFromOutfitIdAsync
|
|
summary: |
|
|
Returns the HumanoidDescription for a specified outfit, which will be set
|
|
with the parts/colors/Animations etc of the outfit.
|
|
description: |
|
|
Returns the HumanoidDescription for a specified outfitId, which will be
|
|
set with the parts/colors/Animations etc of the outfit. An outfit can be
|
|
one created by a user, or it can be the outfit for a bundle created by
|
|
Roblox.
|
|
code_samples:
|
|
- get-humanoiddescription-from-outfitid
|
|
parameters:
|
|
- name: outfitId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The ID of the outfit for which the HumanoidDescription is sought.
|
|
returns:
|
|
- type: HumanoidDescription
|
|
summary: |
|
|
HumanoidDescription initialized with the specification for the passed
|
|
in outfitId.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Avatar
|
|
- Players
|
|
- name: Players:GetHumanoidDescriptionFromOutfitId
|
|
summary: |
|
|
Returns the HumanoidDescription for a specified outfit, which will be set
|
|
with the parts/colors/Animations etc of the outfit.
|
|
description: ''
|
|
code_samples:
|
|
- get-humanoiddescription-from-outfitid
|
|
parameters:
|
|
- name: outfitId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The ID of the outfit for which the HumanoidDescription is sought.
|
|
returns:
|
|
- type: HumanoidDescription
|
|
summary: |
|
|
HumanoidDescription initialized with the specification for the passed
|
|
in outfitId.
|
|
tags:
|
|
- Yields
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This method has been superseded by
|
|
`Class.Players:GetHumanoidDescriptionFromOutfitIdAsync()|GetHumanoidDescriptionFromOutfitIdAsync()`.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Avatar
|
|
- Players
|
|
- name: Players:GetHumanoidDescriptionFromUserIdAsync
|
|
summary: |
|
|
Returns a HumanoidDescription which specifies everything equipped for the
|
|
avatar of the user specified by the passed in userId.
|
|
description: |
|
|
Returns a HumanoidDescription which specifies everything equipped for the
|
|
avatar of the user specified by the passed in userId. Also includes scales
|
|
and body colors.
|
|
code_samples:
|
|
- get-humanoiddescription-from-userid
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The userId for a Roblox user. (The UserId is the number in the profile
|
|
of the user e.g www.roblox.com/users/1/profile).
|
|
returns:
|
|
- type: HumanoidDescription
|
|
summary: |
|
|
HumanoidDescription initialized with the passed in user's avatar
|
|
specification.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Avatar
|
|
- Players
|
|
- name: Players:GetHumanoidDescriptionFromUserId
|
|
summary: |
|
|
Returns a HumanoidDescription which specifies everything equipped for the
|
|
avatar of the user specified by the passed in userId.
|
|
description: ''
|
|
code_samples:
|
|
- get-humanoiddescription-from-userid
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The userId for a Roblox user. (The UserId is the number in the profile
|
|
of the user e.g www.roblox.com/users/1/profile).
|
|
returns:
|
|
- type: HumanoidDescription
|
|
summary: |
|
|
HumanoidDescription initialized with the passed in user's avatar
|
|
specification.
|
|
tags:
|
|
- Yields
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This method has been superseded by
|
|
`Class.Players.GetHumanoidDescriptionFromUserIdAsync|GetHumanoidDescriptionFromUserIdAsync()`.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Avatar
|
|
- Players
|
|
- name: Players:GetNameFromUserIdAsync
|
|
summary: |
|
|
Sends a query to the Roblox website for the username of an account with a
|
|
given `Class.Player.UserId|UserId`.
|
|
description: |
|
|
The GetNameFromUserIdAsync `Class.Players` function will send a query to
|
|
the Roblox website asking what the username is of the account with the
|
|
given `Class.Player.UserId|UserId`.
|
|
|
|
This method errors if no account exists with the given UserId. If you
|
|
aren't certain such an account exists, it's recommended to wrap calls to
|
|
this function with `Global.LuaGlobals.pcall()`. In addition, you can
|
|
manually cache results to make future calls with the same UserId fast. See
|
|
the code samples to learn more.
|
|
code_samples:
|
|
- Name-From-UserId
|
|
- Name-From-UserId-Cache
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The `Class.Player.UserId` of the player being specified.
|
|
returns:
|
|
- type: string
|
|
summary: |
|
|
The name of a user with the specified `Class.Player.UserId`.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetPlayerByUserId
|
|
summary: |
|
|
Returns the `Class.Player` with the given `Class.Player.UserId|UserId` if
|
|
they are in-experience.
|
|
description: |
|
|
This function searches each `Class.Player` in `Class.Players` for one
|
|
whose `Class.Player.UserId` matches the given `userId`. If such a player
|
|
does not exist, it returns `nil`.
|
|
|
|
This method is useful in finding the purchaser of a developer product
|
|
using `Class.MarketplaceService.ProcessReceipt` which provides a table
|
|
that includes the purchaser's `Class.Player.UserId|UserId` and not a
|
|
reference to the `Class.Player` object itself. Most experiences will
|
|
require a reference to the player in order to grant products.
|
|
code_samples:
|
|
- Players-GetPlayerByUserId1
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The `Class.Player.UserId` of the player being specified.
|
|
returns:
|
|
- type: Player
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Safe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetPlayerFromCharacter
|
|
summary: |
|
|
Returns the `Class.Player` whose `Class.Player.Character` matches the
|
|
given instance, or `nil` if one cannot be found.
|
|
description: |
|
|
This function returns the `Class.Player` associated with the given
|
|
`Class.Player.Character`, or `nil` if one cannot be found. It is
|
|
equivalent to the following function:
|
|
|
|
```lua
|
|
local function getPlayerFromCharacter(character)
|
|
for _, player in game:GetService("Players"):GetPlayers() do
|
|
if player.Character == character then
|
|
return player
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
This method is often used when some event in player's character fires
|
|
(such as their `Class.Humanoid` `Class.Humanoid.Died|dying`). Such an
|
|
event might not directly reference the Player object, but this method
|
|
provides easy access. The inverse of this function can be described as
|
|
getting the Character of a Player. To do this, simply access the Character
|
|
property.
|
|
code_samples:
|
|
- Players-GetPlayerFromCharacter1
|
|
parameters:
|
|
- name: character
|
|
type: Model
|
|
default:
|
|
summary: |
|
|
A character instance that you want to get the player from.
|
|
returns:
|
|
- type: Player
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetPlayers
|
|
summary: |
|
|
Returns a table of all presently connected `Class.Player` objects.
|
|
description: |
|
|
This method returns a table of all presently connected `Class.Player`
|
|
objects. It functions the same way `Class.Instance:GetChildren()` would
|
|
except that it only returns `Class.Player` objects found under
|
|
`Class.Players`. When used with a `for` loop, it is useful for iterating
|
|
over all players in an experience.
|
|
|
|
```lua
|
|
local Players = game:GetService("Players")
|
|
|
|
for _, player in Players:GetPlayers() do
|
|
print(player.Name)
|
|
end
|
|
```
|
|
|
|
Scripts that connect to `Class.Players.PlayerAdded` are often trying to
|
|
process every Player that connects to the experience. This method is
|
|
useful for iterating over already-connected players that wouldn't fire
|
|
`Class.Players.PlayerAdded|PlayerAdded`. Using this method ensures that no
|
|
player is missed!
|
|
|
|
```lua
|
|
local Players = game:GetService("Players")
|
|
|
|
local function onPlayerAdded(player)
|
|
print("Player: " .. player.Name)
|
|
end
|
|
|
|
for _, player in Players:GetPlayers() do
|
|
onPlayerAdded(player)
|
|
end
|
|
Players.PlayerAdded:Connect(onPlayerAdded)
|
|
```
|
|
code_samples:
|
|
- Give-Sparkles-to-Everyone
|
|
parameters: []
|
|
returns:
|
|
- type: Instances
|
|
summary: |
|
|
A table containing all the players in the server.
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Safe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:getPlayers
|
|
summary: ''
|
|
description: ''
|
|
code_samples: []
|
|
parameters: []
|
|
returns:
|
|
- type: Instances
|
|
summary: ''
|
|
tags:
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This function is a deprecated variant of `Class.Players:GetPlayers()`
|
|
which should be used instead.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetUserIdFromNameAsync
|
|
summary: |
|
|
Sends a query to the Roblox website for the `Class.Player.UserId|userId`
|
|
of an account with a given username.
|
|
description: |
|
|
This function will send a query to the Roblox website asking what the
|
|
`Class.Player.UserId` is of the account with the given `Class.Player`
|
|
name.
|
|
|
|
This method errors if no account exists with the given username. If you
|
|
aren't certain such an account exists, it's recommended to wrap calls to
|
|
this function with `Global.LuaGlobals.pcall()`. In addition, you can
|
|
manually cache results to quickly make future calls with the same
|
|
username. See the code samples to learn more.
|
|
code_samples:
|
|
- UserId-From-Name
|
|
- UserId-From-Name-Cache
|
|
parameters:
|
|
- name: userName
|
|
type: string
|
|
default:
|
|
summary: |
|
|
The username of the player being specified.
|
|
returns:
|
|
- type: int64
|
|
summary: |
|
|
The `Class.Player.UserId` of a user whose name is specified.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:GetUserThumbnailAsync
|
|
summary: |
|
|
Returns the content URL of a player thumbnail given the size and type, as
|
|
well as a boolean describing if the image is ready to use.
|
|
description: |
|
|
This function returns the content URL of an image of a player's avatar
|
|
given their `Class.Player.UserId|UserId`, the desired image size as a
|
|
`Enum.ThumbnailSize` enum, and the desired type as a `Enum.ThumbnailType`
|
|
enum. It also returns a boolean describing if the image is ready to use.
|
|
|
|
Most often, this method is used with `Class.ImageLabel.Image` or
|
|
`Class.Decal.Texture` to display user avatar pictures in an experience.
|
|
code_samples:
|
|
- display-player-thumbnail
|
|
parameters:
|
|
- name: userId
|
|
type: int64
|
|
default:
|
|
summary: |
|
|
The `Class.Player.UserId` of the player being specified.
|
|
- name: thumbnailType
|
|
type: ThumbnailType
|
|
default:
|
|
summary: |
|
|
A `Enum.ThumbnailType` describing the type of thumbnail.
|
|
- name: thumbnailSize
|
|
type: ThumbnailSize
|
|
default:
|
|
summary: |
|
|
A `Enum.ThumbnailSize` specifying the size of the thumbnail.
|
|
returns:
|
|
- type: Tuple
|
|
summary: |
|
|
A tuple containing the content URL of a user thumbnail based on the
|
|
specified parameters, and a bool describing if the image is ready to
|
|
be used or not.
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:playerFromCharacter
|
|
summary: ''
|
|
description: ''
|
|
code_samples: []
|
|
parameters:
|
|
- name: character
|
|
type: Model
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: Player
|
|
summary: ''
|
|
tags:
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This function is a deprecated variant of
|
|
`Class.Players:GetPlayerFromCharacter()` which should be used in new work.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:players
|
|
summary: |
|
|
Returns a list of players in an experience.
|
|
description: |
|
|
This function was once used to return a list of players in an experience,
|
|
but has since been deprecated in favor of `Class.Players:GetPlayers()`
|
|
code_samples: []
|
|
parameters: []
|
|
returns:
|
|
- type: Instances
|
|
summary: ''
|
|
tags:
|
|
- Deprecated
|
|
deprecation_message: |
|
|
This item has been superseded by `Class.Players:GetPlayers()` which should
|
|
be used in all new work.
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:SetChatStyle
|
|
summary: |
|
|
Sets whether BubbleChat and ClassicChat are being used, and tells TeamChat
|
|
and `Class.Chat` what to do.
|
|
description: |
|
|
This function sets whether BubbleChat and ClassicChat are being used, and
|
|
tells TeamChat and Chat what to do using the `Enum.ChatStyle` enum. Since
|
|
this item is protected, attempting to use it in a `Class.Script` or
|
|
`Class.LocalScript` will cause an error.
|
|
|
|
This function is used internally when the chat mode is set by the
|
|
experience.
|
|
code_samples:
|
|
- setting-a-player-s-chat-style
|
|
parameters:
|
|
- name: style
|
|
type: ChatStyle
|
|
default: Classic
|
|
summary: |
|
|
The specified chat style being set.
|
|
returns:
|
|
- type: ()
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: PluginSecurity
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:TeamChat
|
|
summary: |
|
|
Makes the local player chat the given message, which will only be viewable
|
|
by users on the same team.
|
|
description: |
|
|
This function makes the `Class.Players.LocalPlayer` chat the given
|
|
message, which will only be viewable by users on the same team. Since this
|
|
item is protected, attempting to use it in a `Class.Script` or
|
|
`Class.LocalScript` will cause an error.
|
|
|
|
This function is used internally when the `Class.Players.LocalPlayer`
|
|
sends a message to their team.
|
|
code_samples:
|
|
- sending-team-chat
|
|
parameters:
|
|
- name: message
|
|
type: string
|
|
default:
|
|
summary: |
|
|
The message being chatted.
|
|
returns:
|
|
- type: ()
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: PluginSecurity
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- name: Players:UnbanAsync
|
|
summary: |
|
|
Unbans players banned from `Class.Players:BanAsync()` or the User
|
|
Restrictions Open Cloud API. This method is enabled and disabled by the
|
|
`Class.Players.BanningEnabled` property, which you can toggle in Studio.
|
|
description: |
|
|
Unbans players banned from `Class.Players:BanAsync()` or the
|
|
[User Restrictions Open Cloud API](/cloud/reference/UserRestriction). This
|
|
method is enabled and disabled by the `Class.Players.BanningEnabled`
|
|
property, which you can toggle in Studio.
|
|
|
|
Like `Class.Players:BanAsync()`, this method takes in a `config`
|
|
dictionary that will let you bulk unban users. This configures the users
|
|
that are unbanned and the scope from which they are unbanned from.
|
|
|
|
Unbans will only take effect on bans with the same `ApplyToUniverse`
|
|
scope. For example, an unban with `ApplyToUniverse` set to `true` will not
|
|
invalidate a previous ban with `ApplyToUniverse` set to `false`. In other
|
|
words, a universe level unban will not invalidate a place level ban. The
|
|
opposite also holds true.
|
|
|
|
This method invokes a HTTP call to backend services, which are throttled
|
|
and may fail. If you are calling this API with multiple UserIds, this
|
|
method will attempt to make this HTTP call for each UserId. It will then
|
|
aggregate any error messages and join them as a comma separated list. For
|
|
example, if this method is invoked for five `UserIds`: `{1, 2, 3, 4, 5}`
|
|
and requests for users 2 and 4 fail then the following error message
|
|
appears:
|
|
`HTTP failure for UserId 2: Timedout, HTTP 504 (Service unavailable) failure for UserId 4: Service exception.`
|
|
The message will always include `failure for UserId {}` if it is an HTTP
|
|
error. It is undefined behavior if you pass in both valid and invalid
|
|
UserIds, i.e. a `UserId` that is not a positive number, as some network
|
|
requests may succeed before all input is validated.
|
|
|
|
Because of the risks associated with banning users, this method may only
|
|
be called on the backend server. Client side calls will result in an
|
|
error. You may test this API in Studio, Team Create, and Team Test, but
|
|
the bans will not apply to production. This function call will only
|
|
attempt ban requests on production servers and not in Studio testing.
|
|
However, all input validation steps will still work in Studio.
|
|
|
|
This API uses the
|
|
[User Restrictions Open Cloud API](/cloud/reference/UserRestriction). You
|
|
will be able to utilize these APIs to manage your bans in third party
|
|
applications.
|
|
code_samples:
|
|
- Players-Unban
|
|
parameters:
|
|
- name: config
|
|
type: Dictionary
|
|
default:
|
|
summary: |
|
|
<table><thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>UserIds</code></td>
|
|
<td>array</td>
|
|
<td>UserIDs to be force allowed into the experience(s). <br /> <br />Max size is <code>50</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ApplyToUniverse</code></td>
|
|
<td>boolean</td>
|
|
<td>Propagates the unban to all places within this universe.<br /></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
returns:
|
|
- type: ()
|
|
summary: ''
|
|
tags:
|
|
- Yields
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Players
|
|
- Consequences
|
|
events:
|
|
- name: Players.PlayerAdded
|
|
summary: |
|
|
Fires when a player enters the experience.
|
|
description: |
|
|
This event fires when a player enters the experience, such as loading the
|
|
player's saved `Class.GlobalDataStore` data.
|
|
|
|
This can be used alongside the `Class.Players.PlayerRemoving` event, which
|
|
fires when a player is about to leave the experience. For instance, if you
|
|
would like print a message every time a new player joins or leaves:
|
|
|
|
```lua
|
|
local Players = game:GetService("Players")
|
|
|
|
Players.PlayerAdded:Connect(function(player)
|
|
print(player.Name .. " joined the experience!")
|
|
end)
|
|
|
|
Players.PlayerRemoving:Connect(function(player, reason)
|
|
print(player.Name .. " left the experience! Reason: " .. tostring(exitReason))
|
|
end)
|
|
```
|
|
|
|
If you want to track when a player's character is added or removed from
|
|
the experience, such as when a player respawns or dies, you can use the
|
|
`Class.Player.CharacterAdded` and `Class.Player.CharacterRemoving`
|
|
functions.
|
|
|
|
Note that this event does not work as expected in a solo playtest mode
|
|
because the player is created before scripts run that connect to
|
|
`Class.Players.PlayerAdded|PlayerAdded`. To handle this case, as well as
|
|
cases in which the script is added into the experience after a player
|
|
enters, create an `onPlayerAdded()` function that you can call to handle a
|
|
player's entrance.
|
|
code_samples:
|
|
- Players-PlayerAdded1
|
|
parameters:
|
|
- name: player
|
|
type: Player
|
|
default:
|
|
summary: |
|
|
An instance of the player that joined the experience.
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
capabilities:
|
|
- Players
|
|
- name: Players.PlayerMembershipChanged
|
|
summary: |
|
|
Fires when the experience server recognizes that a player's membership has
|
|
changed.
|
|
description: |
|
|
This event fires when the experience server recognizes that a player's
|
|
membership has changed. Note, however, that the server will only attempt
|
|
to check and update the membership **after** the Premium modal has been
|
|
closed. Thus, to account for cases where the user purchases Premium
|
|
**outside** of the experience while playing, you must still prompt them to
|
|
purchase Premium; this will then show a message telling them they're
|
|
already upgraded and, once they close the modal, the server will update
|
|
their membership and trigger this event.
|
|
|
|
To learn more about and incorporating Premium into your experience and
|
|
monetizing with the engagement-based payouts system, see
|
|
[Engagement-Based Payouts](../../../production/monetization/engagement-based-payouts.md).
|
|
|
|
See also:
|
|
|
|
- `Class.MarketplaceService:PromptPremiumPurchase()`, used to prompt a
|
|
user to purchase Premium
|
|
- `Class.MarketplaceService.PromptPremiumPurchaseFinished`, fires when the
|
|
Premium purchase UI closes
|
|
code_samples:
|
|
- handling-premium-membership-changes
|
|
parameters:
|
|
- name: player
|
|
type: Player
|
|
default:
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
capabilities:
|
|
- Players
|
|
- name: Players.PlayerRemoving
|
|
summary: |
|
|
Fires when a player is about to leave the experience.
|
|
description: |
|
|
This event fires right before a `Class.Player` leaves the experience,
|
|
before `Class.Instance.ChildRemoved|ChildRemoved` fires on
|
|
`Class.Players`, and behaves somewhat similarly to
|
|
`Class.Instance.DescendantRemoving`. Since it fires before the actual
|
|
removal of a `Class.Player`, this event is useful for storing player data
|
|
using a `Class.GlobalDataStore`.
|
|
|
|
This can be used alongside the `Class.Player.PlayerAdded` event, which
|
|
fires when a player joins the experience. For instance, to print a message
|
|
every time a new player joins or leaves:
|
|
|
|
```lua
|
|
local Players = game:GetService("Players")
|
|
|
|
Players.PlayerAdded:Connect(function(player)
|
|
print(player.Name .. " joined the experience!")
|
|
end)
|
|
|
|
Players.PlayerRemoving:Connect(function(player, exitReason)
|
|
print(player.Name .. " left the experience! - Reason: " .. tostring(exitReason))
|
|
end)
|
|
```
|
|
|
|
If you want to track when a player's character is added or removed from
|
|
the experience, such as when a player respawns or dies, you can use the
|
|
`Class.Player.CharacterAdded` and `Class.Player.CharacterRemoving`
|
|
functions.
|
|
code_samples:
|
|
- Players-PlayerRemoving1
|
|
parameters:
|
|
- name: player
|
|
type: Player
|
|
default:
|
|
summary: |
|
|
An instance of the player that is leaving.
|
|
- name: reason
|
|
type: PlayerExitReason
|
|
default:
|
|
summary: |
|
|
Enum.PlayerExitReason in attempt to inform why.
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
capabilities:
|
|
- Players
|
|
- name: Players.UserSubscriptionStatusChanged
|
|
summary: |
|
|
Fires when the experience server recognizes that the user's status for a
|
|
certain subscription has changed.
|
|
description: |
|
|
This event fires when the experience server recognizes that the user's
|
|
status for a certain subscription has changed. Note that the server only
|
|
attempts to check and update the status **after** the Subscription
|
|
Purchase modal has been closed. To account for cases in which the user
|
|
purchases the subscription **outside** of the experience while playing,
|
|
you must still prompt them to purchase the subscription; the prompt shows
|
|
a message telling the user they're already subscribed, and after they
|
|
close the modal, the server updates their subscription status and triggers
|
|
this event.
|
|
|
|
Note that only server scripts receive this event.
|
|
code_samples: []
|
|
parameters:
|
|
- name: user
|
|
type: Player
|
|
default:
|
|
summary: |
|
|
User whose subscription status has changed.
|
|
- name: subscriptionId
|
|
type: string
|
|
default:
|
|
summary: |
|
|
The ID of the subscription with a status change.
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
capabilities:
|
|
- Players
|
|
- Monetization
|
|
callbacks: []
|