Sound module

Module for playing sound effects.

Indexing

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

The sound effects playing now. A slot that is silent still answers, with a stale handle.

Structures

  • trx.sound.SampleNum

    Sample number, in the numbering the loaded level carries. Not a trx.catalog.samples name, which is the sound bank's own. Counted from 0.

  • trx.sound.StreamNum

    Which of the voices playing now, counted in the order the engine holds them. Counted from 1.

  • trx.sound.Sample

    A sound sample the current level carries. Reach them through trx.sound.samples. A handle to a sample 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.sound.SampleNum. (read-only)
    • pitch: integer. The sample's base pitch. (read-only)
    • randomness: integer. How much the sample's playback is randomized. (read-only)
    • range: integer. How far the sample carries. (read-only)
    • volume: integer. The sample's base volume. (read-only)

    Methods:

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

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

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

      Parameters:

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

        Keys:

        • pos (trx.math.Vec3, optional). A world position to play from, which applies pan and volume. Omit to play at full volume.

      Returns: trx.sound.Stream or nil. The voice it started, or nil if none did.

    • sample:stop()
      Stops every voice playing this sample.

  • trx.sound.Stream

    One of the sound effects playing now. Reach them through trx.sound.streams. A handle to a voice that has fallen silent goes stale, so 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:

    Methods:

    • stream:is_valid()
      Whether this voice is still playing.

      Returns: boolean. False once the voice has fallen silent.

    • stream:pause()
      Pauses this voice.

    • stream:stop()
      Stops this voice.

    • stream:unpause()
      Resumes this voice.

Functions

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

    Parameters:

    • id (trx.catalog.samples). Sample to play. To reach a sample by the level's own slot, play it through a handle: trx.sound.samples[slot]:play().

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

      Keys:

      • pos (trx.math.Vec3, optional). A world position to play from, which applies pan and volume. Omit to play at full volume.

    Returns: trx.sound.Stream or nil. The voice it started, or nil if none did.

    Example:

    trx.sound.play(trx.catalog.samples.LARA_NO)
trx.sound.play(trx.catalog.samples.LARA_NO, { pos = { x = 100, y = 200, z = 50 } })

  • trx.sound.stop(id)
    Stops a sound effect by catalog id.

    Parameters:

    • id (trx.catalog.samples). Sample to stop. To reach a sample by the level's own slot, stop it through a handle: trx.sound.samples[slot]:stop().

  • trx.sound.stop_all()
    Stops every sound effect currently playing.