docs: add full getting-started

docs/docs/roadmap/index.md

@@ -53,6 +53,10 @@ hide:
 !!! question "New features?"
     We still may plan to implement some new features if they can provide value.
 
+!!! warning "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)"
     Before we release version v1.0.0 and mark zBassMusic as a finished product, we need to:
 

docs/docs/stylesheets/extra.css

@@ -28,7 +28,11 @@
     margin-top: 1rem;
 }
 
-.md-typeset code {
+/* .md-typeset code {
+    font-size: 0.8rem;
+} */
+
+.md-typeset .admonition {
     font-size: 0.8rem;
 }
 
@@ -53,4 +57,40 @@
 
 .zbassmusic-externals > ul {
     margin-top: 0.5rem;
+}
+
+.gh-release {
+    background: #111;
+    border-radius: 10px;
+    padding: 1rem;
+    margin-top: 1rem;
+    margin-bottom: 2rem;
+}
+
+.gh-release-title {
+    font-weight: bold;
+    margin-top: 0;
+    font-size: 1rem;
+}
+
+.gh-release pre {
+    overflow-x: hidden;
+}
+
+.gh-release-artifacts {
+    list-style: none !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    margin-top: 2rem !important;
+    display: grid !important;
+    grid-template-columns: repeat(2, 1fr);
+    grid-gap: 1rem;
+    font-weight: bold;
+}
+
+.gh-release-artifacts li {
+    list-style: none !important;
+    margin: 0 !important;
+    padding: 0 !important;
+
 }

docs/docs/user-guide/getting-started/crossfading.md

@@ -1 +1,27 @@
-# Crossfading
+# Crossfading
+
+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.
+
+```dae
+prototype C_MUSICTHEME_FIGHT(C_MUSICTHEME)
+{
+	file = "My_Super_Music.mp3"; 
+
+    // Use TRANSITION_TYPE_ENDANDINTRO to enable crossfade between themes
+	transtype = TRANSITION_TYPE_ENDANDINTRO;
+	transsubtype = TRANSITION_SUB_TYPE_MEASURE;
+	reverbmix = -12;
+	reverbtime = 9000;
+	vol = 1;
+	loop = 1;
+};
+```
+
+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).

docs/docs/user-guide/getting-started/index.md

@@ -1,2 +1,46 @@
+---
+hide:
+    - toc
+---
+
 # Getting Started
 
