The media system

Schedule skybox and music @media labels defined in MAST.

Overview

Media labels are declared in MAST with the @media/kind/path "Display" syntax and discovered at runtime. media_schedule and media_schedule_random look up registered labels by kind ("skybox" or "music") and apply them via the engine's set_sky_box / set_music_folder calls, then run the label as a sub-task.

The ID parameter targets a specific ship or client; 0 (the default) applies the change globally on the server.

Use skybox_schedule / music_schedule as convenient wrappers when you already know the media name; use the _random variants to pick from all registered labels of that kind automatically.

Quick example

MAST pyMAST

@media/skybox/nebula "Nebula"
@media/skybox/deep_space "Deep Space"
@media/music/battle "Battle Music"

== setup ==
skybox_schedule_random()
music_schedule("battle")

from sbs_utils.procedural.media import (
    skybox_schedule, skybox_schedule_random,
    music_schedule, music_schedule_random,
)

# Pick a specific skybox
skybox_schedule("nebula")

# Pick a random skybox
skybox_schedule_random()

# Ship-specific music (pass ship ID)
music_schedule("battle", ID=ship_id)

# Random music for server
music_schedule_random()

API

`media_schedule(kind, name, ID=0)`

Schedule a named @media label of the given kind.

Parameters:

Name	Type	Description	Default
`kind`	`str`	Media kind, e.g. `"skybox"` or `"music"`.	required
`name`	`str \| MediaLabel`	Media path name or a `MediaLabel` object.	required
`ID`	`int`	Ship or client ID; `0` targets the server. Defaults to 0.	`0`

Returns:

Type	Description
	Label \| None: The scheduled label, or `None` if not found.

`media_schedule_random(kind, ID=0)`

Schedule a randomly chosen @media label of the given kind.

Parameters:

Name	Type	Description	Default
`kind`	`str`	Media kind, e.g. `"skybox"` or `"music"`.	required
`ID`	`int`	Ship or client ID; `0` targets the server. Defaults to 0.	`0`

Returns:

Type	Description
	Label \| None: The scheduled media label, or `None` if none exist.

`music_schedule(name, ID=0)`

Schedule a specific music track by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Music media path name.	required
`ID`	`int`	Ship or client ID; `0` targets the server. Defaults to 0.	`0`

`music_schedule_random(ID=0)`

Schedule a randomly chosen music @media label.

Parameters:

Name	Type	Description	Default
`ID`	`int`	Ship or client ID; `0` targets the server. Defaults to 0.	`0`

`skybox_schedule(name, ID=0)`

Schedule a specific skybox by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Skybox media path name.	required
`ID`	`int`	Ship or client ID; `0` targets the server. Defaults to 0.	`0`

`skybox_schedule_random(ID=0)`

Schedule a randomly chosen skybox @media label.

Parameters:

Name	Type	Description	Default
`ID`	`int`	Ship or client ID; `0` targets the server. Defaults to 0.	`0`