Models, screens and presets — PMMS

Add models usable as media players, show video on a renderTarget or a scaleform, define presets and place default media players that start with PMMS.

Goal: choose which entities act as media players, where video shows, and which media are offered. File: pmms/config.lua, or in game with the pmms.manage permission.

Add a model

Each Config.models entry is keyed by the model hash (CfxLua `name` syntax):

Config.models = {
    [`prop_boombox_01`] = {
        label = "Boombox"
    },
    [`prop_tv_flat_01`] = {
        label = "TV",
        renderTarget = "tvscreen"
    },
    [`pbus2`] = {
        attenuation = { sameRoom = 1.5, diffRoom = 6 },
        range = 100,
        isVehicle = false
    },
}

Field	Effect
`label`	Name shown in the panel.
`renderTarget`	Name of the model screen’s render target: video shows there through DUI. Without it, video shows in a NUI frame above the entity.
`filter`, `volume`, `attenuation`, `diffRoomVolume`, `range`	Settings offered by default for this model.
`isVehicle`	Treat the entity as a vehicle (outside counts as another room) or not. Absent: determined automatically. `pbus2` and `blimp3` ship with `false`, so they are heard from outside like objects.
`scaleform`	Associated scaleform screen (position, rotation, scale).

Result: after restart pmms, the entity shows in the panel when you are within Config.maxDiscoveryDistance.

The renderTarget name depends on the model: it must match a render target that really exists in the model. A wrong name leaves the screen black without an explicit error. The 102 shipped screens use for example tvscreen, ex_tvscreen, cinscreen, big_disp, tablet or npcphone.

Save a model in game

With pmms.manage, the panel can save the targeted entity’s settings for the model or for this entity. From the server console:

pmms_add prop_boombox_01 Speaker

These settings are written to models.json (models) and defaultMediaPlayers.json (entities), and reloaded at start on top of config.lua. The addModelPermanently and addEntityPermanently exports do the same from a script (see API).

Presets

A preset is a predefined media, picked by name:

Config.presets = {
    ['lobby'] = { url = 'https://example.com/music/lobby.ogg', title = 'Lobby music', filter = false, video = false },
    ['news'] = { url = 'https://www.youtube.com/watch?v=XXXXXXXXXXX', title = 'News', video = true },
}

example.com and the YouTube ID are examples. url is required; title, filter and video are optional. The player types /pmms_play lobby, or /pmms_play random for a random preset; /pmms_presets lists them in the chat.

Without the pmms.customUrl permission, a player can only play presets.

Default media players

The players in Config.defaultMediaPlayers are known to the server from start:

Config.defaultMediaPlayers = {
    {
        position = vector3(-1388.5, -618.2, 30.8),
        label = "Bar — speaker",
        spawn = true,
        model = `prop_boombox_01`,
        rotation = vector3(0.0, 0.0, 120.0),
        url = 'lobby',
        volume = 60,
        loop = false,
        filter = false,
        locked = true,
        range = 25
    },
}

The coordinates are an example.

Field	Effect
`position`	Required. Entity position; also the player’s identifier.
`spawn`	`true`: the entity is created around players within `Config.defaultMediaPlayerSpawnDistance`. Absent: an entity must already exist at this exact position.
`model`, `rotation`, `invisible`	Entity created when `spawn = true`; `model` absent: `Config.defaultModel`.
`url`	URL, preset name or `random`. When present, the media starts with the resource.
`title`, `volume`, `offset`, `loop`, `filter`, `video`, `videoSize`, `muted`, `attenuation`, `diffRoomVolume`, `range`	Media settings (see playback options).
`locked`	`true`: only players with `pmms.manage` can control this player.
`scaleform`	Scaleform screen: `{ position, rotation, scale, standalone, attached }`.

Result: when pmms starts, the speaker appears in the bar and plays the lobby preset, locked for players without pmms.manage.

Free-standing scaleform screen

To show a video on a wall or a board without a screen in the model, use a scaleform. The shipped scaleform is pmms_texture_renderer (stream/pmms_texture_renderer.gfx). The panel offers “Ma position” (my position) to fill position and rotation from your character; the startScaleform server export does the same by script.

Common mistakes

Entity missing from the panel: model not listed, entity further than maxDiscoveryDistance, or player without pmms.anyEntity.
Default media player with no effect and spawn absent: no entity exists exactly at position.
Black screen: wrong renderTarget for this model, or unreachable DUI page.
Settings lost after an update: models.json and defaultMediaPlayers.json overwritten by the new archive’s empty files.