rojo/.cursor/rules/roblox/reference/engine/classes/StarterPlayer.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: StarterPlayer
type: class
memory_category: Instances
summary: |
  A service which allows the defaults of properties in the `Class.Player` object
  to be set.
description: |
  A service which allows the defaults of properties in the `Class.Player` object
  to be set. When a player enters the server, each property of the player object
  is set to the current value of the corresponding property in
  `Class.StarterPlayer`.

  Additionally, you may add four objects to this service:

  - A `Class.StarterPlayerScripts` instance with scripts that run once for each
    player.
  - A `Class.StarterCharacterScripts` instance with scripts to add to each
    player's character every time they spawn.
  - A `Class.Humanoid` instance named `StarterHumanoid` which will be used as
    the default humanoid for each player's character.
  - A `Class.Model` instance named `StarterCharacter` which will be used as the
    character model for all players.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
deprecation_message: ''
properties:
  - name: StarterPlayer.AllowCustomAnimations
    summary: |
      Describes the current game's permission levels regarding custom avatar
      animations from the website.
    description: |
      This property describes the current game's permission levels regarding
      custom avatar `Class.Animation|Animations` from the website.

      As such, this value cannot be changed from within the game. It can only be
      changed by changing the game's permission levels within the game's
      setting's page on the website.

      This property is not intended for use in the game.
    code_samples: []
    type: boolean
    tags:
      - Hidden
    deprecation_message: ''
    security:
      read: None
      write: RobloxScriptSecurity
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.AutoJumpEnabled
    summary: |
      Sets whether the character will automatically jump when hitting an
      obstacle on a mobile device.
    description: |
      This property sets whether the character will automatically jump when
      hitting an obstacle on a mobile device.

      This property is copied from the `Class.StarterPlayer` to a `Class.Player`
      when they join the game. Following that. the value of this property is
      copied to `Class.Humanoid.AutoJumpEnabled` property of the character's
      `Class.Humanoid` on spawn. In other words, it is possible to set the
      auto-jump behavior on a per-character, per-player and per-game basis using
      these three properties.
    code_samples:
      - Auto-Jump-Toggle
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Mobile
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.AvatarJointUpgrade
    summary: |
      Controls whether avatars spawn with AnimationConstraint joints for
      physical simulation.
    description: |
      This property controls the rollout state of new AnimationConstraint joints
      in avatars. When Disabled, avatars spawn with legacy
      `Class.Motor6D|Motor6Ds` connecting their limbs. When Enabled, avatars
      spawn with `Class.AnimationConstraint|AnimationConstraints` and
      `Class.BallSocketConstraint|BallSocketConstraints` connecting their limbs.
      This makes it easier to write scripts that enable physical simulation,
      like arm strength and ragdoll falling down.

      For more info see the
      [devforum announcement](https://devforum.roblox.com/t/studio-beta-avatar-joint-upgrade-enabling-physically-simulated-characters/3266099).
    code_samples: []
    type: RolloutState
    tags:
      - NotReplicated
      - NotScriptable
      - NotBrowsable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Players
  - name: StarterPlayer.CameraMaxZoomDistance
    summary: |
      The maximum distance the player's default camera is allowed to zoom out in
      studs.
    description: |
      This property sets the maximum distance in studs the camera can be from
      the character with the default cameras.

      This property sets the default value of
      `Class.Player.CameraMaxZoomDistance` for each player who joins the game.
      If this value is set to a lower value than
      `Class.StarterPlayer.CameraMinZoomDistance` it will be increased to
      CameraMinZoomDistance.
    code_samples:
      - setting-camera-zoom-distance
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Camera
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CameraMinZoomDistance
    summary: |
      The minimum distance in studs the player's default camera is allowed to
      zoom in.
    description: |
      This property sets the minimum distance in studs the camera can be from
      the character with the default cameras.

      This property sets the default value of
      `Class.Player.CameraMinZoomDistance` for each player who joins the game.
      If this value is set to a higher value than
      `Class.StarterPlayer.CameraMaxZoomDistance` it will be decreased to
      CameraMaxZoomDistance.
    code_samples:
      - setting-camera-zoom-distance
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Camera
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CameraMode
    summary: |
      Changes the default camera's mode to either first or third person.
    description: |
      Sets the default value for `Class.Player.CameraMode` for each player in
      the game. The camera has two modes:

      ##### First Person

      In first person mode, the player's camera is zoomed all the way in. Unless
      there is a visible GUI present with the `Class.GuiButton.Modal` property
      set to `true`, the mouse will be locked and the user's camera will turn as
      the mouse moves.

      ##### Third Person

      In third person mode (default), the character can be seen in the camera.
      While in third person mode on Roblox:

      - You may right-click and drag to rotate your camera, or use the arrow
        keys at the bottom right-hand corner of the screen.
      - When you move your mouse, your camera does not change (unless you move
        the mouse to the end of the screen).
      - When you press any of the arrow keys, the user's character will face in
        the corresponding arrow key's direction.
      - You can zoom in and out freely.
    code_samples:
      - playing-in-first-person
    type: CameraMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Camera
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CharacterBreakJointsOnDeath
    summary: |
      Determines the starting value of `Class.Humanoid.BreakJointsOnDeath` for
      `Class.Player.Character`.
    description: |
      This property determines the starting value of
      `Class.Humanoid.BreakJointsOnDeath` for a player's
      `Class.Player.Character`.

      Note, `Class.StarterPlayer.AvatarJointUpgrade` must be enabled for
      CharacterBreakJointsOnDeath to take effect.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CharacterJumpHeight
    summary: |
      Determines the starting value of `Class.Humanoid.JumpHeight` for
      `Class.Player.Character`.
    description: |
      This property determines the starting value of `Class.Humanoid.JumpHeight`
      for a player's `Class.Player.Character`. The value of this property
      defaults to 7.2 studs.

      This property is only visible in the Properties window If
      `Class.StarterPlayer.CharacterUseJumpPower` is set to `false`, as it would
      not be relevant otherwise.

      Since this property is only relevant for characters being spawned in the
      future, changing it will not change any existing player characters.
      Changes to this property will only take effect when a player respawns.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character Jump Settings
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CharacterJumpPower
    summary: |
      Determines the starting value of `Class.Humanoid.JumpPower` for
      `Class.Player.Character`.
    description: |
      This property determines the starting value of `Class.Humanoid.JumpPower`
      for a player's `Class.Player.Character`. The value of this property
      defaults to 50 and when applied to the player's `Class.Humanoid` it will
      be constrained between 0 and 1000.

      This property is only visible in the Properties window If
      `Class.StarterPlayer.CharacterUseJumpPower` is set to `true`, as it would
      not be relevant otherwise.

      Since this property is only relevant for characters being spawned in the
      future, changing it will not change any existing player characters.
      Changes to this property will only take effect when a player respawns.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character Jump Settings
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CharacterMaxSlopeAngle
    summary: |
      Determines the starting value of `Class.Humanoid.MaxSlopeAngle` for
      `Class.Player.Character`.
    description: |
      This property determines the starting value of
      `Class.Humanoid.MaxSlopeAngle` for a player's `Class.Player.Character`. It
      defaults to 89°, so humanoids can climb pretty much any slope they want by
      default. When applied to the player's `Class.Humanoid` it will be
      constrained between 0 and 89.

      Since this property is only relevant for characters being spawned in the
      future, changing it will not change any existing player characters.
      Changes to this property will only take effect when a player respawns.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CharacterUseJumpPower
    summary: |
      Determines the starting state of `Class.Humanoid.UseJumpPower` for
      `Class.Player.Character`.
    description: |
      `CharacterUseJumpPower` determines the starting value of
      `Class.Humanoid.UseJumpPower` for a player's `Class.Player.Character`.
      Toggling it will change which property is visible in the properties
      window: `Class.StarterPlayer.CharacterJumpHeight|CharacterJumpHeight`
      (false) or `Class.StarterPlayer.CharacterJumpPower` (true). Defaults to
      true.

      Since this property is only relevant for characters being spawned in the
      future, changing it will not change any existing player characters.
      Changes to this property will only take effect when a player respawns.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character Jump Settings
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CharacterWalkSpeed
    summary: |
      Determines the starting value of `Class.Humanoid.WalkSpeed` for
      `Class.Player.Character`.
    description: |
      This property determines the starting value of `Class.Humanoid.WalkSpeed`
      for a player's `Class.Player.Character`. This property defaults to 16.

      Since this property is only relevant for characters being spawned in the
      future, changing it will not change any existing player characters.
      Changes to this property will only take effect when a player respawns.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.ClassicDeath
    summary: ''
    description: ''
    code_samples: []
    type: boolean
    tags:
      - NotBrowsable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.CreateDefaultPlayerModule
    summary: |
      Controls how the default player module and related scripts are handled.
    description: |
      This property is only visible when
      `Class.Workspace.PlayerScriptsUseInputActionSystem` is enabled. When set
      to `true` (default), the `PlayerModule` injection point occurs at
      `Class.StarterPlayer`. When set to `false`, the default camera and control
      scripts will not be added to the place.
    code_samples: []
    type: boolean
    tags:
      - NotScriptable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Controls
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.DevCameraOcclusionMode
    summary: |
      Sets how the default camera handles objects between the camera and the
      player.
    description: |
      Defines how the default camera scripts handle objects between the camera
      and the camera subject. Applies to all players as they join the experience
      and can't be changed for individual players.

      The default value is `Enum.DevCameraOcclusionMode|Zoom` (0). See
      `Enum.DevCameraOcclusionMode` for a list of available modes.
    code_samples: []
    type: DevCameraOcclusionMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Camera
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.DevComputerCameraMovementMode
    summary: |
      Lets you overwrite the player's camera mode on a computer.
    description: |
      This property lets you overwrite the player's camera mode on a computer.

      If set to `Enum.DevComputerCameraMovementMode|UserChoice`, the player's
      camera movement mode will be determined by whatever they set in the
      experience's settings. Otherwise, the mode will be set based on this
      property.

      This property does not affect players who are not on a computer.
    code_samples: []
    type: DevComputerCameraMovementMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Camera
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.DevComputerMovementMode
    summary: |
      Lets you overwrite the player's movement mode on a computer.
    description: |
      This property lets you overwrite the player's movement mode on a computer.

      If set to `Enum.DevComputerMovementMode|UserChoice`, the player's movement
      mode will be determined by whatever they set in the experience's settings.
      Otherwise, the mode will be set based on this property.

      This property does not affect players who are not on a computer.
    code_samples: []
    type: DevComputerMovementMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Controls
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.DevTouchCameraMovementMode
    summary: |
      Lets you overwrite the player's camera mode on a touch-enabled device.
    description: |
      This property lets you overwrite the player's camera mode on a
      touch-enabled device.

      If set to `Enum.DevTouchCameraMovementMode|UserChoice`, the player's
      camera movement mode will be determined by whatever they set in the
      experience's settings. Otherwise, the mode will be set based on this
      property.

      This property does not affect players who are not on a touch-enabled
      device.
    code_samples: []
    type: DevTouchCameraMovementMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Camera
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.DevTouchMovementMode
    summary: |
      Lets you overwrite the player's movement mode on a touch-enabled device.
    description: |
      Lets you overwrite the player's movement mode on a touch-enabled device.

      If set to `Enum.DevTouchMovementMode|UserChoice`, the player's movement
      mode will be determined by whatever they set in the experience's settings.
      Otherwise, the mode will be set based on this property.

      This property does not affect players who are not on a touch-enabled
      device.
    code_samples: []
    type: DevTouchMovementMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Controls
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.EnableDynamicHeads
    summary: |
      Sets the use of dynamic heads. When true, enables the use of avatar heads
      with facial animation data.
    description: |
      Sets the use of dynamic heads. When true, enables the use of avatar heads
      with facial animation data.
    code_samples: []
    type: LoadDynamicHeads
    tags:
      - NotScriptable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.EnableMouseLockOption
    summary: |
      Determines if a player can toggle mouse lock by default.
    description: |
      This property determines if a player can toggle mouse lock by default.

      Mouselock will lock the player's cursor to the center of the screen.
      Moving the mouse will rotate the `Class.Camera` and `Class.Player` will
      move relative to the current rotation of the camera.

      This property sets the value of `Class.Player.DevEnableMouseLock`.

      Note that shift-lock related APIs are in the process of being deprecated,
      so it's recommended to use `Class.UserInputService.MouseBehavior` instead
      to lock the mouse.
    code_samples:
      - enabling-a-player-s-mouse-lock
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Controls
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.HealthDisplayDistance
    summary: |
      Sets the distance at which this player will see other `Class.Humanoid`
      health bars. If set to 0, the health bars will not be displayed.
    description: |
      This property sets the distance in studs at which this player will see
      other `Class.Humanoid` health bars. If set to 0, the health bars will not
      be displayed. This property is set to 100 studs by default.

      To change the display distance for a player once they join the game, you
      can set the `Class.Player.HealthDisplayDistance` property.

      If a `Class.Humanoid` health bar is visible, you can set the display type
      using `Class.Humanoid.DisplayDistanceType`.
    code_samples:
      - hiding-player-health-and-names
    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: StarterPlayer.LoadCharacterAppearance
    summary: |
      Whether or not the appearance of a player's character should be loaded.
    description: |
      This property sets whether or not the appearance of a player's character
      should be loaded.

      Setting this to `false` results in the player having no clothes (including
      hats), body colors, body packages or anything else related to the
      appearance of the player's avatar. By default, this property is set to
      `true`.

      Setting this to `true` results in the player loading the appearance
      corresponding to the player's `Class.Player.CharacterAppearanceId`.

      If `Class.Player:LoadCharacterWithHumanoidDescriptionAsync()` is used, it
      can be advantageous to set `Class.StarterPlayer.LoadCharacterAppearance`
      to false as the player's avatar is not required as all asset IDs to equip
      on the character will come from the passed in `Class.HumanoidDescription`.
    code_samples:
      - disabling-a-player-s-appearance
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: 'StarterPlayer.LoadCharacterLayeredClothing '
    summary: |
      Indicates whether characters spawning into an experience will have layered
      clothing accessories equipped on them.
    description: |
      Indicates whether characters spawning into an experience will have layered
      clothing accessories equipped on them (Although
      `Class.Workspace.MeshPartHeadsAndAccessories` also need to be enabled in
      the `Class.Workspace`).
    code_samples: []
    type: LoadCharacterLayeredClothing
    tags:
      - NotReplicated
      - NotScriptable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Players
  - name: StarterPlayer.LuaCharacterController
    summary: ''
    description: ''
    code_samples: []
    type: CharacterControlMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Controls
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
  - name: StarterPlayer.NameDisplayDistance
    summary: |
      Sets the distance at which this player will see other `Class.Humanoid`
      names.
    description: |
      Sets the distance at which this player will see other `Class.Humanoid`
      names. If set to `0`, names are hidden. This property is set to `100`
      studs by default.

      To change the display distance for a player once they join the game, you
      can set the `Class.Player.NameDisplayDistance` property.

      If a `Class.Humanoid` name is visible, you can set the display type using
      `Class.Humanoid.DisplayDistanceType`.
    code_samples:
      - hiding-player-health-and-names
    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: StarterPlayer.UserEmotesEnabled
    summary: |
      Determines if user-owned emotes are loaded when loading avatars.
    description: |
      This property determines if user-owned emotes are loaded when loading
      avatars. Setting this property to `false` disables loading. Developers can
      set the property in Studio directly.

      When emote loading is disabled, the emotes UI will still work as long as
      developers choose to use the emotes feature by adding emotes within their
      game.

      See also [Avatar Emotes](../../../characters/emotes.md), an article
      detailing how to control, customize, and play avatar emotes.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Character
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Players
methods: []
events: []
callbacks: []