Merge pull request #2912 from ivan-mogilko/363--audioplayastype

Script API: Add AudioClip.PlayAsType() and Game.PlayVoiceClipAsType()

Author: ivan-mogilko

Common/ac/common_defines.h

@@ -129,4 +129,10 @@
 // An identifier of a "null font", a pseudo font used when you don't want a text to be drawn
 #define FONT_NULL (-1)
 
+#define AUDIOTYPE_UNDEFINED -1
+#define AUDIOTYPE_SPEECH 0
+#define AUDIOTYPE_LEGACY_AMBIENT_SOUND 1
+#define AUDIOTYPE_LEGACY_MUSIC 2
+#define AUDIOTYPE_LEGACY_SOUND 3
+
 #endif // __AC_DEFINES_H

Common/ac/dynobj/scriptaudioclip.cpp

@@ -14,9 +14,49 @@
 
 #include "ac/dynobj/scriptaudioclip.h"
 #include "util/stream.h"
+#include "util/string_compat.h"
 
 using namespace AGS::Common;
 
+/*static*/ AudioFileType ScriptAudioClip::GetAudioFileTypeFromExt(const char *ext)
+{
+    if (ags_stricmp(ext, "mp3") == 0)
+        return eAudioFileMP3;
+    else if (ags_stricmp(ext, "wav") == 0)
+        return eAudioFileWAV;
+    else if (ags_stricmp(ext, "voc") == 0)
+        return eAudioFileVOC;
+    else if (ags_stricmp(ext, "mid") == 0)
+        return eAudioFileMIDI;
+    else if ((ags_stricmp(ext, "mod") == 0) || (ags_stricmp(ext, "xm") == 0)
+             || (ags_stricmp(ext, "s3m") == 0) || (ags_stricmp(ext, "it") == 0))
+        return eAudioFileMOD;
+    else if (ags_stricmp(ext, "ogg") == 0)
+        return eAudioFileOGG;
+    return eAudioFileUndefined;
+}
+
+/*static */ const char *ScriptAudioClip::GetExtFromAudioFileType(AudioFileType filetype)
+{
+    switch (filetype)
+    {
+    case eAudioFileOGG:
+        return "ogg";
+    case eAudioFileMP3:
+        return "mp3";
+    case eAudioFileWAV:
+        return "wav";
+    case eAudioFileVOC:
+        return "voc";
+    case eAudioFileMIDI:
+        return "mid";
+    case eAudioFileMOD:
+        return "mod";
+    default:
+        return "";
+    }
+}
+
 void ScriptAudioClip::ReadFromFile(Stream *in)
 {
     id = in->ReadInt32();

Common/ac/dynobj/scriptaudioclip.h

@@ -18,12 +18,15 @@
 #ifndef __AGS_CN_DYNOBJ__SCRIPTAUDIOCLIP_H
 #define __AGS_CN_DYNOBJ__SCRIPTAUDIOCLIP_H
 
+#include "ac/common_defines.h"
 #include "util/string.h"
 
 namespace AGS { namespace Common { class Stream; } }
 using namespace AGS; // FIXME later
 
-enum AudioFileType {
+enum AudioFileType
+{
+    eAudioFileUndefined = 0,
     eAudioFileOGG = 1,
     eAudioFileMP3 = 2,
     eAudioFileWAV = 3,
@@ -44,17 +47,21 @@ enum AudioClipBundle
 #define LEGACY_AUDIOCLIP_SCRIPTNAMELENGTH    30
 #define LEGACY_AUDIOCLIP_FILENAMELENGTH      15
 
-struct ScriptAudioClip {
-    int id = 0;
+struct ScriptAudioClip
+{
+    int id = -1;
     Common::String scriptName;
     Common::String fileName;
     uint8_t bundlingType = kAudioBundle_Undefined;
-    uint8_t type = 0;
-    AudioFileType fileType = eAudioFileOGG;
+    uint8_t type = AUDIOTYPE_UNDEFINED;
+    AudioFileType fileType = eAudioFileUndefined;
     char defaultRepeat = 0;
     short defaultPriority = 50;
     short defaultVolume = 100;
 
+    static AudioFileType GetAudioFileTypeFromExt(const char *ext);
+    static const char *GetExtFromAudioFileType(AudioFileType filetype);
+
     void ReadFromFile(Common::Stream *in);
 };
 

Common/ac/gamesetupstruct.cpp

@@ -44,7 +44,7 @@ void AdjustFontInfoUsingFlags(FontInfo &finfo, const uint32_t flags)
     }
 }
 
-ScriptAudioClip* GetAudioClipForOldStyleNumber(GameSetupStruct &game, bool is_music, int num)
+const ScriptAudioClip* GetAudioClipForOldStyleNumber(GameSetupStruct &game, bool is_music, int num)
 {
     String clip_name;
     if (is_music)

Common/ac/gamesetupstruct.h

@@ -163,6 +163,6 @@ void ConvertOldGameStruct (OldGameSetupStruct *ogss, GameSetupStruct *gss);
 #endif // OBSOLETE
 
 // Finds an audio clip using legacy convention index
-ScriptAudioClip* GetAudioClipForOldStyleNumber(GameSetupStruct &game, bool is_music, int num);
+const ScriptAudioClip* GetAudioClipForOldStyleNumber(GameSetupStruct &game, bool is_music, int num);
 
 #endif // __AGS_CN_AC__GAMESETUPSTRUCT_H

Common/core/assetmanager.h

@@ -72,6 +72,8 @@ struct AssetPath
     String Filter;
 
     AssetPath(const String &name = "", const String &filter = "") : Name(name), Filter(filter) {}
+
+    operator bool() const { return !Name.IsEmpty(); }
 };
 
 // AssetLibEntry describes AssetLibrary registered in the AssetManager,

Common/game/main_game_file.cpp

@@ -425,43 +425,31 @@ void BuildAudioClipArray(const std::vector<String> &assets, std::vector<ScriptAu
     int temp_number;
     char temp_extension[10];
 
-    // FIXME: use audio type constants instead of obscure numeric literals
     for (const String &asset : assets)
     {
         if (sscanf(asset.GetCStr(), "%5s%d.%3s", temp_name, &temp_number, temp_extension) != 3)
             continue;
 
-        ScriptAudioClip clip;
-        if (ags_stricmp(temp_extension, "mp3") == 0)
-            clip.fileType = eAudioFileMP3;
-        else if (ags_stricmp(temp_extension, "wav") == 0)
-            clip.fileType = eAudioFileWAV;
-        else if (ags_stricmp(temp_extension, "voc") == 0)
-            clip.fileType = eAudioFileVOC;
-        else if (ags_stricmp(temp_extension, "mid") == 0)
-            clip.fileType = eAudioFileMIDI;
-        else if ((ags_stricmp(temp_extension, "mod") == 0) || (ags_stricmp(temp_extension, "xm") == 0)
-            || (ags_stricmp(temp_extension, "s3m") == 0) || (ags_stricmp(temp_extension, "it") == 0))
-            clip.fileType = eAudioFileMOD;
-        else if (ags_stricmp(temp_extension, "ogg") == 0)
-            clip.fileType = eAudioFileOGG;
-        else
+        AudioFileType file_type = ScriptAudioClip::GetAudioFileTypeFromExt(temp_extension);
+        if (file_type == eAudioFileUndefined)
             continue;
 
+        ScriptAudioClip clip;
+        clip.fileType = file_type;
         if (ags_stricmp(temp_name, "music") == 0)
         {
             clip.scriptName.Format("aMusic%d", temp_number);
             clip.fileName.Format("music%d.%s", temp_number, temp_extension);
             clip.bundlingType = (ags_stricmp(temp_extension, "mid") == 0) ? kAudioBundle_GamePak : kAudioBundle_AudioVox;
-            clip.type = 2;
+            clip.type = AUDIOTYPE_LEGACY_MUSIC;
             clip.defaultRepeat = 1;
         }
         else if (ags_stricmp(temp_name, "sound") == 0)
         {
             clip.scriptName.Format("aSound%d", temp_number);
             clip.fileName.Format("sound%d.%s", temp_number, temp_extension);
             clip.bundlingType = kAudioBundle_GamePak;
-            clip.type = 3;
+            clip.type = AUDIOTYPE_LEGACY_SOUND;
             clip.defaultRepeat = 0;
         }
         else
@@ -719,7 +707,7 @@ void RemapLegacySoundNums(GameSetupStruct &game, std::vector<ViewStruct> &views,
     game.scoreClipID = -1;
     if (game.options[OPT_SCORESOUND] > 0)
     {
-        ScriptAudioClip* clip = GetAudioClipForOldStyleNumber(game, false, game.options[OPT_SCORESOUND]);
+        const ScriptAudioClip* clip = GetAudioClipForOldStyleNumber(game, false, game.options[OPT_SCORESOUND]);
         if (clip)
             game.scoreClipID = clip->id;
     }

Editor/AGS.Editor/Resources/agsdefns.sh

@@ -2496,6 +2496,10 @@ builtin managed struct AudioChannel {
   /// Changes playback to continue from the specified position in milliseconds.
   import void SeekMs(int position);
 #endif // SCRIPT_API_v36026
+#ifdef SCRIPT_API_v363
+  /// Gets which audio type current played clip is representing, or -1 if no clip is being played.
+  import readonly attribute AudioType PlayingType;
+#endif // SCRIPT_API_v363
 };
 
 builtin managed struct AudioClip {
@@ -2512,13 +2516,17 @@ builtin managed struct AudioClip {
   /// Plays this audio clip, explicitly putting it on the particular channel.
   import AudioChannel* PlayOnChannel(int chan, AudioPriority=SCR_NO_VALUE, RepeatStyle=SCR_NO_VALUE);
 #endif // SCRIPT_API_v360
+#ifdef SCRIPT_API_v363
+  /// Plays this audio clip using certain AudioType settings, and optionally putting it on a particular channel.
+  import AudioChannel* PlayAsType(AudioType type, int chan=SCR_NO_VALUE, AudioPriority=SCR_NO_VALUE, RepeatStyle=SCR_NO_VALUE);
+#endif // SCRIPT_API_v363
   /// Stops all currently playing instances of this audio clip.
   import void Stop();
   /// Gets the file type of the sound.
   readonly import attribute AudioFileType FileType;
   /// Checks whether this audio file is available on the player's system.
   readonly import attribute bool IsAvailable;
-  /// Gets the type of audio that this clip contains.
+  /// Gets the audio type that this clip belongs to.
   readonly import attribute AudioType Type;
 #ifdef SCRIPT_API_v350
   /// Gets the clip's ID number.
@@ -3250,6 +3258,8 @@ builtin struct Game {
   import static readonly attribute bool InBlockingWait;
 #endif // SCRIPT_API_v362
 #ifdef SCRIPT_API_v363
+  /// Play speech voice-over in non-blocking mode, using certain AudioType settings, and optionally putting it on a particular channel.
+  import static AudioChannel* PlayVoiceClipAsType(Character*, int cue, AudioType type, int chan=SCR_NO_VALUE, AudioPriority=SCR_NO_VALUE, RepeatStyle=SCR_NO_VALUE);
   /// Gets/sets game's running speed, in frames per second.
   import static attribute int Speed;
   /// Gets number of game's ticks (updates) passed since the game start.

Engine/ac/audiochannel.cpp

@@ -85,6 +85,14 @@ ScriptAudioClip* AudioChannel_GetPlayingClip(ScriptAudioChannel *channel)
     return nullptr;
 }
 
+int AudioChannel_GetPlayingType(ScriptAudioChannel *channel)
+{
+    auto *ch = AudioChans::GetChannelIfPlaying(channel->id);
+    if (ch)
+        return ch->sourceClipType;
+    return AUDIOTYPE_UNDEFINED;
+}
+
 int AudioChannel_GetPosition(ScriptAudioChannel *channel)
 {
     auto* ch = AudioChans::GetChannelIfPlaying(channel->id);
@@ -175,7 +183,7 @@ void AudioChannel_Stop(ScriptAudioChannel *channel)
     if (channel->id == SCHAN_SPEECH && play.IsNonBlockingVoiceSpeech())
         stop_voice_nonblocking();
     else
-        stop_or_fade_out_channel(channel->id, -1, nullptr);
+        stop_or_fade_out_channel(channel->id, -1);
 }
 
 void AudioChannel_Pause(ScriptAudioChannel *channel)
@@ -278,6 +286,11 @@ RuntimeScriptValue Sc_AudioChannel_GetPlayingClip(void *self, const RuntimeScrip
     API_OBJCALL_OBJ(ScriptAudioChannel, ScriptAudioClip, ccDynamicAudioClip, AudioChannel_GetPlayingClip);
 }
 
+RuntimeScriptValue Sc_AudioChannel_GetPlayingType(void *self, const RuntimeScriptValue *params, int32_t param_count)
+{
+    API_OBJCALL_INT(ScriptAudioChannel, AudioChannel_GetPlayingType);
+}
+
 // int | ScriptAudioChannel *channel
 RuntimeScriptValue Sc_AudioChannel_GetPosition(void *self, const RuntimeScriptValue *params, int32_t param_count)
 {
@@ -378,6 +391,7 @@ void RegisterAudioChannelAPI()
         { "AudioChannel::get_Panning",        API_FN_PAIR(AudioChannel_GetPanning) },
         { "AudioChannel::set_Panning",        API_FN_PAIR(AudioChannel_SetPanning) },
         { "AudioChannel::get_PlayingClip",    API_FN_PAIR(AudioChannel_GetPlayingClip) },
+        { "AudioChannel::get_PlayingType",    API_FN_PAIR(AudioChannel_GetPlayingType) },
         { "AudioChannel::get_Position",       API_FN_PAIR(AudioChannel_GetPosition) },
         { "AudioChannel::get_PositionMs",     API_FN_PAIR(AudioChannel_GetPositionMs) },
         { "AudioChannel::get_Volume",         API_FN_PAIR(AudioChannel_GetVolume) },

Engine/ac/audiochannel.h

@@ -26,6 +26,7 @@ int     AudioChannel_GetIsPlaying(ScriptAudioChannel *channel);
 int     AudioChannel_GetPanning(ScriptAudioChannel *channel);
 void    AudioChannel_SetPanning(ScriptAudioChannel *channel, int newPanning);
 ScriptAudioClip* AudioChannel_GetPlayingClip(ScriptAudioChannel *channel);
+int     AudioChannel_GetPlayingType(ScriptAudioChannel *channel);
 int     AudioChannel_GetPosition(ScriptAudioChannel *channel);
 int     AudioChannel_GetPositionMs(ScriptAudioChannel *channel);
 int     AudioChannel_GetLengthMs(ScriptAudioChannel *channel);