<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE funcs
  SYSTEM '../../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
<funcs>
  <func>
    <title>SetPlayList</title>
    <category>Music</category>
    <version>4.2 OC</version>
    <syntax>
      <rtype>int</rtype>
      <params>
        <param>
          <type>any</type>
          <name>playlist</name>
          <desc>If this parameter is a string: List of pieces of music to be played. The individual file and category names are separated with semicolons (";"). Wildcards are expanded. If the parameter is left out, the standard playlist is restored. The parameter may also be a proplist with any of the following members:
            <table><rowh><col>Property</col><col>Type</col><col>Meaning</col></rowh>
              <row><col>PlayList</col><col>string</col><col>Same as providing the playlist directly as a string.</col></row>
              <row><col>MusicBreakMin</col><col>int</col><col>Minimum time of silence between two songs in milliseconds. Defaults to 10000.</col></row>
              <row><col>MusicBreakMax</col><col>int</col><col>Maximum time of silence between two songs in milliseconds. Defaults to 10000. A random value between the minimum and maximum is chosen before each new song is selected.</col></row>
              <row><col>MusicBreakChance</col><col>int</col><col>Chance in percent that silence is inserted between two songs. Defaults to 50.</col></row>
              <row><col>MusicMaxPositionMemory</col><col>int</col><col>Time in seconds that the current position in a piece is remembered and will be used for resume if it becomes available through a call to SetPlayList. Defaults to 420. A value of zero means infinite memory.</col></row>
            </table>
          </desc>
          <optional />
        </param>
        <param>
          <type>int</type>
          <name>at_player</name>
          <desc>The playlist is changed only on clients where the player with this player number is local. If left out or NO_OWNER, the playlist is changed for all clients. If the player number is invalid, no playlists are changed.</desc>
          <optional />
        </param>
        <param>
          <type>bool</type>
          <name>force_change</name>
          <desc>If true and the new playlist does not contain the piece currently playing, a new song is selected and played.</desc>
          <optional />
        </param>
        <param>
          <type>int</type>
          <name>fadetime_ms</name>
          <desc>Fade time to the new piece if force_change is true and the current song is changed in response to this call. Set to zero to change music instantly.</desc>
          <optional />
        </param>
        <param>
          <type>int</type>
          <name>resume_time_ms</name>
          <desc>If greater than zero and changing the playlist causes a new piece to be selected immediately, the upcoming piece is resumed from the position where it last stopped playing if at least this amount of time is still left to be played.</desc>
          <optional />
        </param>
      </params>
    </syntax>
    <desc>Sets the play list of pieces of music to be played in random order, if music is activated. The actual number of pieces of music in the playlist is returned, or 0 in network mode.</desc>
    <remark>Pieces are identified either by matching file name or any matching category. Categories are only available for .ogg files and may be set as a semicolon-delimited list in the comment field. Matching is case-insensitive, but case insensitive matching does not work for extended UTF8 characters.</remark>
    <remark>SetPlayList does not activate music playback when the player has turned the music off. If the player enables music, the new playlist takes effect.</remark>
    <remark><code>SetPlayList("*.*")</code> is not identical to <code>SetPlayList()</code>. The former activates all music, the latter only those not starting with "@", the standard behavior.</remark>
    <related><funclink>Music</funclink></related>
  </func>
  <author>PeterW</author><date>2003-01</date>
  <author>Sven2</author><date>2015-09</date>
</funcs>
