diff --git a/docs/docs/configuration/index.md b/docs/docs/configuration/index.md new file mode 100644 index 0000000..af4abbf --- /dev/null +++ b/docs/docs/configuration/index.md @@ -0,0 +1 @@ +# Configuration \ No newline at end of file diff --git a/docs/docs/developer-guide/architecture/index.md b/docs/docs/developer-guide/architecture/index.md new file mode 100644 index 0000000..f2569bf --- /dev/null +++ b/docs/docs/developer-guide/architecture/index.md @@ -0,0 +1 @@ +# Architecture \ No newline at end of file diff --git a/docs/docs/developer-guide/code-style/index.md b/docs/docs/developer-guide/code-style/index.md new file mode 100644 index 0000000..46530fa --- /dev/null +++ b/docs/docs/developer-guide/code-style/index.md @@ -0,0 +1 @@ +# Code Style \ No newline at end of file diff --git a/docs/docs/developer-guide/contributing/index.md b/docs/docs/developer-guide/contributing/index.md new file mode 100644 index 0000000..4d218d9 --- /dev/null +++ b/docs/docs/developer-guide/contributing/index.md @@ -0,0 +1 @@ +# Contributing \ No newline at end of file diff --git a/docs/docs/developer-guide/environment/index.md b/docs/docs/developer-guide/environment/index.md new file mode 100644 index 0000000..ad00dca --- /dev/null +++ b/docs/docs/developer-guide/environment/index.md @@ -0,0 +1 @@ +# Environment \ No newline at end of file diff --git a/docs/docs/developer-guide/index.md b/docs/docs/developer-guide/index.md new file mode 100644 index 0000000..6f8d214 --- /dev/null +++ b/docs/docs/developer-guide/index.md @@ -0,0 +1 @@ +# Developer Guide \ No newline at end of file diff --git a/docs/docs/images/android-chrome-192x192.png b/docs/docs/images/android-chrome-192x192.png new file mode 100644 index 0000000..0ef49eb Binary files /dev/null and b/docs/docs/images/android-chrome-192x192.png differ diff --git a/docs/docs/images/android-chrome-512x512.png b/docs/docs/images/android-chrome-512x512.png new file mode 100644 index 0000000..152a4bc Binary files /dev/null and b/docs/docs/images/android-chrome-512x512.png differ diff --git a/docs/docs/images/apple-touch-icon.png b/docs/docs/images/apple-touch-icon.png new file mode 100644 index 0000000..21e6d45 Binary files /dev/null and b/docs/docs/images/apple-touch-icon.png differ diff --git a/docs/docs/images/favicon-16x16.png b/docs/docs/images/favicon-16x16.png new file mode 100644 index 0000000..61b07c4 Binary files /dev/null and b/docs/docs/images/favicon-16x16.png differ diff --git a/docs/docs/images/favicon-32x32.png b/docs/docs/images/favicon-32x32.png new file mode 100644 index 0000000..4165ae3 Binary files /dev/null and b/docs/docs/images/favicon-32x32.png differ diff --git a/docs/docs/images/favicon.ico b/docs/docs/images/favicon.ico new file mode 100644 index 0000000..302da99 Binary files /dev/null and b/docs/docs/images/favicon.ico differ diff --git a/docs/docs/images/favicon@2x.png b/docs/docs/images/favicon@2x.png new file mode 100644 index 0000000..6af13dd Binary files /dev/null and b/docs/docs/images/favicon@2x.png differ diff --git a/docs/docs/images/logo.svg b/docs/docs/images/logo.svg new file mode 100644 index 0000000..1067ee3 --- /dev/null +++ b/docs/docs/images/logo.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/docs/docs/images/site.webmanifest b/docs/docs/images/site.webmanifest new file mode 100644 index 0000000..45dc8a2 --- /dev/null +++ b/docs/docs/images/site.webmanifest @@ -0,0 +1 @@ +{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"} \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..41ba4ea --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,116 @@ +--- +name: zBassMusic +--- + +# zBassMusic + +zBassMusic is a modern music system for Gothic games based on ZenGin. +It replaces the original DirectMusic system with a custom engine built on top of [BASS Library](https://www.un4seen.com/) +to provide easier workflow for composers and additional functions for the perfect soundtrack design. +The most important features include: + +* Direct playback of common audio formats (WAV, OGG, MP3) instead of DirectMusic propertiary formats +* Out-of-the-box support for existing music theme definitions (just change the audio file) +* Alternative scheduling & transition systems to support smooth crossfades between themes +* Loading of music files from VDF volumes (DirectMusic required physical files) +* Scriptable interface for controlling the system from Deadalus scripts +* Backward compatibility with original `.sgt` music (it's redirected to the DirectMusic system) + + +!!! tip "Project Status" + + zBassMusic is still in the development phase and some APIs may be unstable, incomplete or buggy. You can help the project by + using the plugin and reporting bugs or proposing ideas for the next features. The current state and plans for the future are + on the [Roadmap](roadmap/index.md). + + +
+ +- ::octicons-rocket-16:{ .lg .middle } __Release Builds__ + + --- + + Release builds are ready to be used in Gothic and we publish them automatically on our GitHub. + + [:octicons-arrow-right-24: Releases](https://github.com/Silver-Ore-Team/zBassMusic/releases) + +- :fontawesome-brands-github:{ .lg .middle } __Source Code__ + + --- + + zBassMusic is open source and you can access the code on our public repo hosted by GitHub. + + [:octicons-arrow-right-24: GitHub](https://github.com/Silver-Ore-Team/zBassMusic) + +- :fontawesome-solid-bug:{ .lg .middle } __Bug Reporting__ + + --- + + If you have found a bug in zBassMusic, please create an issue on GitHub and tell us what's wrong. + + [:octicons-arrow-right-24: Issues](https://github.com/Silver-Ore-Team/zBassMusic/issues) + +- :fontawesome-regular-message:{ .lg .middle } __Discussions__ + + --- + + We listen to ideas for new features, so if something is missing from zBassMusic, let us know and we'll do it. + + [:octicons-arrow-right-24: Discussions](https://github.com/Silver-Ore-Team/zBassMusic/discussions) + +
+ + +## For modders + +zBassMusic is designed exclusively for Gothic modders to include it in their mods and it's licensed +under a permissive [MIT License](https://github.com/Silver-Ore-Team/zBassMusic/blob/main/LICENSE), +so you can use the plugin for free in any project[^1]. +It's built using the new [union-api](https://gitlab.com/union-framework/union-api) and can be embedded +either as a Union 1.0m plugin or as a completely standalone plugin for base Gothic with System Pack. + +Check out [Getting Started](getting-started/index.md) for instructions how to start working with zBassMusic. + +[^1]: zBassMusic depends on vendored libraries [union-api](https://gitlab.com/union-framework/union-api) and [gothic-api]() + licensed under [GNU GPL Version 3](https://gitlab.com/union-framework/union-api/-/blob/main/LICENSE) + and on propertiary licensed [BASS Library](https://www.un4seen.com/) that's free for non-commercial use only. + Make sure you are not violating these terms while using zBassMusic. + +## For players + +Unlike most Union plugins, zBassMusic doesn't provide any functions directly for the players who just play base game or some +other mod utilizing the original music system. In order to make use of the plugin, you have to actually put your music in the +game, so there is no point of installing zBassMusic if you are not making a mod. + +## Repository + +zBassMusic is an open source project with the source code available on GitHub. + +- [GitHub Repository](https://github.com/Silver-Ore-Team/zBassMusic) +- [Release Builds](https://github.com/Silver-Ore-Team/zBassMusic/releases) +- [Bug Reporting](https://github.com/Silver-Ore-Team/zBassMusic/issues) +- [Discussions](https://github.com/Silver-Ore-Team/zBassMusic/discussions) + +## Authors + +zBassMusic development started in 2023 as an internal plugin for [Nek's History](https://silveroreteam.pl/en/projects/nek) +to ease the collaboration with our composer[^2] who had zero knowledge of DirectMusic Producer workflow and forcing him to learn it +would be a complete waste of time and possibly limit the creativity. Sometime later the internal code base based on Union SDK 1.0m +was rewritten for [union‑api](https://gitlab.com/union-framework/union-api) — the successor of Union SDK, and published as an open source project. + +The project is maintained under [Silver Ore Team](https://silveroreteam.pl) modding group by [tehe](https://github.com/piotrmacha): + +* Email: [piotr.macha@silveroreteam.pl](mailto:piotr.macha@silveroreteam.pl) +* Discord: [@tehe.official](https://discordapp.com/users/1014655735856111678) + +The mentionable contributors for the early stage development are [Boguś](https://github.com/bogu9821) and [Emu](https://github.com/muczc1wek) who have helped sorting some things up. If you'd like to also help zBassMusic development, check out [Developer Guide](developer-guide/index.md) +and feel free to submit a Pull Request. One accepted merge and you will join the gallery. + +
+ +![Mosaic of zBassMusic contributors](https://contrib.nn.ci/api?repo=Silver-Ore-Team/zBassMusic) + +
+ +[^2]: [Adam Dzieżyk](https://adamdziezyk.com/), composer for Golden Gate, Golden Gate 2, Nek's History and many non-Gothic projects. + Also a reason why zBassMusic exists. \ No newline at end of file diff --git a/docs/docs/javascripts/mathjax.js b/docs/docs/javascripts/mathjax.js new file mode 100644 index 0000000..3d0d925 --- /dev/null +++ b/docs/docs/javascripts/mathjax.js @@ -0,0 +1,19 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } + }; + + document$.subscribe(() => { + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() + MathJax.typesetPromise() + }) \ No newline at end of file diff --git a/docs/docs/reference/index.md b/docs/docs/reference/index.md new file mode 100644 index 0000000..4a938e0 --- /dev/null +++ b/docs/docs/reference/index.md @@ -0,0 +1 @@ +# Reference \ No newline at end of file diff --git a/docs/docs/roadmap/index.md b/docs/docs/roadmap/index.md new file mode 100644 index 0000000..ae378c9 --- /dev/null +++ b/docs/docs/roadmap/index.md @@ -0,0 +1,53 @@ +# Roadmap + +## Done + +### Core functions +!!! success "Music Engine (v0.1.0)" + Music engine capable of replacing 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)" + 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)" + 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. + + +## In Progress + +### Transition Scheduler + +!!! info "Transition Scheduler (v0.1.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)" + Default transition starts the effect instantly after receiving an event from the game. + + !!! 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)" + 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) + + 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. + +## Future Plans + +!!! 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 + * battle-test the system by having it working in multiple released Gothic mods + * fix all bugs and crashes that have a meaningful probability of causing Access Violation on players' games \ No newline at end of file diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css new file mode 100644 index 0000000..fa52c9a --- /dev/null +++ b/docs/docs/stylesheets/extra.css @@ -0,0 +1,29 @@ +/* #a00*/ +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #830404; + --md-typeset-a-color: rgb(255, 143, 143); +} + +.md-content { + max-width: 160ch; +} + +.grid.cards { + margin-top: 1.5rem; + margin-bottom: 2.5rem; + grid-gap: 0.8rem; +} + +.grid.cards > ul > li > p > span + strong { + margin-left: 10px; + vertical-align: -2px; + font-size: 0.9rem; +} + +.footnote { + margin-top: 2rem; +} + +.zbassmusic-contributos { + margin-top: 1rem; +} \ No newline at end of file diff --git a/docs/docs/user-guide/debugging/index.md b/docs/docs/user-guide/debugging/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/user-guide/define-music.md b/docs/docs/user-guide/define-music.md new file mode 100644 index 0000000..7f04af0 --- /dev/null +++ b/docs/docs/user-guide/define-music.md @@ -0,0 +1 @@ +# Define Music \ No newline at end of file diff --git a/docs/docs/user-guide/getting-started/crossfading.md b/docs/docs/user-guide/getting-started/crossfading.md new file mode 100644 index 0000000..754552b --- /dev/null +++ b/docs/docs/user-guide/getting-started/crossfading.md @@ -0,0 +1 @@ +# Crossfading \ No newline at end of file diff --git a/docs/docs/user-guide/getting-started/index.md b/docs/docs/user-guide/getting-started/index.md new file mode 100644 index 0000000..31dd91e --- /dev/null +++ b/docs/docs/user-guide/getting-started/index.md @@ -0,0 +1,2 @@ +# Getting Started + diff --git a/docs/docs/user-guide/getting-started/music-definition.md b/docs/docs/user-guide/getting-started/music-definition.md new file mode 100644 index 0000000..fcdb744 --- /dev/null +++ b/docs/docs/user-guide/getting-started/music-definition.md @@ -0,0 +1 @@ +# Music Definition \ 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 new file mode 100644 index 0000000..0c5759c --- /dev/null +++ b/docs/docs/user-guide/getting-started/plugin-loading.md @@ -0,0 +1 @@ +# Plugin Loading \ No newline at end of file diff --git a/docs/docs/user-guide/index.md b/docs/docs/user-guide/index.md new file mode 100644 index 0000000..14e727f --- /dev/null +++ b/docs/docs/user-guide/index.md @@ -0,0 +1 @@ +# User Guide \ No newline at end of file diff --git a/docs/docs/user-guide/scripting/custom-scheduler.md b/docs/docs/user-guide/scripting/custom-scheduler.md new file mode 100644 index 0000000..ee0646a --- /dev/null +++ b/docs/docs/user-guide/scripting/custom-scheduler.md @@ -0,0 +1 @@ +# Custom Scheduler \ No newline at end of file diff --git a/docs/docs/user-guide/scripting/index.md b/docs/docs/user-guide/scripting/index.md new file mode 100644 index 0000000..737fe1a --- /dev/null +++ b/docs/docs/user-guide/scripting/index.md @@ -0,0 +1 @@ +# Scripting (Daedalus) \ No newline at end of file diff --git a/docs/docs/user-guide/transition-scheduler/index.md b/docs/docs/user-guide/transition-scheduler/index.md new file mode 100644 index 0000000..baf60e6 --- /dev/null +++ b/docs/docs/user-guide/transition-scheduler/index.md @@ -0,0 +1 @@ +# Transitions Scheduler \ 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 new file mode 100644 index 0000000..8c27579 --- /dev/null +++ b/docs/docs/user-guide/transition-scheduler/instant.md @@ -0,0 +1 @@ +# Instant Transition \ No newline at end of file diff --git a/docs/docs/user-guide/transition-scheduler/on-beat.md b/docs/docs/user-guide/transition-scheduler/on-beat.md new file mode 100644 index 0000000..8827144 --- /dev/null +++ b/docs/docs/user-guide/transition-scheduler/on-beat.md @@ -0,0 +1 @@ +# On Beat Transition \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..5737d73 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,120 @@ +site_name: zBassMusic +copyright: Copyright © 2024 Silver Ore Team +repo_url: https://github.com/Silver-Ore-Team/zBassMusic +nav: + - Home: index.md + - Roadmap: roadmap/index.md + - User Guide: + - user-guide/index.md + - Getting Started: + - 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 + - Transition Scheduler: + - user-guide/transition-scheduler/index.md + - user-guide/transition-scheduler/instant.md + - user-guide/transition-scheduler/on-beat.md + - Scripting (Daedalus): + - user-guide/scripting/index.md + - user-guide/scripting/custom-scheduler.md + - Debugging: + - user-guide/debugging/index.md + - Configuration: + - configuration/index.md + - Reference: + - reference/index.md + - Developer Guide: + - developer-guide/index.md + - Environment: + - developer-guide/environment/index.md + - Architecture: + - developer-guide/architecture/index.md + - Code Style: + - developer-guide/code-style/index.md + - Contributing: + - developer-guide/contributing/index.md + - Releases: + - developer-guide/releases/index.md +theme: + name: material + logo: images/logo.svg + favicon: images/favicon.ico + palette: + scheme: slate + primary: custom + highlightjs: true + hljs_languages: + - yaml + - ini + - cpp + - daedalus + - json + features: + - navigation.instant + - navigation.instant.prefetch + - navigation.footer + - navigation.tabs + - navigation.tabs.sticky + - content.code.copy + - content.code.select + - content.code.annotate + - navigation.indexes + - toc.integrate + - navigation.top + icon: + annotation: material/record-circle + admonition: + note: fontawesome/solid/note-sticky + abstract: fontawesome/solid/book + info: fontawesome/solid/circle-info + tip: fontawesome/solid/bullhorn + success: fontawesome/solid/check + question: fontawesome/solid/circle-question + warning: fontawesome/solid/triangle-exclamation + failure: fontawesome/solid/bomb + danger: fontawesome/solid/skull + bug: fontawesome/solid/robot + example: fontawesome/solid/flask + quote: fontawesome/solid/quote-left +markdown_extensions: + - admonition + - pymdownx.highlight: + linenums: true + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + use_pygments: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.details + - pymdownx.tabbed: + alternate_style: true + - tables + - footnotes + - attr_list + - md_in_html + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.arithmatex: + generic: true + - pymdownx.smartsymbols +plugins: + - search + - offline: + enabled: !ENV [OFFLINE, false] +extra_css: + - stylesheets/extra.css +extra: + generator: false + social: + - icon: fontawesome/brands/github + link: https://github.com/Silver-Ore-Team/zBassMusic + - icon: fontawesome/brands/discord + link: https://discord.gg/cvd6jhKB +extra_javascript: + - javascripts/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js \ No newline at end of file diff --git a/docs/options.md b/docs/options.md deleted file mode 100644 index 0554b7d..0000000 --- a/docs/options.md +++ /dev/null @@ -1,23 +0,0 @@ -# OptionsType reference (.ini) -```ini -[BASSMUSIC] - -; Transition time between audio themes in miliseconds -TransitionTime = 2000.0 - -; Disable reverb effect globally -ForceDisableReverb = false - -; Force fade-in fade-out transition even if theme doesn't specify it -ForceFadeTransition = false - -; Creates C_MUSICTHEME class in main parser to make it easier to use scriptable interface. -; It does not provide any coop with music parser. -CreateMainParserCMusicTheme = true - -; Logger level for Union console (DEBUG, INFO, WARN, ERROR, OFF) -LoggerLevelUnion=INFO - -; Logger level for ZSpy console (DEBUG, INFO, WARN, ERROR, OFF) -LoggerLevelZSpy=DEBUG -``` \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9a8a4ca --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs +mkdocs-material diff --git a/docs/scriptable-interface.md b/docs/scriptable-interface.md deleted file mode 100644 index 3c6d720..0000000 --- a/docs/scriptable-interface.md +++ /dev/null @@ -1,139 +0,0 @@ -# Scriptable interface (externals) -## Reference - -If you use Visual Studio Code with Daedalus extension from Kirides, you can copy `_externals` directory to your project root to register them for autocomplete. - -```cpp - -// --------------------------------------------------------------- -// 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_ActiveThemeID -// Holds the instance name/id of currently played song or the last song if none is playing now. -// --------------------------------------------------------------- -var string BassMusic_ActiveThemeID; - -// --------------------------------------------------------------- -// var string BassMusic_EventThemeFilename -// Holds the filename of theme in current event -// --------------------------------------------------------------- -var string BassMusic_EventThemeFilename; - -// --------------------------------------------------------------- -// var string BassMusic_EventhemeID -// Holds the instance name/id of theme in current eventr -// --------------------------------------------------------------- -var string BassMusic_EventThemeID; - -// --------------------------------------------------------------- -// BassMusic_Play: Play a CMusicTheme by script name. -// @param var string id: Name of CMusicTheme instance. -// --------------------------------------------------------------- -func void BassMusic_Play(var string id) {}; - -// --------------------------------------------------------------- -// BassMusic_OnEndEvent: Add event listener for the end/loop of music theme. -// @param var func callback: Function with signature func void CB() -// --------------------------------------------------------------- -func void BassMusic_OnEndEvent(var func callback) {}; - -// --------------------------------------------------------------- -// BassMusic_OnTransitionEvent: Add event listener for the moment when track is finishing and transition should start. -// @param var func callback: Function with signature func void CB(var int time_left_ms) -// --------------------------------------------------------------- -func void BassMusic_OnTransitionEvent(var func callback) {}; - -// --------------------------------------------------------------- -// BassMusic_OnChangeEvent: Add event listener for the change of a theme. -// @param var func callback: Function with signature func void CB() -// --------------------------------------------------------------- -func void BassMusic_OnChangeEvent(var func callback) {}; - -// --------------------------------------------------------------- -// BassMusic_SetFullScriptControl: Sets full script control state. When true, the engine won't change music themes. -// @param var int active: Boolean if full script control should be activated. -// --------------------------------------------------------------- -func void BassMusic_SetFullScriptControl(var int active) {}; - -// --------------------------------------------------------------- -// BassMusic_Opt_TransitionTime: Set TransitionTime option value. -// @param var float time: Transition time in miliseconds -// --------------------------------------------------------------- -func void BassMusic_Opt_TransitionTime(var float time) {}; - -// --------------------------------------------------------------- -// BassMusic_Opt_ForceDisableReverb: Set ForceDisableReverb option value. -// @param var int enabled: Boolean value -// --------------------------------------------------------------- -func void BassMusic_Opt_ForceDisableReverb(var int enabled) {}; - -// --------------------------------------------------------------- -// BassMusic_Opt_ForceFadeTransition: Set ForceFadeTransition option value. -// @param var int enabled: Boolean value -// --------------------------------------------------------------- -func void BassMusic_Opt_ForceFadeTransition(var int enabled) {}; -``` - -## Full Script Control - -It's possible to disable automatic scheduling of music by the engine by setting: -```cpp -BassMusic_SetFullScriptControl(true); -``` - -After that the changes of music zones or time will not interfere with controlling the playback from scripts. To create custom scheduling logic, you can use event subscribers: -```cpp -func void MyMusicEndSubscriber() -{ - if (STR_Compare(MEM_BassMusic_EventThemeID, "START_THEME") == 0) - { - BassMusic_Play("NEXT_THEME_1"); - }; - - if (STR_Compare(MEM_BassMusic_EventThemeID, "NEXT_THEME_1") == 0) - { - BassMusic_Play("NEXT_THEME_2"); - }; - - if (STR_Compare(MEM_BassMusic_EventThemeID, "NEXT_THEME_2") == 0) - { - BassMusic_Play("START_THEME"); - }; -}; - -BassMusic_OnEndEvent(MyMusicEndSubscriber); -BassMusic_Play("START_THEME"); -``` - -Each music theme needs to be defined as `C_MUSICTHEME` instance like: -```cpp -prototype Base_Theme(C_MUSICTHEME) -{ - file = ""; - transtype = 7; // TRANSITION_TYPE_ENDANDINTRO - transsubtype = 7; // TRANSITION_TYPE_ENDANDINTRO - reverbmix = -8; - reverbtime = 9000; - vol = 1; - loop = 1; -}; - -instance START_THEME(Base_Theme) -{ - file = "Start_Theme.wav"; -}; - -instance NEXT_THEME_1(Base_Theme) -{ - file = "Next_Theme_1.wav"; -}; - -instance NEXT_THEME_2(Base_Theme) -{ - file = "Next_Theme_2.wav"; -}; -``` \ No newline at end of file diff --git a/docs/transitions-effects.md b/docs/transitions-effects.md deleted file mode 100644 index c6b8a62..0000000 --- a/docs/transitions-effects.md +++ /dev/null @@ -1,15 +0,0 @@ -# Transition effects -zBassMusic can transition between music themes using simple fade-out and fade-in effects over a timespan. - -To use transitions, at least one must be true: -* **C_MUSICTHEME.transtype == zMUS_TR_INTRO (5)**: theme will use fade-in -* **C_MUSICTHEME.transtype == zMUS_TR_END (6)**: theme will use fade-out -* **C_MUSICTHEME.transtype == zMUS_TR_ENDANDINTRO (7)**: theme will use both fade-in and fade-out -* **BASSMUSIC.ForceFadeTransition** ini is set true, all themes will use both fade-in and fade-out - -Transition time can be set by **BASSMUSIC.TransitionTime** ini option. - -Scripts can control transition time dynamically using: -```cpp -BassMuisc_Opt_TransitionTime(3000.0); // 3 seconds -``` \ No newline at end of file