API

Numbers that appear in square brackets indicate the minimum version of PlayX required for that feature.

Server-side API

Variables

These are immutable.

table PlayX.CurrentMedia = nil

If something is playing, this variable will contain a table with the following keys:

• Handler: Assigned handler to play the media.
• URI: URI for the handler.
• StartTime: Number of seconds since the server start (found via CurTime()) that the video started at. If the media was skipped to a position, then this time would have been shifted backwards by the number of seconds skipped. Note: The behavior of this key may change in the future.
• ResumeSupported: Boolean indicating whether the media can be resumed.
• LowFramerate: Boolean indicating the status of low frame rate mode.
• StopTime: Number of seconds since the server start (found via CurTime()) that the video should end at. Note: The behavior of this key may change in the future. May be nil if no stop time is set.
• HandlerArgs: Additional arguments for the handler.
• Length: [1.1] Length of the media, in seconds. May be nil if the length is not known.
• Provider: [1.1] Provider. May be nil if not known.
• Identifier: [1.1] Identifier provided by a provider. May be nil if not known.
• Title: [1.1] Title of the media. May be nil if not known.

bool PlayX.AdminTimeoutTimerRunning = false

Whether the administrator timeout timer is running.

Functions

bool PlayX.PlayerExists()

This function returns true if there is an instance of the PlayX player entity.

Entity PlayX.GetInstance()

The PlayX player entity is returned if it exists; nil is returned otherwise. The class name of the PlayX entity is gmod_playx.

bool PlayX.IsUsingJW()

Returns whether the JW player is enabled.

string PlayX.GetJWURL()

Returns the URL of the JW player being used. This may return an empty string, but it should not return nil.

bool PlayX.JWPlayerSupportsYouTube()

Returns whether the JW player is configured for YouTube. Note that the return of this function can still be true even if PlayX.IsUsingJW() returns false.

bool PlayX.IsPermitted(Entity ply)

Checks whether to see a user is permitted to use PlayX. By default, this function will return true for administrators and super administrators, and false for everyone else. This behavior can be overridden by defining a particular callback (see Callbacks).

Parameters:

• ply: A player entity.

void PlayX.SpawnForPlayer(Entity ply, string model)

Create a PlayX player where a user is looking. The model path can be of any usable model, but it is best if you use a model with a defined screen (see Defining Screens). However, PlayX will use an algorithm to lay a screen over the model if a screen has not been defined for it. Do not depend on the algorithm from not changing in the future, however.

This function will make sure that a PlayX player isn’t already spawned, but it will not check to see whether the user has permissions to spawn the player. true will be returned if the operation was successful, otherwise false will be returned, followed by an error message as a string.

Parameters:

• ply: A player entity.
• model: The model to use.

void PlayX.OpenMedia(string provider, string uri, number start, bool forceLowFramerate, bool useJW, number ignoreLength)

Plays media. This is the function that you want to, and should call, if you want to play something. This function will return the table returned from the provider if successful, otherwise false as the first returned value, followed by the error message as a string written in English as the 2nd returned value. If you provide information about a piece of media that PlayX does not know how to play, an error will be returned. If there is no PlayX player is spawned (PlayX.PlayerExists() will return false), then the function will return an error. No permission checks are done in this function.

Parameters:

• provider: The name of a registered provider, or an empty string to use auto-detection.
• uri: The URI to pass to the provider.
• start: Number of seconds to skip in the video; optional; can be nil to indicate that the media should be played from the beginning.
• forceLowFramerate: Whether to force the playing media into low frame rate mode; optional; can be nil to indicate that low frame rate mode should not be on.
• useJW: Specify whether the JW player should be used; optional; can be “nil,” which will use the default option: use the JW player.
• ignoreLength: Specify whether to ignore the length of the video and disable the auto-close on video end feature. This parameter has no effect if the auto-close on video end feature is not enabled.

void PlayX.CloseMedia()

Stops whatever is currently playing. This function checks to see whether something is currently playing, and will do nothing, silently, if nothing was playing.

void PlayX.SetCurrentMediaLength(length)

This sets the length of the currently playing. The information is for metadata purposes, and calling this function is not required. Some providers have support for automatically fetching the length of a piece of media, so you do not need to call this function.

However, information about a video’s length is required in order for the auto-close media on end feature to function. If length information is not provided, then PlayX will not do anything.

void PlayX.BeginMedia(string handler, string uri, number start, number resumeSupported, bool lowFramerate, number length, table handlerArgs, [1.1] string provider, [1.1] string identifier, [1.1] string title)

This function is deeper in the procedure for calling a video — it prepares the media for being played, it sets the “current playing media” state, and it will tell clients about the media that now needs to be played. Generally, you do not need to call this function, as you can get by by calling PlayX.OpenMedia. However, you may want to call this function if you want to skip the whole provider identification stage and directly play a video using a handler of choice. See the Concepts page to understand the difference between a provider and a handler.

Note that this function does not check to see if there is a PlayX player spawned, nor does it know if the particular combination of handler, URI, and handler arguments is supported by the client. Therefore, you must be careful.

Parameters:

• handler: The name of the handler is used.
• uri: URI to be passed to the handler.
• start: Number of seconds to skip. This value must be a number.
• resumeSupported: Whether resume is supported. Required argument.
• lowFramerate: Whether to use low framerate mode. Required argument.
• length: The length of the video in seconds. Must be a number greater than or equal to 0. Required argument.
• handlerArgs: Additional arguments for the handler. Required argument.
• provider: [1.1] Name of provider. Must be a string, but can be empty.
• identifier: [1.1] Identifier. Must be a string, but can be empty.
• title: [1.1] Title of the media. Must be a string, but can be empty.

void PlayX.EndMedia()

Analogous to PlayX.BeginMedia(), except this function ends the currently playing media. This function does not check to see whether something is playing.

void PlayX.SendBeginDStream(Entity ply)

Function to send the necessary message(s) to inform a client that media is beginning. This is an internal function, and you should not need to call it. This function will not handle well if it is called after some time has passed since the media has started (it will not compensate for that).

Parameters:

• ply: A player entity.

void PlayX.SendEndUMsg()

Function to send the necessary message(s) to inform a client that nothing is playing now. This is an internal function, and you should not need to call it.

void PlayX.SendSpawnDialogUMsg(Entity ply)

Sends a message to a player that causes the PlayX model selection dialog to appear.

Parameters:

• ply: A player entity.

Client-side API

Variables

These are immutable.

bool PlayX.Enabled = true

Whether the PlayX player is enabled.

bool PlayX.Playing = false

Whether something is playing.

table PlayX.CurrentMedia = nil

If something is playing, this variable will contain a table with the following keys:

• Handler: Assigned handler to play the media.
• URI: URI for the handler.
• StartTime: Number of seconds since the server start (found via CurTime()) that the video started at. If the media was skipped to a position, then this time would have been shifted backwards by the number of seconds skipped. Note: The behavior of this key may change in the future.
• ResumeSupported: Boolean indicating whether the media can be resumed.
• LowFramerate: Boolean indicating the status of low frame rate mode.
• HandlerArgs: Additional arguments for the handler.

bool PlayX.SeenNotice = false

Used by PlayX to remember whether it has shown the introductory message about PlayX to the user.

string PlayX.JWPlayerURL = ""

The URL, provided by the server, to use for the JW player.

Functions

bool PlayX.PlayerExists()

This function returns true if there is an instance of the PlayX player entity.

entity PlayX.GetInstance()

The PlayX player entity is returned if it exists; nil is returned otherwise. The class name of the PlayX entity is gmod_playx.

string PlayX.GetHTML()

The HTML currently present in the player will be returned. If PlayX player does not exist, then nil will be returned. If nothing is playing, then either nil, an empty string, or a string containing HTML/text may be returned. This function is primarily for debugging purposes.

void PlayX.Enable()

The player will be enabled for the client. If the player was already enabled, then nothing will occur. If the player was disabled, and there was something playing, then play/resume will occur immediately, unless the current media does not support resuming.

void PlayX.Disable()

Disable the player for the client. The media will stop playing.

number PlayX.GetPlayerFPS()

Gets the set FPS of the screen.

void PlayX.SetPlayerFPS(number fps)

Sets the FPS of the screen.

Parameters:

• fps: Frames per second to set to.

number PlayX.GetPlayerVolume()

Gets the client-side volume of the player. This will be a number between 0 and 100, or 0 or 100.

void PlayX.SetPlayerVolume(number volume)

Set the volume of the player. The volume should be a number no less than 0 and no greater than 100. However, the function will accept any value. When the value is read, the volume will be clamped to that range, however. Changing the volume has no effect unless something else is played or the player is re-intiialized. The player can be re-initialized with PlayX.ResumePlay().

Parameters:

• volume: Volume to set to.

void PlayX.ResumePlay()

Re-initializes/resumes play. The function will check to see whether a PlayX player is spawned, whether there is something currently being played, and whether the current media can be resumed. If an error occurs, a message oriented to the user will be printed to chat, but there is no programmatic way to detect success. You can, however, perform the checks yourself before calling this function.

void PlayX.HidePlayer()

Stops playing (for the current playing media) and hides the screen. The function will check to see whether a PlayX player is spawned and whether there is something currently being played. If an error occurs, a message oriented to the user will be printed to chat, but there is no programmatic way to detect success. You can, however, perform the checks yourself before calling this function.

void PlayX.ResetRenderBounds()

Reset the render bounds of the entity. PlayX must set the render bounds of the entity to be large so that the screen will appear even if the entity is not in sight. This applies to the projectors. While PlayX will automatically set the render bounds appropriately, you can call this function to reset it." The function will check to see whether a PlayX player is spawned and whether the current screen is a projector. If an error occurs, a message oriented to the user will be printed to chat, but there is no programmatic way to detect success. You can, however, perform the checks yourself before calling this function.

void PlayX.RequestOpenMedia(string provider, string uri, number start, bool lowFPS, bool useJW)

Send a request to the server to play something. The user must have appropriate permissions to be able to play something, and a PlayX player must have already been spawned. If an error occurs, the server will print an error message to the client’s chat.

Parameters:

• provider: The name of a provider registered on the server, or an empty string to use auto-detection.
• uri: The URI to pass to the provider.
• start: Number of seconds to skip in the video; optional; can be nil to indicate that the media should be played from the beginning.
• lowFPS: Whether to force the playing media into low frame rate mode; optional; can be nil to indicate that low frame rate mode should not be on.
• useJW: Specify whether the JW player should be used; optional; can be “nil,” which will use the default option: use the JW player.

void PlayX.RequestCloseMedia()

Send a request to the server to stop playing. The user must have appropriate permissions to be able to play something. No other checks are performed (a bug). If an error occurs, the server will print an error message to the client’s chat.

void PlayX.OpenSpawnDialog()

Open the spawn dialog for the client. The dialog will always show, but the player must have permissions in order to spawn a player.