Resound API

Developer and Album Author Documentation

Target: Resound 4.1.0

Resound is a Vanilla+-styl e music framework for Vendetta Online. It recreates the game's environment-aware music behavior while allowing other mods to register new albums, define new environmental rules, observe playback, and request playback changes through a public LME interface.

Scope: This document describes the public interfaces and album format exposed by Resound 4.1.0. Internal tables and module files are implementation details and should not be hooked, replaced, or accessed directly.

Contents

• 1. Getting the Resound API

• 2. Creating and registering albums

• 3. Understanding tag expressions

• 4. Built-in tags

• 5. Extending the tag system

• 6. Playback API

• 7. Observer API

• 8. Configuration API

• 9. Extension recipes

• 10. API summary and compatibility notes

1. Getting the Resound API

Resound exposes its supported functionality through its LME class. External LME plugins should declare Resound as a dependency and obtain the public class rather than reading or replacing Resound modules.

Dependency declaration

[dependencies]
depid1=resound
depvs1=4.1.0
depmx1=4.9.9

Use a version range appropriate for the API surface your plugin requires.

Obtaining the class

local res_ver = lib.get_latest("resound", "4.1.0", "4.9.9")
local resound = lib.get_class("resound", res_ver)

Boundary: If functionality is not exposed through the returned public table, do not assume Resound's private module layout, load order, filenames, or internal tables are stable API.

2. Creating and Registering Albums

A Resound album is an INI file. The [resound] section describes the album, followed by consecutively numbered song sections beginning at [1]. Resound stops reading songs at the first numbered section that does not contain a file key.

Album INI example

[resound]
api=3
album=my_album
description=Example music album
a uthor=Example Author

[1]
file=plugins/MyAlbum/music/example.ogg
title=Example Track
artist=Example Composer
tags=ambient
vol=100
length=183000

[2]
file=plugins/MyAlbum/music/danger.ogg
title=Danger Track
artist=Example Composer
tags==danger
length=201000

Contiguous numbering: Song sections must be [1], [2], [3], and so on. A missing file entry ends album ingestion; later numbered sections will not be discovered.

Registering an album

local ok, err = resound.new_album("plugins/MyAlbum/MyAlbum.ini")
if not ok then
print("Resound album registration failed: " .. tostring(err))
end

new_album(path) returns true on success. On failure it returns false plus a short error string, such as a missing album key or an album with zero songs.

If you are publishing a standard Resound album, the registration code above and the tag behavior described in Chapter 3 are normally all you need. The remaining public API is primarily intended for album management, playback integration, observers, or cust om tag behavior.

Album management and inspection

Raw versus compiled entries: Album/song inspection functions return registration data. The playback engine uses a separate compiled playlist entry table.

3. Understanding Tag Expressions

Tags decide whether a song is valid in the current environment. Resound compiles each song's tags string into one or more groups, then evaluates those groups against the current tag state.

Basic token syntax

Commas, semicolons, and whitespace can separate tokens. Tag names are normalized to lowercase alphanumeric/underscore form.

Groups are OR branches

tags=[ambient -danger] [station]

The complete expression is true if any bracketed group is true. If no brackets are used, the entire string is treated as one group.

Required, excluded, and optional behavior

Within one group, all required tags must pass and no excluded tag may be active. A passing required tag makes the group meaningfully valid. Optional tags provide an alternative way for the group to become valid.

Negative-only groups: A group containing only excluded (-) conditions never becomes valid by itself; it needs a required or passing optional condition.

Forced tags

Some environmental rules use require_tag(). A forced tag is not merely active: every candidate group's expression must structurally mention that tag name. This is how Resound can require a class of music during conditions such as danger or combat.

-- If danger is forced, a group that never mentions danger cannot match.
tags=ambient

-- This group can participate while danger is forced.
tags=+danger,=ambient

O ptional +tag entries normally matter only when they are the condition that makes a tag group valid. If a group already contains passing required =tag conditions, ordinary +tag entries usually have no additional effect. The important exception is a tag that Resound has environmentally forced with require_tag(): the group must structurally mention that forced tag, and a +tag entry is enough to satisfy that structural requirement. +danger can matter beside =ambient not because optional tags are generally additive, but because forced-tag presence is checked separately from normal truth evaluation.

4. Built-in Tags

Resound 4.1.0 provides a vanilla-style core tag set. Optional non-vanilla tags are loaded when the adv_tags configuration value is YES.

Vanilla-style tags

Optional non-vanilla tags

5. Extending the Tag System

Lua extensions can add environment rules without replacing Resound's tag engine. Prefer a unique tag name when your semantics differ from Resound's built-in tags.

Reading and changing live tags

Entry and scanning callbacks

resound.tags.register_entry_tag(function()
-- Runs when Resound rebuilds environment tags on sector entry.
resound.tags.toggle_tag("my_region", some_test())
end)

resound.tags.register_scanning_tag(function()
-- Runs periodically as part of Resound's scanner rotation.
resound.tags.toggle_tag("my_dynamic_state", some_other_test())
end)

No unregister API: 4.1.0 does not expose an unregister function for entry/scanning callbacks. If your behavior may be disabled at runtime, register one stable callback and gate its work internally.

Argument-based tag functions

resound.tags.register_tag_func("hascargo", function(args)
local item = args and args[1]
return item and my_plugin_has_cargo(item) or false
end)

-- Album usage:
-- tags=hascargo:PremiumWidget

register_tag_func(tagname, handler) installs one handler for the normalized tag name. Registering another handler under the same name replaces the previous function. unregister_tag_func(tagname) removes it.

Immediate revalidation

Normal tag mutations mark the current playback state dirty; Resound consumes that dirty state after the scanning cycle. Event-driven extensions that need an immediate reaction can call:

resound.revalidate_current_song()

The function returns true if the current song remains valid. If there is no current song or the current song is invalid, Resound requests a seek and returns false.

6. Playback API

Compiled playback entry

{
album_id = "album_id",
id = "1",
song_id = "1",
name = "Track title",
file = "path/to/music.ogg",
compiled = <compiled tag expression>,
length_ms = 183000
}

Observer/song ID: Compiled playback entries expose both id and song_id, which contain the same registered song ID. id is shared with raw album song entries, while song_id is retained as a descriptive alias for compiled entries.

Playhead table

{
started_at = <game time in ms>,
elapsed = <milliseconds>,
song_length = <milliseconds>,
has_valid_len = true/false,
remaining = <milliseconds>,
percentage = <elapsed percentage>
}

Unk nown or non-positive registered song lengths are treated as having no valid duration; Resound does not schedule an automatic end for those tracks. Playback will loop based on standard game client rules defined by the functionality of gksound.GKPlayMusic().

7. Observer API

Observers let another plugin receive selected Resound events without hooking the engine or notification module.

Registering an observer

local function on_resound_event(event_trigger, data)
if event_trigger ~= "track_started" then
return
end

print("Resound started: " .. tostring(data.name))
end

resound.register_observer("my_plugin_resound_observer", on_resound_event)

register_observer(id, func) returns true on success. Registering the same ID again replaces the prior observer.

Releasing an observer

resound.release_observer("my_plugin_resound_observer")

Observer contract

• Observers receive every observer trigger Resound chooses to expose. Filter event_trigger before assuming the shape of data.

• Callbacks are protected with pcall; a failing observer does not interrupt Resound playback.

• An observer is deregistered after more than three lifetime callback failures.

• As of 4.1.0, the public trigger is track_started.

track_started

C urrently the only trigger exposed in v4.1.0, but more will be implemented later. Fired after Resound commits the new current song, begins GK music playback, and schedules its end timer. data is the compiled playback entry shown in the Playback API section.

local function credits(event_trigger, data)
if event_trigger ~= "track_started" then
return
end

local album = resound.get_album_data(data.album_id)
local ini_path = album and album.path
local song_id = data.id

if ini_path then
local artist = gkini.ReadString2(
song_id, "artist", "unknown artist", ini_path
)
print("\tCreated by: " .. artist)
end
end

8. Configuration API

Resound's configuration values are exposed for inspection and controlled changes. Values are stored as strings.

4.1.0 configuration keys

9. Extension Recipes

Recipe: register a simple album plugin

local res_ver = lib.get_latest("resound", "4.1.0", "4.9.9")
local resound = lib.get_class("resound", res_ver)

local my_path = lib.get_path() or "plugins/MyAlbum/"
local ok, err = resound.new_album(my_path .. "MyAlbum.ini")

if not ok then
lib.log_error("[MyAlbum] Unable to register Resound album: " .. tostring(err), 3)
end

Recipe: custom scanning tag

resound.tags.register_scanning_tag(function()
local active = my_environment_test()
resound.tags.toggle_tag("mytag", active)
end)

-- Album:
-- tags==mytag

Recipe: event-driven tag with immediate playback reaction

RegisterEvent(function()
resound.tags.toggle_tag("mycombat", true)
resound.tags.require_tag("mycombat")
resound.revalidate_current_song()
end, "PLAYER_GOT_HIT")

When the condition ends, remove forced status and explicitly turn off ordinary state if that is your desired semantics:

resound.tags.unrequire_tag("mycombat")
resound.tags.toggle_tag("mycombat", false)

Recipe: add extra track metadata in chat

local function extra_track_info(event_trigger, data)
if event_trigger ~= "track_started" then
return
end
if resound.get_config("do_chat") ~= "YES" then
return
end

local album = resound.get_ album_data(data.album_id)
if not album or not album.path then
return
end

local artist = gkini.ReadString2(
data.song_id, "artist", "unknown artist", album.path
)
local game = gkini.ReadString2(
data.song_id, "ga me", "", album.path
)

if game == "" then
print("\tCreated by: " .. artist)
else
print("\tRemix by: " .. artist .. " | Game: " .. game)
end
end

resound.register_observer(
"my_extended_track_info",
extra_track_info
)

Custom INI keys: Resound only ingests its known song keys. An extension may still read additional known keys directly from album.path with gkini.ReadString2(). Vendetta Online's INI API requires the caller to know the key name.

10. API Summary and Compatibility Notes

Top-level public API

resound.tags API

get_tag, toggle_tag, require_tag, unrequire_tag, clear_all_tags, register_entry_tag, register_scanning_tag, register_tag_func, unregister_tag_func, list_current_tags

Observer triggers in 4.1.0

Compatibility guidance

• Depend on the Resound class and public API, not internal module filenames or private tables.

• Use a custom tag rather than redefining a built-in tag when your behavior has different semantics.

• Use observers for reactions to playback instead of replacing Resound's notification or engine callbacks.

• Use revalidate_current_song() when an external event changes tag validity and waiting for the normal scanner rotation is undesirable.

• Treat undocumented internal return structures and private fields as unstable unless they are described in this document.

Version target

This document targets Resound 4.1.0. Future releases may add public observer triggers, tag functions, or API methods. Plugins should declare a compatible version range and should not infer new API from Resound's private implementation.