StudioDeviceSimulatorService
Service allowing you to control Studio's Device Simulator.
Its interface does not cross the network boundary.
Instances of this class cannot be created with Instance.new.
It is a singleton that may be acquired with GetService.
Tags: [NotCreatable, Service, NotReplicated]
Provides programmatic control over Studio's Device Simulator. Use this service
to switch between device presets, override resolution and pixel density,
control orientation and scaling, and manage custom device profiles from a
plugin or from an external tool connected through the MCP server.
All methods are asynchronous and yield the calling coroutine. The service is
available in Edit mode and Play Client. Methods that modify the active
simulation state are blocked in PlayServer mode.
Limitations
- All methods are asynchronous and yield the calling coroutine.
- Methods that modify the active simulation state (
SetDeviceAsync,
StopSimulationAsync, SetOrientationAsync, SetResolutionAsync,
SetPixelDensityAsync, SetScalingModeAsync) error in PlayServer mode.
They work in Edit mode and Play Client. UpdateDeviceAsync and RemoveDeviceAsync error when called on built-in
presets.- Resolution, DPI, and scaling mode methods require an active device and error
when
GetDeviceAsync() returns "default". - Resolution and DPI overrides are session-level. They are not persisted and
are cleared on
SetDeviceAsync. - Built-in presets are immutable.
| Parameters (0) |
|---|
| No parameters. |
Fires when the active simulation state changes: device switch,
orientation, resolution, pixel density, scaling mode, or user interaction
with the Device Simulator UI. Does not fire for catalog-only operations
such as CreateDeviceAsync, UpdateDeviceAsync on a non-active device,
RemoveDeviceAsync on a non-active device, or GetDeviceInfoAsync.
Getter calls inside the handler are async and will yield.
History 1
Creates a custom device and returns its newly assigned ID. Custom devices
are persisted to disk and appear in the Device Simulator UI.
Errors if any required field is missing or out of range.
It will block the calling thread until completion.
History 1
Tags: [Yields]
| Parameters (0) |
|---|
| No parameters. |
| Returns (1) |
|---|
| string |
Returns the ID of the currently active device, or "default" if no device
is active.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Returns a DeviceConfiguration for the specified device without
activating it. Useful for inspecting presets before choosing one to switch
to.
The returned dictionary contains the following fields:
| Field | Type | Create/Update | Description |
|---|
DeviceId | string | Read-only | Unique identifier assigned by the service. |
Name | string | Required | Display name. 1 to 200 characters. Cannot be "default". |
Width | number | Required | Screen width in pixels. Range: 1 to 7680. |
Height | number | Required | Screen height in pixels. Range: 1 to 4320. |
PixelDensity | number | Required | Pixel density in DPI. Range: 72 to 10000. |
DeviceForm | DeviceForm | Optional (default: Phone) | One of Phone, Tablet, Desktop, Console, VR. |
IsCustom | boolean | Read-only | true if the device was user-created. |
ResolutionScale | number | Optional (default: 1.0) | Resolution scaling factor. Must be greater than 0, max 10.0. |
PortraitKeyboardHeight | number | Optional (default: 0) | Virtual keyboard height in portrait mode. |
LandscapeKeyboardHeight | number | Optional (default: 0) | Virtual keyboard height in landscape mode. |
It will block the calling thread until completion.
History 1
Tags: [Yields]
| Parameters (0) |
|---|
| No parameters. |
| Returns (1) |
|---|
| Array |
Returns an array of device IDs for all available presets, including
built-in and custom devices.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Returns the current simulated orientation.
It will block the calling thread until completion.
History 1
Tags: [Yields]
| Parameters (0) |
|---|
| No parameters. |
| Returns (1) |
|---|
| float |
Returns the current simulated pixel density.
It will block the calling thread until completion.
History 1
Tags: [Yields]
| Parameters (0) |
|---|
| No parameters. |
| Returns (1) |
|---|
| Vector2 |
Returns the current simulated resolution.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Returns the current scaling mode.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Removes a custom device.
Errors if the target is a built-in preset.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Activates the specified device. Passing "default" stops simulation and
is equivalent to calling StopSimulationAsync.
Errors in PlayServer mode. Errors if the device ID does not exist.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Sets or gets the simulated screen orientation. Accepts Portrait,
LandscapeLeft, or LandscapeRight. Other values will error.
Errors in PlayServer mode.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Overrides or returns the simulated pixel density in DPI. Session-level;
cleared on device switch.
This method requires an active device. SetPixelDensityAsync also errors
in PlayServer mode.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Overrides the simulated viewport resolution or returns the current
resolution as a Vector2. Overrides are session-level and cleared when you
switch devices.
Coordinates are in landscape space: the first parameter maps to the
horizontal axis in landscape, the second to the vertical axis. In
portrait, axes are swapped automatically.
Both methods require an active device. They error if GetDeviceAsync()
returns "default". SetResolutionAsync also errors in PlayServer mode.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Controls how the simulated resolution maps to the Studio viewport.
ScaleToPhysicalSize scales the viewport to approximate physical device
size.ActualResolution renders at exact pixel resolution.FitToWindow scales to fill the viewport.
Both methods require an active device. SetScalingModeAsync also errors
in PlayServer mode.
It will block the calling thread until completion.
History 1
Tags: [Yields]
| Parameters (0) |
|---|
| No parameters. |
| Returns (1) |
|---|
| null |
Stops the active simulation. Prefer this over SetDeviceAsync("default")
for clarity.
Errors in PlayServer mode.
It will block the calling thread until completion.
History 1
Tags: [Yields]
Updates a custom device's configuration.
Errors if the target is a built-in preset.
It will block the calling thread until completion.
History 1
Tags: [Yields]