Skip to content

legacy_sound

The legacy_sound plugin replaces NVGT's built-in sound system with the older, BASS based implementation that NVGT shipped with before its current audio engine was written. It exists so that older projects can keep running unchanged while they are migrated, and it should not be used for new projects.

To activate it, add the following line to your script:

#pragma plugin legacy_sound

When the plugin is active, it registers its own versions of the sound, mixer and sound_environment classes in place of the built-in ones, along with the legacy pack class documented here. The built-in pack_file class is still available, but when the legacy sound class loads a sound from a pack, that pack must be a legacy pack. Includes such as menu.nvgt, number_speaker.nvgt and bgt_compat.nvgt detect the plugin with #if plugin_legacy_sound and switch to the legacy pack class automatically.

Packs created by the legacy pack class use a different file format from those created by pack_file, and the two classes cannot open each other's files.

classes

pack

The legacy pack class, which reads and writes pack files in the format used by NVGT before the pack_file class was introduced. It is only available when the legacy_sound plugin is loaded.

pack();

Remarks:

A pack is a single file that contains many other files, usually the sounds and other assets of a game. Unlike pack_file, a legacy pack can be opened for appending, and files can be deleted from it or replaced in place.

New projects should use the built-in pack_file class instead. This class is documented so that existing projects can be maintained while they are migrated.

methods

add_file

Add a file on disk to a pack.

bool pack::add_file(const string&in disk_filename, const string&in pack_filename, bool allow_replace = false);

Arguments:
Returns:

bool: true if the file was successfully added, false otherwise.

add_memory

Add content stored in memory to a pack.

bool pack::add_memory(const string&in pack_filename, const string&in data, bool replace = false);

Arguments:
Returns:

bool: true if the data was successfully added, false otherwise.

close

Closes a pack, freeing all its resources.

bool pack::close();

Returns:

bool: true if the pack was successfully closed, false otherwise.

delete_file

Attempt to remove a file from a pack.

bool pack::delete_file(const string&in filename);

Arguments:
Returns:

bool: true if the file was successfully deleted, false otherwise.

file_exists

Query whether or not a file exists in your pack.

bool pack::file_exists(const string&in filename);

Arguments:
Returns:

bool: true if the file exists in the pack, false if not.

get_file_name

Get the name of a file with a particular index.

string pack::get_file_name(int index);

Arguments:
Returns:

string: the name of the file if found, or an empty string if not.

Remarks:

The index you pass to this function is the same index you'd use to access an element in the return value from pack::list_files().

get_file_offset

Get the offset of a file in your pack.

uint pack::get_file_offset(const string&in filename);

Arguments:
Returns:

uint: the offset of the file (in bytes).

Remarks:

Do not confuse this with the offset parameter in the pack::read_file method. This function is provided encase you wish to re-open the pack file with your own file object and seek to a file's data within that external object. The offset_in_file parameter in the read_file method is relative to the file being read.

get_file_size

Returns the size of a particula file in the pack.

uint pack::get_file_size(const string&in filename);

Arguments:
Returns:

uint: the size of the file (in bytes), or 0 if no file with that name was found.

list_files

Get a list of all the files in the pack.

string[]@ pack::list_files();

Returns:

string[]@: a handle to an array of strings containing the names of every file in the pack.

open

Open a pack to perform operations on it.

bool pack::open(const string&in filename, uint mode = PACK_OPEN_MODE_READ, bool memload = false);

Arguments:
Returns:

bool: true if the pack was successfully opened with the given mode, false otherwise.

Remarks:

To open an embedded pack, prefix it with *, like this:

pack.open("*embedded.dat");

For BGT compatibility, you can use a single * to open the first available embedded pack.

pack.open("*");

read_file

Get the contents of a file contained in a pack.

string pack::read_file(const string&in pack_filename, uint offset_in_file, uint size);

Arguments:
Returns:

string: the contents of the file.

Remarks:

This function allows you to read chunks of data from a file, as well as an entire file in one call. To facilitate this, the offset and size parameters are provided. offset is relative to the file being read E. 0 for the beginning of it. So to read a file in one chunk, you could execute:

string file_contents = my_pack.read_file("filename", 0, my_pack.get_file_size("filename"));
set_pack_identifier

Set the identifier of this pack object (e.g. the first 8-bytes that determine if you have a valid pack or not).

bool pack::set_pack_identifier(const string&in ident);

Arguments:
Returns:

bool: true if the pack's identifier was properly set, false otherwise.

Remarks:

enums

pack_open_modes

This is a list of all the possible open modes to be passed to the pack::open() function.

functions

pack_set_global_identifier

Set the global identifier of all your packs (e.g. the first 8-bytes that determine if you have a valid pack or not).

bool pack_set_global_identifier(const string&in ident);

Arguments:

Returns:

bool: true if the identifier was properly set, false otherwise.

Remarks:

global properties

pack_global_identifier

Represents the identifier currently being used for all your packs.

const string pack_global_identifier;