From 31e612f3142a931780843a8d0df6d0e0da007785 Mon Sep 17 00:00:00 2001 From: Piotr Macha Date: Thu, 23 May 2024 21:38:30 +0200 Subject: [PATCH] docs: publish all categories excluding Developer Guide --- _externals/BassMusic.d | 2 +- docs/docs/reference/classes/C_MUSICTHEME.md | 33 +++++- docs/docs/reference/externals/index.md | 103 +++++++++++++++++- docs/docs/reference/globals/index.md | 20 +++- docs/docs/reference/index.md | 32 +++++- docs/docs/reference/options/index.md | 57 +++++++++- docs/docs/roadmap/index.md | 42 ++++--- docs/docs/stylesheets/extra.css | 9 ++ docs/docs/user-guide/debugging/index.md | 36 ++++++ .../{crossfading.md => cross-fading.md} | 12 +- .../getting-started/plugin-loading.md | 8 +- .../user-guide/scripting/custom-scheduler.md | 25 ++++- docs/docs/user-guide/scripting/index.md | 85 ++++++++++++++- .../user-guide/transition-scheduler/index.md | 16 ++- .../transition-scheduler/instant.md | 4 +- .../user-guide/transition-scheduler/jingle.md | 5 + .../transition-scheduler/on-beat.md | 35 +++++- docs/mkdocs.yml | 7 +- 18 files changed, 485 insertions(+), 46 deletions(-) rename docs/docs/user-guide/getting-started/{crossfading.md => cross-fading.md} (59%) create mode 100644 docs/docs/user-guide/transition-scheduler/jingle.md diff --git a/_externals/BassMusic.d b/_externals/BassMusic.d index 358a7ce..e4b62cf 100644 --- a/_externals/BassMusic.d +++ b/_externals/BassMusic.d @@ -3,7 +3,7 @@ // var string BassMusic_ActiveThemeFilename // Holds the filename of currently played song or the last song if none is playing now. // --------------------------------------------------------------- -var string BassMusic_ActiveThemeFilename; +var string BassMusic_ActiveThemeFilename;BassMusic_ActiveThemeFilename // --------------------------------------------------------------- // var string BassMusic_ActiveThemeID diff --git a/docs/docs/reference/classes/C_MUSICTHEME.md b/docs/docs/reference/classes/C_MUSICTHEME.md index 54dfa27..fb6273b 100644 --- a/docs/docs/reference/classes/C_MUSICTHEME.md +++ b/docs/docs/reference/classes/C_MUSICTHEME.md @@ -1 +1,32 @@ -# C_MUSICTHEME \ No newline at end of file +# C_MUSICTHEME + +## Description + +The class represents a music theme that can be played by the plugin. + +## Definition + +```dae +class C_MUSICTHEME +{ + var string file; + var float vol; + var int loop; + var float reverbmix; + var float reverbtime; + var int transtype; + var int transsubtype; +}; +``` + +## Fields + +| Field | Type | Description | +|----------------|--------|-------------------------------------| +| `file` | string | The filename of the music theme. | +| `vol` | float | The volume of the music theme. | +| `loop` | int | If true, music will loop after nd | +| `reverbmix` | float | The reverb mix of the music theme. | +| `reverbtime` | float | The reverb time of the music theme. | +| `transtype` | int | The type of the transition. | +| `transsubtype` | int | The subtype of the transition. | \ No newline at end of file diff --git a/docs/docs/reference/externals/index.md b/docs/docs/reference/externals/index.md index 1d9ec0e..4cf3246 100644 --- a/docs/docs/reference/externals/index.md +++ b/docs/docs/reference/externals/index.md @@ -15,9 +15,9 @@ func void BassMusic_Play(var string id) * `#!dae var string id`
Symbol name of the music theme ([C_MUSICTHEME](../classes/C_MUSICTHEME.md)) to play -## BassMusic_SetFullScriptControl +## BassMusic_SetFullScriptControl -... +Set the "Full Script Control" ```dae func void BassMusic_SetFullScriptControl(int enabled) {} @@ -29,4 +29,103 @@ func void BassMusic_SetFullScriptControl(int enabled) {} Boolean value if full script control should be enabled. +## BassMusic_OnEndEvent + +Set a callback function to be called when the music ends. + +```dae +func void BassMusic_OnEndEvent(var func callback) {} +``` + +**Parameters** + +* `#!dae var func callback`
+ Callback function to be called when the music ends with signature:
+ `#!dae func void callback();` + +## BassMusic_OnTransitionEvent + +Set a callback function to be called when the music is close to the end and transition starts. + +```dae +func void BassMusic_OnTransitionEvent(var func callback) {} +``` + +**Parameters** + +* `#!dae var func callback`
+ Callback function to be called when the music is close to the end and transition starts:
+ `#!dae func void callback(var float time_left_ms);` + +## BassMusic_OnChangeEvent + +Set a callback function to be called when the music changes. + +```dae +func void BassMusic_OnChangeEvent(var func callback) {} +``` + +**Parameters** + +* `#!dae var func callback`
+ Callback function to be called when the music changes with signature:
+ `#!dae func void callback();` + +## BassMusic_Opt_TransitionTime + +Set [Bass].TransitionTime ini setting. + +```dae +func void BassMusic_Opt_TransitionTime(var float time) {} +``` + +**Parameters** + +* `#!dae var float time`
+ The transition time in miliseconds + +## BassMusic_Opt_ForceDisableReverb + +Set [Bass].ForceDisableReverb ini setting. + +```dae +func void BassMusic_Opt_ForceDisableReverb(var int enabled) {} +``` + +**Parameters** + +* `#!dae var int enabled`
+ If true, the reverb effect is globally disabled + +## BassMusic_Opt_ForceFadeTransition + +Set [Bass].ForceFadeTransition ini setting. + +```dae +func void BassMusic_Opt_ForceFadeTransition(var int enabled) {} +``` + +**Parameters** + +* `#!dae var int enabled`
+ If true, the fade transition is globally enabled + +## BassMusic_TransitionRule_OnBeat + +Add a new OnBeat rule to the Transition Scheduler. + +```dae +func void BassMusic_TransitionRule_OnBeat(var string name, var string interval, var string timeCodes) {} +``` + +**Parameters** + +* `#!dae var string name`
+ Input music theme name +* `#!dae var string interval`
+ String formatted as double, the interval of a beat in seconds. Set "0" to disable. +* `#!dae var string timeCodes`
+ String formatted as a list of semicolon-separated doubles, the time codes in seconds when the transition can happen, + eg. `"0.0;1.0;2.0;3.0"` + \ No newline at end of file diff --git a/docs/docs/reference/globals/index.md b/docs/docs/reference/globals/index.md index 54fcf63..9c12578 100644 --- a/docs/docs/reference/globals/index.md +++ b/docs/docs/reference/globals/index.md @@ -1,5 +1,21 @@ # Globals -
+
-## `var string BassMusic_ActiveThemeFilename` \ No newline at end of file +## BassMusic_ActiveThemeFilename + +Holds the filename of the currently active theme. + +```dae +var string BassMusic_ActiveThemeFilename; +``` + +## BassMusic_ActiveThemeID + +Hods the ID (symbol name) of the currently active theme. + +```dae +var string BassMusic_ActiveThemeID; +``` + +
\ No newline at end of file diff --git a/docs/docs/reference/index.md b/docs/docs/reference/index.md index 4a938e0..2a75dc1 100644 --- a/docs/docs/reference/index.md +++ b/docs/docs/reference/index.md @@ -1 +1,31 @@ -# Reference \ No newline at end of file +# Reference + +## Classes + +* [C_MUSICTHEME](classes/C_MUSICTHEME.md) + +## Globals + +* [BassMusic_ActiveThemeFilename](globals/index.md#bassmusic_activethemefilename) +* [BassMusic_ActiveThemeID](globals/index.md#bassmusic_activethemeid) + +## Externals + +* [BassMusic_Play](externals/index.md#bassmusic_play) +* [BassMusic_SetFullScriptControl](externals/index.md#bassmusic_setfullscriptcontrol) +* [BassMusic_OnEndEvent](externals/index.md#bassmusic_onendevent) +* [BassMusic_OnTransitionEvent](externals/index.md#bassmusic_ontransitionevent) +* [BassMusic_OnChangeEvent](externals/index.md#bassmusic_onchangeevent) +* [BassMusic_Opt_TransitionTime](externals/index.md#bassmusic_opt_transitiontime) +* [BassMusic_Opt_ForceDisableReverb](externals/index.md#bassmusic_opt_forcedisablereverb) +* [BassMusic_Opt_ForceFadeTransition](externals/index.md#bassmusic_opt_forcefadetransition) +* [BassMusic_TransitionRule_OnBeat](externals/index.md#bassmusic_transitionrule_onbeat) + +## Options (.ini) + +* [[BassMusic] TransitionTime](options/index.md#transitiontime) +* [[BassMusic] ForceDisableReverb](options/index.md#forcedisablereverb) +* [[BassMusic] ForceFadeTransition](options/index.md#forcefadetransition) +* [[BassMusic] CreateMainParserCMusicTheme](options/index.md#createmainparsercmusictheme) +* [[BassMusic] LoggerLevelUnion](options/index.md#loggerlevelunion) +* [[BassMusic] LoggerLevelZSpy](options/index.md#loggerlevelzspy) \ No newline at end of file diff --git a/docs/docs/reference/options/index.md b/docs/docs/reference/options/index.md index a9bda27..26d0682 100644 --- a/docs/docs/reference/options/index.md +++ b/docs/docs/reference/options/index.md @@ -1,6 +1,57 @@ # Options (.ini) -## [BassMusic] +
-
-### LoggerLevelUnion +Options are defined under `[BassMusic]` sction. + +## TransitionTime + +The time of the crossfade transition in milliseconds. + +```dae +TransitionTime=2000 +``` + +## ForceDisableReverb + +If true, all reverb effects are disabled. + +```dae +ForceDisableReverb=0 +``` + +## ForceFadeTransition + +If true, all transitions use cross-fade even if it's not set in the theme. + +```dae +ForceFadeTransition=0 +``` + +## CreateMainParserCMusicTheme + +If true, the class [C_MUSICTHEME](../classes/C_MUSICTHEME.md) is also created within the main scripts' parser +and you can define music themes in Content scripts. Be aware that it doesn't provide any sharing between parsers +so you can't use instance from music parser in the main parser - then you have to redefine it in the other + +```dae +CreateMainParserCMusicTheme=1 +``` + +## LoggerLevelUnion + +Sets the logger level for Union Console logs + +```dae +LoggerLevelUnion=INFO +``` + +## LoggerLevelZSpy + +Sets the logger level for ZSpy logs + +```dae +LoggerLevelZSpy=DEBUG +``` + +
\ No newline at end of file diff --git a/docs/docs/roadmap/index.md b/docs/docs/roadmap/index.md index 40e536a..3e721f2 100644 --- a/docs/docs/roadmap/index.md +++ b/docs/docs/roadmap/index.md @@ -5,16 +5,23 @@ hide: # Roadmap +
+!!! success "Done" +!!! info "In Progress" +!!! warning "Waiting in Queue" +!!! danger "Planned" +
+ ## Done ### Core functions -!!! success "Music Engine (v0.1.0)" +??? success "Music Engine (v0.1.0)" Music engine capable of replacing the original DM system in the scope of playing audio and switching songs based on game events. -!!! success "Daedalus API for controlling playback (v0.1.0)" +??? success "Daedalus API for controlling playback (v0.1.0)" External functions to take control over music scheduling in Daedalus scripts. API is stable and shouldn't introduce any breaking changes. -!!! success "Simple crossfade (v0.1.0)" +??? success "Simple crossfade (v0.1.0)" Every music theme can opt-in for simple fade-in and fade-out transitions to smoothly crossfade changing themes. The crossfade time is set globally and the transition starts instantly after receiving an event from the game. @@ -23,41 +30,40 @@ hide: ### Transition Scheduler -!!! info "Transition Scheduler (v0.1.x)" +??? info "Transition Scheduler (v0.2.x)" Scheduler for executing advanced transitions between songs based on defined rules. The system should be flexible and offer different transition effects behind an easy-to-use interface. The artist should be able to define rules with high precision (soft goal: <10ms latency). - !!! success "Instant Transition (Done)" + ??? success "Instant Transition (Done)" Default transition starts the effect instantly after receiving an event from the game. - !!! success "OnBeat Transition (Done)" + ??? success "OnBeat Transition (Done)" Transition accepts a list of time points when the transition can happen and schedules it for the closest point. This way the song may switch exactly in a moment when the beat ends to match the rhythm. - !!! warning "Jingle Transition (To Do)" + ??? warning "Jingle Transition (To Do)" Transition plays an additional short audio during the transition as a one-time jingle. For example, battle music transitioning into normal can play some theme to emphasize the end of a fight. - !!! question "Format for defining the transition rules (Analysis / Planning)" - We are still thinking about how can we accept the transition rules from developers. The options to consider are: - - * Daedalus API (not very ergonomic to pass lots of data) - * MIDI file (easy to work with for composers because they can do it directly in their DAW) - * Custom file format (we prefer not to introduce additional custom formats that require custom tooling) +??? info "MIDI bridge for Transition Scheduler (v0.2.x)" + The MIDI format is the best option for defining rules for the Transition Scheduler. The composer can just + put all the information about the transitions as MIDI events on some muted track in DAW and export it to the plugin. + The composer uses a tool he knows, and we can extract precise information from the MIDI file perfectly synchronized + with the music. - We may choose more than one option. At this moment the best option seems to be MIDI for defining time points + Daedalus API to setup - additional metadata. + The bridge defines a spec how to interpret MIDI events and how they map to the internal structures of the Transition Scheduler. + Then the bridge can load MIDI files and provide the rules to the scheduler. ## Future Plans -!!! question "New features?" +??? question "New features?" We still may plan to implement some new features if they can provide value. -!!! warning "Support late injection" +??? danger "Support late injection" Right now the plugin hooks early into Gothic initialization to set itself up and replace the `zmusic` pointer with a custom implementation. We should add support for late initialization and let the plugin be loaded by Daedalus/Ikaus scripts. -!!! danger "Complete Product Release (v1.0.0)" +??? danger "Complete Product Release (v1.0.0)" Before we release version v1.0.0 and mark zBassMusic as a finished product, we need to: * finish all the features in the backlog diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css index 0c5f7b6..52dc0fb 100644 --- a/docs/docs/stylesheets/extra.css +++ b/docs/docs/stylesheets/extra.css @@ -93,4 +93,13 @@ margin: 0 !important; padding: 0 !important; +} + +.roadmap-legend .admonition { + margin: 0 auto; + font-size: 0.7rem; +} + +.md-main { + margin-bottom: 3rem; } \ No newline at end of file diff --git a/docs/docs/user-guide/debugging/index.md b/docs/docs/user-guide/debugging/index.md index e69de29..89843ec 100644 --- a/docs/docs/user-guide/debugging/index.md +++ b/docs/docs/user-guide/debugging/index.md @@ -0,0 +1,36 @@ +# Debugging + +If you encounter any issues with the application, you can use the following tools to help you debug the problem. + +## Union Console + +Union can start a console window alongside with Gothic and catch standard output where we print a lot of logs. +To enable the console, you need to set following settings in the `SystemPack.ini` file: + +```ini +[CORE] +ShowDebugWindow = true +UseDebugWindowHost = true +``` + +## Logging Level + +By default, we print only the severity >=INFO to Union Console and >=DEBUG to ZSpy. +To print all logs to the console, you can set TRACE logging level in `Gothic.ini`: + +```ini +[BASSMUSIC] +LoggerLevelUnion=TRACE +LoggerLevelZSpy=TRACE +``` + +## Debug Symbols + +Standard Release build does not contain debug symbols, so you cannot debug the application in the debugger easily +because you will see only the optimized assembly code. + +If you encounter a crash on Release build, +please download the builds suffixed with `-pdb` like `zBassMusic-v0.1.4-pdb.zip` and replace Release with them. +These builds contain debug symbols, and now you can start Gothic with a debugger attached to catch the exception +causing the crash and see the source code where it happened. +If you get some additional information about the crash from the debugger, please include it in the bug report. diff --git a/docs/docs/user-guide/getting-started/crossfading.md b/docs/docs/user-guide/getting-started/cross-fading.md similarity index 59% rename from docs/docs/user-guide/getting-started/crossfading.md rename to docs/docs/user-guide/getting-started/cross-fading.md index 54fa362..7058e6d 100644 --- a/docs/docs/user-guide/getting-started/crossfading.md +++ b/docs/docs/user-guide/getting-started/cross-fading.md @@ -1,13 +1,15 @@ -# Crossfading +# Cross-fading -zBassMusic implements basic fade-in and fade-out effects to crossfade between songs but it's activated only +zBassMusic implements basic fade-in and fade-out effects to crossfade between songs, but it's activated only if the music theme defines a correct `transtype`. We support: * `TRANSITION_TYPE_INTRO` (= 5) - fade-in effect at the start * `TRANSITION_TYPE_END` (= 6) - fade-out effect at the end * `TRANSITION_TYPE_ENDANDINTRO` (= 7) - both fade-in and fade-out effects -The best default is to use `TRANSITION_TYPE_ENDANDINTRO` because it defines both start and end effects. If you would have one song with `TRANSITION_TYPE_END` and another song without `TRANSITION_TYPE_INTRO`, then during the transition the first sound would fade out but the second one would start minutely at 100% volume. +The best default is to use `TRANSITION_TYPE_ENDANDINTRO` because it defines both start and end effects. +If you had one song with `TRANSITION_TYPE_END` and another song without `TRANSITION_TYPE_INTRO`, +then during the transition the first sound would fade out but the second one would start instantly at 100% volume. ```dae prototype C_MUSICTHEME_FIGHT(C_MUSICTHEME) @@ -24,4 +26,6 @@ prototype C_MUSICTHEME_FIGHT(C_MUSICTHEME) }; ``` -Other values of `transtype` and all values of `transsubtype` are ignored because zBassMusic can't emulate them on arbitrary audio files with no MIDI metadata. The advanced transitions are implemented by the plugin in [Transition Scheduler](../transition-scheduler/index.md). \ No newline at end of file +Other values of `transtype` and all values of `transsubtype` are ignored because zBassMusic can't emulate them on +arbitrary audio files with no MIDI metadata. +The advanced transitions are implemented by the plugin in [Transition Scheduler](../transition-scheduler/index.md). \ No newline at end of file diff --git a/docs/docs/user-guide/getting-started/plugin-loading.md b/docs/docs/user-guide/getting-started/plugin-loading.md index c978874..287811b 100644 --- a/docs/docs/user-guide/getting-started/plugin-loading.md +++ b/docs/docs/user-guide/getting-started/plugin-loading.md @@ -13,7 +13,7 @@ with hundreds of GothicStarter entries, so you don't want to break someone's gam This method requires the player to install Union. Good option if your mod already uses other Union plugins and the runtime is there. -!!! danger "Global Method" +??? danger "Global Method" Choose either ZIP or VDF. Both work the same. @@ -25,7 +25,7 @@ This method requires the player to install Union. Good option if your mod alread Copy `zBassMusic.vdf`
To `/Data/` -!!! success "Isolated Method" +??? success "Isolated Method" The isolated method is possible if you are placing your mod in `/Data/ModVDF` and declare .mod file in `YourMod.ini`. @@ -49,7 +49,7 @@ This method requires the player to install Union. Good option if your mod alread It's possible to load zBassMusic on a clean Gothic with only System Pack using `pre.load` file but it's always global. -!!! danger "Global Method" +??? danger "Global Method" From ZIP release:
Copy `zBassMusic.dll`, `UnionAPI.dll`, `bass.dll`
@@ -69,7 +69,7 @@ file but it's always global. If you are using Ikarus in your scripts, it's possible to load dynamically any DLL using `LoadLibrary("AnyLib.dll")` function. The function is conveniently provided by Ikarus and this method is always isolated. -!!! success "Isolated Method" +??? success "Isolated Method" From ZIP release:
Copy `zBassMusic.dll`, `UnionAPI.dll`, `bass.dll`
diff --git a/docs/docs/user-guide/scripting/custom-scheduler.md b/docs/docs/user-guide/scripting/custom-scheduler.md index ee0646a..73e58f1 100644 --- a/docs/docs/user-guide/scripting/custom-scheduler.md +++ b/docs/docs/user-guide/scripting/custom-scheduler.md @@ -1 +1,24 @@ -# Custom Scheduler \ No newline at end of file +# Custom Scheduler + +Example of a custom scheduler that plays [OLD_CAMP, NEW_CAMP, SWAMP_CAMP] in a loop. +The event handler listens for transition start and schedules next theme based on the current one. + +```dae +void OnTransition(var float time_left) { + if (Hlp_StrCmp(BassMusic_ActiveThemeID, "OLD_CAMP") == 0) { + BassMusic_Play("NEW_CAMP"); + } else if (Hlp_StrCmp(BassMusic_ActiveThemeID, "NEW_CAMP") == 0) { + BassMusic_Play("SWAMP_CAMP"); + } else if (Hlp_StrCmp(BassMusic_ActiveThemeID, "SWAMP_CAMP") == 0) { + BassMusic_Play("OLD_CAMPP"); + } +}; + +void INIT_GLOBAL() { + Game_InitGerman(); + + BassMusic_SetFullScriptControl(true); + BassMusic_OnTransitionEvent(OnTransition); + BassMusic_Play("OLD_CAMP"); +}; +``` diff --git a/docs/docs/user-guide/scripting/index.md b/docs/docs/user-guide/scripting/index.md index 737fe1a..208fd9d 100644 --- a/docs/docs/user-guide/scripting/index.md +++ b/docs/docs/user-guide/scripting/index.md @@ -1 +1,84 @@ -# Scripting (Daedalus) \ No newline at end of file +# Scripting (Daedalus) + +The plugin defines several external functions that let us interact with the Music Engine from Daedalus scripts. +The full list of available functions can be found in the [Reference](../reference/index.md) page, and here we +will cover only the "Full Script Control" mode. + +## Full Script Control + +You can enable the Full Script Control mode in scripts to disable automatic music scheduling based on music zones +and play your own music themes without any interference from the standard mechanism. + +```dae +BassMusic_SetFullScriptControl(true); +``` + +When the Full Script Control mode is enabled, the plugin will not play any music themes automatically and you +have to do it yourself using the `BassMusic_Play` function. + +```dae +BassMusic_Play("MyTheme"); +``` + + +When you are done with the custom music playback, you can disable the Full Script Control mode and get the +original schedulers back. + +```dae +BassMusic_SetFullScriptControl(false); +``` + +## Global variables + +You can access currently playing music theme using global variables. + +```dae +var string BassMusic_ActiveThemeFilename; // eg. OLD_CAMP.mp3 +var string BassMusic_ActiveThemeID; // eg. OLD_CAMP +``` + +## Events + +You can handle some music events in the scripts by registering a callback function. + +### OnEnd + +```dae +func void OnEnd() { + // Do something when the music ends +}; + +BassMusic_OnEndEvent(OnEnd); +``` + +### OnTransition + +```dae +func void OnTransition(var int time_left_ms) { + // Do something when the transition is about to happen + // time_left_ms is the time left to the end of the current +}; + +BassMusic_OnTransitionEvent(OnTransition); +``` + +### OnChange + +```dae +func void OnChange() { + // Do something when the music theme changes +}; + +BassMusic_OnChangeEvent(OnChange); +``` + +## Options + +Some .ini options can be set from the scripts. It may be useful if you are taking full control over the music playback. + +```dae +func void BassMusic_Opt_TransitionTime(var float time) {}; +func void BassMusic_Opt_ForceDisableReverb(var int enabled) {}; +func void BassMusic_Opt_ForceFadeTransition(var int enabled) {}; +``` + diff --git a/docs/docs/user-guide/transition-scheduler/index.md b/docs/docs/user-guide/transition-scheduler/index.md index baf60e6..0be9c8a 100644 --- a/docs/docs/user-guide/transition-scheduler/index.md +++ b/docs/docs/user-guide/transition-scheduler/index.md @@ -1 +1,15 @@ -# Transitions Scheduler \ No newline at end of file +# Transitions Scheduler + +!!! note "Preview" + This feature is still under development and may change significantly in the future. + +Transition Scheduler is a module providing advanced transitions between music themes that need to be precisely +synchronized and accord to the defined rules. +For example, OnBeat rule limits the time points when the transition can occur and schedules the transition for +the closest point in the future, so the composer can design seamless transitions with a perfect match to the beat. + +Available transition rules: + +* [Instant](instant.md) - immediate transition [default] +* [OnBeat](on-beat.md) - transition only on specific time points +* [Jingle](jingle.md) - transition with another sound inbetween \ No newline at end of file diff --git a/docs/docs/user-guide/transition-scheduler/instant.md b/docs/docs/user-guide/transition-scheduler/instant.md index 8c27579..d5187e4 100644 --- a/docs/docs/user-guide/transition-scheduler/instant.md +++ b/docs/docs/user-guide/transition-scheduler/instant.md @@ -1 +1,3 @@ -# Instant Transition \ No newline at end of file +# Instant Transition + +Instant transition is the default transition rule. It immediately switches to the next theme without any delay. \ No newline at end of file diff --git a/docs/docs/user-guide/transition-scheduler/jingle.md b/docs/docs/user-guide/transition-scheduler/jingle.md new file mode 100644 index 0000000..d4c5387 --- /dev/null +++ b/docs/docs/user-guide/transition-scheduler/jingle.md @@ -0,0 +1,5 @@ +# Jingle Transition + +!!! danger "Not implemented" + This feature is not implemented yet. + diff --git a/docs/docs/user-guide/transition-scheduler/on-beat.md b/docs/docs/user-guide/transition-scheduler/on-beat.md index 659dad8..7a909cc 100644 --- a/docs/docs/user-guide/transition-scheduler/on-beat.md +++ b/docs/docs/user-guide/transition-scheduler/on-beat.md @@ -1 +1,34 @@ -# OnBeat Transition \ No newline at end of file +# OnBeat Transition + +!!! note "Preview" + This feature is still under development and may change significantly in the future. + +OnBeat transition is a rule that schedules the transition for the closest point in the future from the list of +allowed points. +In this Release, the OnBeat rule can be activated only by using a Daedalus external and matches the input theme +to any output. +In the future, we plan to allow providing time points using a MIDI file synchronized with the music +and scope the rule to specific (input, output) pairs. + +## Daedalus API + +### Activate on an interval +The second argument accepts a string formatted as a double that defines the interval of the beat in seconds. +Transition can happen at any multiplier of the interval. + +```dae +// Will activate on [2.66, 5.32, 7.98, ...] +BassMusic_TransitionRule_OnBeat("Input_Theme", "2.66", ""); +``` + +### Activate on a specific time points +The third argument accepts a string formatted as a semicolon-separated list of doubles that defines the exact time points in seconds. +Transition can happen only at the specified time points. + +```dae +// Will activate on [1.2, 2.4, 7.33, 12.97] +BassMusic_TransitionRule_OnBeat("Input_Theme", "0", "1.2;2.4;7.33;12.97"); +``` + +You can also mix both arguments to create a rule with constant interval + some additional points. +The scheduler will always choose the closest point in the future. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 4ef3e4c..c107701 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,11 +10,12 @@ nav: - user-guide/getting-started/index.md - user-guide/getting-started/plugin-loading.md - user-guide/getting-started/music-definition.md - - user-guide/getting-started/crossfading.md + - user-guide/getting-started/cross-fading.md - Transition Scheduler: - user-guide/transition-scheduler/index.md - user-guide/transition-scheduler/instant.md - user-guide/transition-scheduler/on-beat.md + - user-guide/transition-scheduler/jingle.md - Scripting (Daedalus): - user-guide/scripting/index.md - user-guide/scripting/custom-scheduler.md @@ -26,14 +27,10 @@ nav: - reference/classes/C_MUSICTHEME.md - Globals: - reference/globals/index.md - - BassMusic_ActiveThemeFilename: reference/globals/#bassmusic_activethemefilename - Externals: - reference/externals/index.md - - BassMusic_Play: reference/externals/#bassmusic_play - Options (.ini): - reference/options/index.md - - '[BassMusic]': - - LoggerLevelUnion: reference/options/#loggerlevelunion - Developer Guide: - developer-guide/index.md - Environment: