Script API: add Game.PlayVoiceClipAsType()

Author: ivan-mogilko

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

@@ -24,7 +24,9 @@
 namespace AGS { namespace Common { class Stream; } }
 using namespace AGS; // FIXME later
 
-enum AudioFileType {
+enum AudioFileType
+{
+    eAudioFileUndefined = 0,
     eAudioFileOGG = 1,
     eAudioFileMP3 = 2,
     eAudioFileWAV = 3,
@@ -45,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 = AUDIOTYPE_UNDEFINED;
-    AudioFileType fileType = eAudioFileOGG;
+    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/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,29 +425,17 @@ 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);

Editor/AGS.Editor/Resources/agsdefns.sh

@@ -3258,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/game.cpp

@@ -944,6 +944,29 @@ int Game_InBlockingWait()
     return IsInWaitMode();
 }
 
+ScriptAudioChannel *Game_PlayVoiceClip(CharacterInfo *ch, int sndid, bool as_speech)
+{
+    if (!play_voice_nonblocking(ch ? ch->index_id : -1 /* narrator */, sndid, as_speech))
+        return nullptr;
+    return &scrAudioChannel[SCHAN_SPEECH];
+}
+
+ScriptAudioChannel *Game_PlayVoiceClipAsType(CharacterInfo *ch, int sndid, int audio_type, int chan, int priority, int repeat)
+{
+    if (audio_type <= AUDIOTYPE_SPEECH || static_cast<uint32_t>(audio_type) >= game.audioClipTypes.size())
+        quitprintf("!AudioClip.PlayAsType: invalid audio type %d, the range is %u - %u",
+                   audio_type, AUDIOTYPE_SPEECH + 1, static_cast<uint32_t>(game.audioClipTypes.size() - 1));
+    if (chan != SCR_NO_VALUE && (chan < NUM_SPEECH_CHANS || chan >= game.numGameChannels))
+        quitprintf("!AudioClip.PlayAsType: invalid channel %d, the range is %d - %d",
+                   chan, NUM_SPEECH_CHANS, game.numGameChannels - 1);
+    if (chan == SCR_NO_VALUE)
+        chan = -1;
+
+    if (!play_voice_clip_as_type(ch ? ch->index_id : -1 /* narrator */, sndid, audio_type, chan, priority, repeat))
+        return nullptr;
+    return &scrAudioChannel[SCHAN_SPEECH];
+}
+
 void Game_PrecacheSprite(int sprnum)
 {
     const auto tp_start = FastClock::now();
@@ -2100,7 +2123,12 @@ RuntimeScriptValue Sc_Game_IsPluginLoaded(const RuntimeScriptValue *params, int3
 
 RuntimeScriptValue Sc_Game_PlayVoiceClip(const RuntimeScriptValue *params, int32_t param_count)
 {
-    API_SCALL_OBJ_POBJ_PINT_PBOOL(ScriptAudioChannel, ccDynamicAudio, PlayVoiceClip, CharacterInfo);
+    API_SCALL_OBJ_POBJ_PINT_PBOOL(ScriptAudioChannel, ccDynamicAudio, Game_PlayVoiceClip, CharacterInfo);
+}
+
+RuntimeScriptValue Sc_Game_PlayVoiceClipAsType(const RuntimeScriptValue *params, int32_t param_count)
+{
+    API_SCALL_OBJ_POBJ_PINT5(ScriptAudioChannel, ccDynamicAudio, Game_PlayVoiceClipAsType, CharacterInfo);
 }
 
 RuntimeScriptValue Sc_Game_GetCamera(const RuntimeScriptValue *params, int32_t param_count)
@@ -2212,7 +2240,8 @@ void RegisterGameAPI()
         { "Game::StopSound^1",                            API_FN_PAIR(StopAllSounds) },
         { "Game::IsPluginLoaded",                         Sc_Game_IsPluginLoaded, pl_is_plugin_loaded },
         { "Game::ChangeSpeechVox",                        API_FN_PAIR(Game_ChangeSpeechVox) },
-        { "Game::PlayVoiceClip",                          Sc_Game_PlayVoiceClip, PlayVoiceClip },
+        { "Game::PlayVoiceClip",                          API_FN_PAIR(Game_PlayVoiceClip) },
+        { "Game::PlayVoiceClipAsType",                    API_FN_PAIR(Game_PlayVoiceClipAsType) },
         { "Game::SimulateKeyPress",                       API_FN_PAIR(Game_SimulateKeyPress) },
         { "Game::ResetDoOnceOnly",                        API_FN_PAIR(Game_ResetDoOnceOnly) },
         { "Game::PrecacheSprite",                         API_FN_PAIR(Game_PrecacheSprite) },

Engine/ac/gamestate.cpp

@@ -449,6 +449,11 @@ bool GamePlayState::ShouldPlayVoiceSpeech() const
         (play.speech_mode != kSpeech_TextOnly) && (play.voice_avail);
 }
 
+bool GamePlayState::ShouldPlayVoiceSpeechNonBlocking() const
+{
+    return !play.fast_forward && (play.voice_avail);
+}
+
 void GamePlayState::ReadFromSavegame(Stream *in, GameDataVersion data_ver, GameStateSvgVersion svg_ver, RestoredData &r_data)
 {
     score = in->ReadInt32();

Engine/ac/gamestate.h

@@ -468,6 +468,7 @@ struct GamePlayState
     bool IsNonBlockingVoiceSpeech() const;
     // Speech helpers
     bool ShouldPlayVoiceSpeech() const;
+    bool ShouldPlayVoiceSpeechNonBlocking() const;
 
     //
     // Serialization

Engine/ac/global_audio.cpp

@@ -446,13 +446,6 @@ int IsMusicVoxAvailable () {
 
 extern ScriptAudioChannel scrAudioChannel[MAX_GAME_CHANNELS];
 
-ScriptAudioChannel *PlayVoiceClip(CharacterInfo *ch, int sndid, bool as_speech)
-{
-    if (!play_voice_nonblocking(ch ? ch->index_id : -1 /* narrator */, sndid, as_speech))
-        return NULL;
-    return &scrAudioChannel[SCHAN_SPEECH];
-}
-
 // Construct an asset name for the voice-over clip for the given character and cue id
 static String get_cue_filename(int charid, int sndid, bool old_style)
 {
@@ -477,15 +470,11 @@ static String get_cue_filename(int charid, int sndid, bool old_style)
     return Path::ConcatPaths(get_voice_assetpath(), asset_filename);
 }
 
-// Play voice-over clip on the common channel;
-// voice_name should be bare clip name without extension
-static bool play_voice_clip_on_channel(const String &voice_name)
+static AssetPath find_voice_clip(const String &voice_name)
 {
-    stop_and_destroy_channel(SCHAN_SPEECH);
-
     // TODO: perhaps a better algorithm, allow any extension / sound format?
     // e.g. make a hashmap matching a voice name to a asset name
-    std::array<const char*, 3> exts = {{ "mp3", "ogg", "wav" }};
+    std::array<const char *, 3> exts = { { "mp3", "ogg", "wav" } };
     AssetPath apath = get_voice_over_assetpath(voice_name);
     bool found = false;
     for (auto *ext : exts)
@@ -498,9 +487,22 @@ static bool play_voice_clip_on_channel(const String &voice_name)
 
     if (!found) {
         debug_script_warn("Speech file not found: '%s'", voice_name.GetCStr());
-        return false;
+        return AssetPath();
     }
 
+    return apath;
+}
+
+// Play voice-over clip on the common channel;
+// voice_name should be bare clip name without extension
+static bool play_voice_clip_on_channel(const String &voice_name)
+{
+    stop_and_destroy_channel(SCHAN_SPEECH);
+
+    AssetPath apath = find_voice_clip(voice_name);
+    if (!apath)
+        return false;
+
     std::unique_ptr<SoundClip> voice_clip(load_sound_clip(apath, "", false));
     if (voice_clip != nullptr) {
         voice_clip->fileName = apath.Name;
@@ -590,16 +592,34 @@ bool play_voice_speech(int charid, int sndid)
 bool play_voice_nonblocking(int charid, int sndid, bool as_speech)
 {
     // don't play voice if we're skipping a cutscene
-    if (!play.ShouldPlayVoiceSpeech())
+    if (!play.ShouldPlayVoiceSpeechNonBlocking())
         return false;
     // don't play voice if there's a blocking speech with voice-over already
-    if (play.IsBlockingVoiceSpeech())
+    if (as_speech && play.IsBlockingVoiceSpeech())
         return false;
 
     String voice_file = get_cue_filename(charid, sndid, !game.options[OPT_VOICECLIPNAMERULE]);
     return play_voice_clip_impl(voice_file, as_speech, false);
 }
 
+const ScriptAudioChannel *play_voice_clip_as_type(int charid, int sndid, int type, int chan, int priority, int repeat)
+{
+    // don't play voice if we're skipping a cutscene
+    if (!play.ShouldPlayVoiceSpeechNonBlocking())
+        return nullptr;
+
+    String voice_file = get_cue_filename(charid, sndid, !game.options[OPT_VOICECLIPNAMERULE]);
+    AssetPath apath = find_voice_clip(voice_file);
+    if (!apath)
+        return nullptr;
+
+    ScriptAudioClip sc_clip; // pass temp dummy clip
+    sc_clip.fileName = apath.Name;
+    sc_clip.fileType = ScriptAudioClip::GetAudioFileTypeFromExt(Path::GetFileExtension(apath.Name).GetCStr());
+    sc_clip.bundlingType = kAudioBundle_SpeechVox;
+    return play_audio_clip(AudioPlayback(&sc_clip, type), chan, priority, repeat, 0, false);
+}
+
 void stop_voice_speech()
 {
     if (!play.speech_has_voice)

Engine/ac/global_audio.h

@@ -51,16 +51,14 @@ int     IsMusicVoxAvailable ();
 
 struct CharacterInfo;
 struct ScriptAudioChannel;
-// Starts voice-over playback and returns audio channel it is played on;
-// as_speech flag determines whether engine should apply speech-related logic
-// as well, such as temporary volume reduction.
-ScriptAudioChannel *PlayVoiceClip(CharacterInfo *ch, int sndid, bool as_speech);
 
 //=============================================================================
 // Play voice-over for the active blocking speech and initialize relevant data
 bool    play_voice_speech(int charid, int sndid);
 // Play voice-over clip in non-blocking manner
 bool    play_voice_nonblocking(int charid, int sndid, bool as_speech);
+// Play voice-over clip in non-blocking manner, as a given audio type, optionally selecting an explicit channel
+const ScriptAudioChannel *play_voice_clip_as_type(int charid, int sndid, int type, int chan, int priority, int repeat);
 // Stop voice-over for the active speech and reset relevant data
 void    stop_voice_speech();
 // Stop non-blocking voice-over and revert audio volumes if necessary