+To start working with zBassMusic, first we need to download the plugin. 
+We publish all releases on the [Releases](https://github.com/Silver-Ore-Team/zBassMusic/releases) page, so you can go there and download zBassMusic.
+Alternatively, below you should see the newest release:
+
+<div class="gh-release">
+    <p class="gh-release-title">&nbsp;</p>
+    <p class="gh-release-changelog">&nbsp;</p>
+    <ul class="gh-release-artifacts">
+    </ul>
+</div>
+
+<script type="text/javascript">
+    fetch('https://api.github.com/repos/Silver-Ore-Team/zBassMusic/releases')
+        .then(d => d.json())
+        .then(releases => {
+            const release = releases[0];
+            console.log(document.querySelector('.gh-release-title'));
+            document.querySelector('.gh-release-title').textContent = `${release.name} (${release.published_at})`;
+
+            document.querySelector('.gh-release-changelog').innerHTML = `<pre>${release.body}</pre>`;
+            for (var i = 0; i < release.assets.length; i++) {
+                const asset = release.assets[i];
+                const li = document.createElement('li');
+                li.innerHTML = `<a href="${asset.browser_download_url}">${asset.name}</a>`;
+                document.querySelector('.gh-release-artifacts').appendChild(li);
+            }
+        });
+</script>
+
+There are different kinds of files for different use cases.
+
+* `zBassMusic-{version}.zip`<br>ZIP archive with zBassMusic.dll and its dependencies. Use for loading the plugin directly from the disk.
+* `zBassMusic-{version}.vdf`<br>Gothic VDF volume with zBassMusic.dll and its dependencies packed under `System/Autorun`. 
+    It's for loading the plugin using an external loader like Union.
+* `zBassMusic-{version}-pdb.zip/vdf`<br>The same role as above but **-pdb** builds contain PDB debug symbols. 
+    You can use it if you are going to use a debugger and would like to see the source code instead of assembly for zBassMusic.
+
+
+When you download the files, we can proceed to [loading the plugin](plugin-loading.md)

docs/docs/user-guide/getting-started/music-definition.md

@@ -1 +1,32 @@
-# Music Definition
+# Music Definition
+
+zBassMusic uses the same music definitions as the original game, so you can work directly on existing `C_MUSICTHEME` instances. 
+The instances are in `Scripts/System/Music/MusicInst.d`.
+
+```dae
+prototype C_MUSICTHEME_FIGHT(C_MUSICTHEME)
+{
+    // With zBassMusic you can load mp3 and other music formats
+	file = "My_Super_Music.mp3"; 
+
+    // Use TRANSITION_TYPE_ENDANDINTRO to enable crossfade between themes
+	transtype = TRANSITION_TYPE_ENDANDINTRO;
+	transsubtype = TRANSITION_SUB_TYPE_MEASURE;
+
+    // reverbmix and reverbtime might have to be adjusted
+	reverbmix = -12;
+	reverbtime = 9000;
+	vol = 1;
+	loop = 1;
+};
+```
+
+## Caveat: Reverb Effect
+
+zBassMusic emulates the original reverb effects using `BASS_DX8_REVERB` from BASS library but it has strict limits on the
+acceptable parameters range. If you would like to use the effect, make sure that:
+
+* `reverbmix` is in range `[-96, 0]`
+* `reverbtime` is in range `[0.001, 3000]`
+
+If the parameter value is outside these ranges, the effect won't be applied.

docs/docs/user-guide/getting-started/plugin-loading.md

@@ -1 +1,106 @@
-# Plugin Loading
+# Plugin Loading
+
+The next step is loading zBassMusic.dll to the Gothic memory, so it activates. There are several ways of doing it depending on 
+your environment and expectations. Some methods are global for the whole Gothic installation where the plugin will always load
+indifferently if you start mod A, mod B or the original game. Other methods make it possible to isolate the plugin to a single
+mod, so it doesn't mess with others.
+
+During the development, it's fine to use global methods on a local installation but when you are going to ship the mod to other
+players, you should select an option with isolation. You never know if the player has a clean Gothic only for your mod or a gigadirctory 
+with hundreds of GothicStarter entries, so you don't want to break someone's game by loading unsolicited DLLs globally.
+
+## Union 1.0m
+
+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"
+
+    Choose either ZIP or VDF. Both work the same.
+
+    From ZIP release:<br>
+    Copy `zBassMusic.dll`, `UnionAPI.dll`, `bass.dll` <br>
+    To `<GOTHIC_DIR>/System/Autorun/`
+
+    From VDF release:<br>
+    Copy `zBassMusic.vdf` <br>
+    To `<GOTHIC_DIR>/Data/`
+
+!!! success "Isolated Method"
+
+    The isolated method is possible if you are placing your mod in `<GOTHIC_DIR>/Data/ModVDF` and declare .mod file in `YourMod.ini`.
+
+    From VDF release:<br>
+    Rename `zBassMusic.vdf` to `zBassMusic.mod`<br>
+    Copy `zBassMusic.mod`<br>
+    To `<GOTHIC_DIR>/Data/ModVDF/`
+
+    In `YourMod.ini` add an additional file to [FILES].VDF key:
+
+    ```ini
+    [FILES]
+    ; NOTICE DOUBLE SPACE!
+    ; If you use multiple VDF files, 
+    ; you have to separate them with TWO spaces
+    VDF=YourMod.mod  zBassMusic.mod 
+    ```
+
+## Standalone System Pack
+
+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"
+
+    From ZIP release:<br>
+    Copy `zBassMusic.dll`, `UnionAPI.dll`, `bass.dll` <br>
+    To `<GOTHIC_DIR>/System/`
+
+    Create `pre.load` file in `<GOTHIC_DIR>/System/` with content:
+    ```
+    zBassMusic.dll
+    ```
+
+## Standalone Ikarus
+
+!!! warning "Not supported now"
+
+    In the current release, we are hooking early into Gothic initialization, so Ikarus would load the plugin too late. In future releases, we may provide an alternative initialization that would be possible at any moment.
+
+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"
+
+    From ZIP release:<br>
+    Copy `zBassMusic.dll`, `UnionAPI.dll`, `bass.dll` <br>
+    To `<GOTHIC_DIR>/System/`
+
+    In your `Startup.d` add to Init:
+    ```dae
+    func void INIT_GLOBAL()
+    {
+	    Game_InitGerman();
+        LoadLibrary("zBassMusic.dll");
+        // ...
+    }
+    ```
+
+## Validate
+
+To check if zBassMusic was loaded you can either look into ZSpy for strings like:
+```
+zBassMusic 0.1.3 Release (build: 2024-05-20T10:21:26, branch: feature/cleanup, revision: 466f67cedf3c23bfb6aa555f90653f67bb61742a)
+```
+
+Alternatively, you can try to call one of the externals in your Daedalus scripts, for example:
+```dae
+
+    func void INIT_GLOBAL()
+    {   
+        BassMusic_SetFullScriptControl(false);
+        // ...
+    }
+```
+
+If you get an error about missing external, then zBassMusic wasn't loaded, so you have to double-check if the chosen loading method 
+was executed correctly. If you don't see any error, that means everything is fine and we can proceed to [music definitions](music-definition.md).

docs/docs/user-guide/index.md

@@ -1,3 +1,8 @@
+---
+hide:
+    - toc
+---
+
 # User Guide
 
 User Guide is the zBassMusic documentation dedicated to people who would like to include the plugin in their mod and use it as a music system.