Music module

Module for playing and controlling the soundtrack.

Indexing

The soundtrack's streams: [1] is the main stream, [2] onwards the overlay slots. A slot that is not playing still answers, with a stale handle.

• trx.music.streams[key] (key: trx.music.StreamNum, value: trx.music.Stream or nil).
• #trx.music.streams (integer). How many there are.

The tracks the current level carries. A level does not carry every number, so indexing one it lacks is nil and iterating passes it by.

• trx.music.tracks[key] (key: trx.music.TrackNum, value: trx.music.Track or nil).
• #trx.music.tracks (integer). How many there are.

Properties

• trx.music.current_track (trx.music.Track). The track playing now, or nil when nothing plays. (read-only)
• trx.music.looped_track (trx.music.Track). The ambient track that resumes once the current one-shot finishes, or nil when none is set. (read-only)

Enums

• trx.music.PlayMode

  How a track is played. Pass one as trx.music.play.opts.mode.

  • trx.music.PlayMode.ONCE = 0
    Plays the track once. When it finishes, any active looped track resumes from its start.
  • trx.music.PlayMode.LOOP = 1
    Plays the track continuously. It becomes the ambient track.
  • trx.music.PlayMode.DELAY = 2
    Marks the track for later playback rather than starting it now.
  • trx.music.PlayMode.NO_REPEAT = 3
    Plays the track once, but does not retrigger it if it is already playing.
  • trx.music.PlayMode.OVERLAY = 4
    Plays the track on top of the current one.

Structures

• trx.music.TrackNum

  Track number, in the numbering the loaded level carries. Not a trx.catalog.music name, which is the soundtrack's own. Counted from 0.

• trx.music.StreamNum

  Which of the soundtrack's slots: 1 is the main stream, 2 onwards the overlays. Counted from 1.

• trx.music.Stream

  One of the soundtrack's playing streams: the main stream, or an overlay. Reach them through trx.music.streams. A handle to a slot that is not playing goes stale, so reading a field or calling a method on it raises; check is_valid first.

  Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.

  Properties:

  • mode: trx.music.PlayMode. How the track is playing. (read-only)
  • timestamp: trx.game.Seconds. How far into the track the stream is. (read-only)
  • track_num: trx.music.TrackNum. The track this stream is playing. (read-only)

  Methods:

  • stream:is_valid()
    Whether the slot is still playing. A stream that has finished, or been stopped, leaves its handle stale.

    Returns: boolean. False once the slot has gone quiet.

  • stream:pause()
    Pauses this stream.

  • stream:seek(timestamp)
    Seeks this stream to a timestamp.

    Parameters:

    • timestamp (trx.game.Seconds). Where to seek to.

    Returns: boolean. Whether the seek took.

  • stream:stop()
    Stops this stream. Stopping the main stream lets a deferred ambient loop resume; an overlay just ends.

  • stream:unpause()
    Resumes this stream.

• trx.music.Track

  A track the current level carries. Reach them through trx.music.tracks, or as trx.music.current_track. A handle to a track the loaded level does not carry goes stale, so is_valid answers whether it is still there.

  Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.

  Properties:

  • num: trx.music.TrackNum. (read-only)

  Methods:

  • track:is_valid()
    Whether the loaded level still carries this track.

    Returns: boolean. False once a level change has replaced the tracks.

  • track:path()
    Resolves the track's file path.

    Returns: string or nil. nil when there is no file, e.g. a CD-audio soundtrack.

  • track:play([opts])
    Plays this track.

    Parameters:

    • opts (table, optional). How to play it.

      Keys:

      • mode (trx.music.PlayMode, optional). Plays once by default.

    Returns: trx.music.Stream or nil. The stream it started, or nil if none did.

Functions

• trx.music.play(id, [opts])
  Plays a track by catalog id, mapping it to the level's own track. A game that does not carry the track plays nothing.

  Parameters:

  • id (trx.catalog.music). Track to play. To reach a track by the level's own slot, play it through a handle: trx.music.tracks[slot]:play().

  • opts (table, optional). How to play it.

    Keys:

    • mode (trx.music.PlayMode, optional). Plays once by default.

  Returns: trx.music.Stream or nil. The stream it started, or nil if none did.

  Example:

  trx.music.play(trx.catalog.music.SECRET)
  trx.music.play(trx.catalog.music.SECRET, { mode = trx.music.PlayMode.LOOP })
  

• trx.music.pause()
  Pauses the music.

• trx.music.unpause()
  Resumes paused music.

• trx.music.stop()
  Stops all music.