Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Binding to external libraries

Moduli

L'esempio di Summator in Moduli personalizzati in C++ è ottimo per piccoli moduli personalizzati, ma cosa succede se si desidera utilizzare una libreria esterna più grande? Diamo un'occhiata a un esempio che utilizza Festival, una libreria di sintesi vocale (text-to-speech) scritta in C++.

Per associare una libreria esterna, configurare un modulo simile all'esempio di Summator:

godot/modules/tts/

Successivamente, si creerà un file di intestazione con una classe TTS:

godot/modules/tts/tts.h

#pragma once

#include "core/object/ref_counted.h"

class TTS : public RefCounted {
    GDCLASS(TTS, RefCounted);

protected:
    static void _bind_methods();

public:
    bool say_text(String p_txt);

    TTS();
};

E poi si aggiungerà il file cpp.

godot/modules/tts/tts.cpp

#include "tts.h"

#include <festival.h>

bool TTS::say_text(String p_txt) {

    //convert Godot String to Godot CharString to C string
    return festival_say_text(p_txt.ascii().get_data());
}

void TTS::_bind_methods() {

    ClassDB::bind_method(D_METHOD("say_text", "txt"), &TTS::say_text);
}

TTS::TTS() {
    festival_initialize(true, 210000); //not the best way to do it as this should only ever be called once.
}

Proprio come prima, la nuova classe si deve registrare in qualche modo, quindi è necessario creare altri due file:

register_types.h
register_types.cpp

Importante

Questi file devono trovarsi nella cartella di livello superiore del modulo (accanto ai file SCsub e config.py) affinché il modulo sia registrato correttamente.

Questi file dovrebbero contenere quanto segue:

godot/modules/tts/register_types.h

void initialize_tts_module(ModuleInitializationLevel p_level);
void uninitialize_tts_module(ModuleInitializationLevel p_level);
/* yes, the word in the middle must be the same as the module folder name */

godot/modules/tts/register_types.cpp

#include "register_types.h"

#include "core/object/class_db.h"
#include "tts.h"

void initialize_tts_module(ModuleInitializationLevel p_level) {
    if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
        return;
    }
    ClassDB::register_class<TTS>();
}

void uninitialize_tts_module(ModuleInitializationLevel p_level) {
    // Nothing to do here in this example.
}

Successivamente, è necessario creare un file SCsub in modo che il sistema di compilazione compili questo modulo:

godot/modules/tts/SCsub

Import('env')

env_tts = env.Clone()
env_tts.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build

È necessario installare la libreria esterna sul computer per ottenere i file .a di libreria. Consultare la documentazione ufficiale della libreria per istruzioni specifiche su come farlo per il proprio sistema operativo. Di seguito abbiamo incluso i comandi di installazione per Linux, come riferimento.

sudo apt-get install festival festival-dev  # Installs festival and speech_tools libraries
apt-cache search festvox-*  # Displays list of voice packages
sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k  # Installs voices

Importante

Le voci utilizzate da Festival (e qualsiasi altra potenziale risorsa esterna/di terze parti) hanno varie licenze e termini d'uso; alcune (se non la maggior parte) potrebbero presentare problemi con Godot, anche se la libreria Festival stessa è compatibile con la licenza MIT. Si prega di verificare le licenze e i termini d'uso.

Sarà necessario installare la libreria esterna anche all'interno del modulo per rendere i file sorgente accessibili al compilatore, mantenendo autonomo allo stesso tempo il codice del modulo. Le librerie festival e speech_tools si possono installare dalla cartella modules/tts/ tramite git attraverso i seguenti comandi:

git clone https://github.com/festvox/festival
git clone https://github.com/festvox/speech_tools

Se non si desidera che i file sorgente del repository esterno siano salvati nel proprio repository, è possibile collegarti ad essi aggiungendoli come sotto-moduli (dall'interno della cartella modules/tts/), come mostrato di seguito:

git submodule add https://github.com/festvox/festival
git submodule add https://github.com/festvox/speech_tools

Importante

Si prega di notare che i sotto-moduli Git non vengono utilizzati nel repository Godot. Se si sta sviluppando un modulo da integrare nel repository Godot principale, non si dovrebbero utilizzare i sotto-moduli. Se il modulo non è integrato, è sempre possibile provare a implementare la libreria esterna sotto forma di una GDExtension.

Per aggiungere cartelle di inclusione che il compilatore può esaminare, è possibile aggiungerle ai percorsi dell'ambiente:

godot/modules/tts/SCsub

# These paths are relative to /modules/tts/
env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"])

# LIBPATH and LIBS need to be set on the real "env" (not the clone)
# to link the specified libraries to the Godot executable.

# This is an absolute path where your .a libraries reside.
# If using a relative path, you must convert it to a
# full path using a utility function, such as `Dir('...').abspath`.
env.Append(LIBPATH=[Dir('libpath').abspath])

# Check with the documentation of the external library to see which library
# files should be included/linked.
env.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring'])

Se si desidera aggiungere flag personalizzati al compilatore durante la compilazione del modulo, è necessario prima clonare env, affinché non aggiunga quei flag all'intera compilazione di Godot (il che potrebbe causare errori). SCsub di esempio con flag personalizzati:

godot/modules/tts/SCsub

Import('env')

env_tts = env.Clone()
env_tts.add_source_files(env.modules_sources, "*.cpp")
# Append CCFLAGS flags for both C and C++ code.
env_tts.Append(CCFLAGS=['-O2'])
# If you need to, you can:
# - Append CFLAGS for C code only.
# - Append CXXFLAGS for C++ code only.

Il modulo finale dovrebbe apparire così:

godot/modules/tts/festival/
godot/modules/tts/libpath/libestbase.a
godot/modules/tts/libpath/libestools.a
godot/modules/tts/libpath/libeststring.a
godot/modules/tts/libpath/libFestival.a
godot/modules/tts/speech_tools/
godot/modules/tts/config.py
godot/modules/tts/tts.h
godot/modules/tts/tts.cpp
godot/modules/tts/register_types.h
godot/modules/tts/register_types.cpp
godot/modules/tts/SCsub

Utilizzare il modulo

Ora è possibile utilizzare il modulo appena creato da qualsiasi script:

var t = TTS.new()
var script = "Hello world. This is a test!"
var is_spoken = t.say_text(script)
print('is_spoken: ', is_spoken)

E il risultato sarà is_spoken: True se il testo è pronunciato.