Silver-Ore-Team · piotrmacha · May 23, 2024 · May 23, 2024
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -12,10 +12,10 @@ set(VDF_DIR "${CMAKE_SOURCE_DIR}/vdf")
 set(GOTHIC_USERAPI_DIR "${CMAKE_SOURCE_DIR}/gothic-userapi")
 
 set(CMAKE_CXX_STANDARD 23)
-if(${CMAKE_BUILD_RELEASE_PDB})
+if (${CMAKE_BUILD_RELEASE_PDB})
     set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} /Zi")
     set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} /DEBUG /OPT:REF /OPT:ICF")
-endif()
+endif ()
 
 include(cmake/union-api.cmake)
 include(cmake/gothic-api.cmake)
@@ -45,33 +45,33 @@ target_link_libraries(plugin PRIVATE union-api gothic-api bass)
 
 install(FILES $<TARGET_RUNTIME_DLLS:plugin> "${CMAKE_BINARY_DIR}/zBassMusic.dll" TYPE BIN)
 install(FILES $<TARGET_RUNTIME_DLLS:plugin> "${CMAKE_BINARY_DIR}/UnionAPI.dll" TYPE BIN)
-if(${BUILD_VDF})
+if (${BUILD_VDF})
     install(FILES "${CMAKE_BINARY_DIR}/script.vdfs" DESTINATION "${CMAKE_INSTALL_PREFIX}")
     install(SCRIPT "${VDF_DIR}/vdf.cmake")
     install(CODE "execute_process(COMMAND ${CMAKE_SOURCE_DIR}/vdf/GothicVDFS.exe /B \"${CMAKE_INSTALL_PREFIX}/script.vdfs\"
             WORKING_DIRECTORY \"${CMAKE_INSTALL_PREFIX}\")")
-endif()
+endif ()
 
-if(${BUILD_VDF})
+if (${BUILD_VDF})
     string(REPLACE "build" "install" INSTALL_DIR "${CMAKE_BINARY_DIR}")
     add_custom_target(plugin_vdf ALL
             COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR} --prefix ${INSTALL_DIR}
             DEPENDS plugin
             COMMENT "Run install to build VDF")
 
-    if(DEFINED ENV{COPY_VDF_TARGET})
+    if (DEFINED ENV{COPY_VDF_TARGET})
         add_custom_target(copy_vdf ALL
                 COMMAND ${CMAKE_COMMAND} -E copy "${INSTALL_DIR}/zBassMusic.vdf" "$ENV{COPY_VDF_TARGET}"
                 DEPENDS plugin_vdf
                 COMMENT "Copy plugin to target directory: $ENV{COPY_VDF_TARGET}")
-    endif()
-endif()
+    endif ()
+endif ()
 
-if(DEFINED ENV{COPY_DLL_TARGET})
+if (DEFINED ENV{COPY_DLL_TARGET})
     add_custom_target(copy_dll ALL
             COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_BINARY_DIR}/zBassMusic.dll" "$ENV{COPY_DLL_TARGET}/Autorun/zBassMusic.dll"
             COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_BINARY_DIR}/UnionAPI.dll" "$ENV{COPY_DLL_TARGET}/Autorun/UnionAPI.dll"
             COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_SOURCE_DIR}/dependencies/bass/lib/bass.dll" "$ENV{COPY_DLL_TARGET}/bass.dll"
             DEPENDS plugin
             COMMENT "Copy plugin to target directory: $ENV{COPY_DLL_TARGET}")
-endif()
+endif ()
diff --git a/CMakePresets.json b/CMakePresets.json
@@ -1,5 +1,5 @@
 {
-    "version": 3,
+  "version": 3,
   "configurePresets": [
     {
       "name": "windows-base",

diff --git a/README.md b/README.md
@@ -1,22 +1,25 @@
 # zBassMusic
-zBassMusic is a modern music system for Gothic I and Gothic II NotR based on [BASS Audio Library](https://www.un4seen.com/) distributed as a Union plugin. It replaces the old DirectMusic system to let the modders create music for Gothic as regular audio files instead of unfriendly DirectMusic format.  
 
-Features:
-* Music playback with modern audio formats like WAV, MP3, OGG
-* Out-of-the-box support for existing `C_MUSICTHEME` instances
-* Scriptable interface to control music playback from Daedalus scripts 
-* Loading music files from VDFS volumes (excluding .sgt)
-* Backwards compatibility with DirectMusic .sgt files - they are forwarded to original system
+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 Audio Library](https://www.un4seen.com/) to provide easier workflow for composers
+and additional functions for the
+perfect soundtrack design. The most important features include:
 
-## Project Status
+Features:
 
-The project is under development, but starting with the v0.1.0 version, we consider its core stable for general use. 
-Now we focus on implementing more advanced control over the playback & transitions, like fine-tuning the
-transition time points to cross-fade songs right on the beat.
+* Direct playback of common audio formats (WAV, OGG, MP3) instead of DirectMusic proprietary formats
+* Out-of-the-box support for existing music theme definitions (just change the audio file)
+* Alternative scheduling & transition systems to support smooth cross-fades 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)
 
 ## Getting Started
 
-Download `zBassMusic.vdf` and place it inside `<GOTHIC_ROOT>/Data` with Union installed to automatically load the system at the start of the game. With default settings you can use modern audio formats directly in `MusicInst.d` like:
+Download `zBassMusic.vdf` and place it inside `<GOTHIC_ROOT>/Data` with Union installed to automatically load the system
+at the start of the game. With default settings you can use modern audio formats directly in `MusicInst.d` like:
+
 ```cpp
 instance SYS_MENU(C_MUSICTHEME_DEF)
 {
@@ -39,52 +42,50 @@ instance SYS_MENU(C_MUSICTHEME_DEF)
 
 ## Documentation
 
-For more detailed information [check the project's Wiki](https://github.com/Silver-Ore-Team/zBassMusic/wiki).
+* [zBassMusic](https://silver-ore-team.github.io/zBassMusic/)
+* [User Guide](https://silver-ore-team.github.io/zBassMusic/user-guide/)
+    * [Getting Started](https://silver-ore-team.github.io/zBassMusic/user-guide/getting-started/)
+* [Reference](https://silver-ore-team.github.io/zBassMusic/reference/)
+* [Developer Guide](https://silver-ore-team.github.io/zBassMusic/developer-guide/)
 
 ## Build
 
-To build the project you need Visual Studio 2022 with v143 toolset (eg. 14.39). Then you can clone the repository and update submodules:
-```
-git clone git@github.com:Silver-Ore-Team/zBassMusic.git
-cd zBassMusic
-git submodule init --remote
-```
-
-The project is based on CMake, so you can open it in Visual Studio, CLion or any other IDE supporting CMake, and build `plugin` target to compile `zBassMusic.dll`. 
-
-Run `cmake --install out/build/x86-release --prefix out/install/x86-release` to generate release directory with all required DLLs and VDF file to include in Gothic.
+Build instructions are available in
+the [Developer Guide](https://silver-ore-team.github.io/zBassMusic/developer-guide/).
 
 ## Support
 
-If you have found a bug in zBassMusic, please [create an issue](https://github.com/Silver-Ore-Team/zBassMusic/issues/new) and state your problem in detail. 
-Include zBassMusic version, Union version and your environment (other plugins, stack traces etc.).
+If you have found a bug in zBassMusic,
+please [create an issue](https://github.com/Silver-Ore-Team/zBassMusic/issues/new).
 
-Please enable Union console using `SystemPack.ini` and try to get the logs to include in the report.  
-```ini
-[CORE]
-ShowDebugWindow = true
-UseDebugWindowHost = true
-```
+Before creating a new issue, you can try to enable debug logging and get the logs to include in the issue.
+See [Debugging](https://silver-ore-team.github.io/zBassMusic/user-guide/debugging/)
 
 ### Discord
 
-You can meet the plugin authors on Discord if you got a quick question. Look for `tehe`.
-It's not an official support channel, so keep in mind that our SLA varies from 3 minutes to 71 weeks.   
+You can contact the authors and maintainers on Discord. 
+Look for [@tehe.official](https://discordapp.com/users/1014655735856111678).
 
 #### Gothic Modding Community
+
 Biggest community of international Gothic modders.
 https://discord.gg/6rQQGVQK
 
 #### 🇵🇱 Historia Neka
-Official Discord of Nek's History, the mod we are working on and started zBassMusic for it. 
-https://discord.gg/cvd6jhKB
+
+Official Discord of Nek's History, the mod we are working on and started zBassMusic for it.
+https://discord.gg/cvd6jhKB`
 
 ## License
 
 zBassMusic is licensed under [MIT license](LICENSE) excluding some dependencies.
 
-[union-api](https://gitlab.com/union-framework/union-api) and [gothic-api](https://gitlab.com/union-framework/gothic-api) are licensed under [GNU GENERAL PUBLIC LICENSE V3](https://gitlab.com/union-framework/union-api-/blob/main/LICENSE).
+[union-api](https://gitlab.com/union-framework/union-api)
+and [gothic-api](https://gitlab.com/union-framework/gothic-api) are licensed
+under [GNU GENERAL PUBLIC LICENSE V3](https://gitlab.com/union-framework/union-api-/blob/main/LICENSE).
 
-BASS library is licensed under a proprietary license that's free for non-commercial use only. For commercial licensing please refer to [www.un4seen.com](https://www.un4seen.com/).
+BASS library is licensed under a proprietary license that's free for non-commercial use only. For commercial licensing
+please refer to [www.un4seen.com](https://www.un4seen.com/).
 
-GothicVDFS 2.6 [Copyright (c) 2001-2003, Nico Bendlin, Copyright (c) 1994-2002, Peter Sabath / TRIACOM Software GmbH](vdf/License.txt)
+GothicVDFS
+2.6 [Copyright (c) 2001-2003, Nico Bendlin, Copyright (c) 1994-2002, Peter Sabath / TRIACOM Software GmbH](vdf/License.txt)
diff --git a/cmake/union-api.cmake b/cmake/union-api.cmake
@@ -11,10 +11,10 @@ target_link_directories(union-api PUBLIC "${UNION_API_DIR}/union-api")
 file(GLOB_RECURSE UNION_SOURCES "${UNION_API_DIR}/union-api/union-api.cpp" "${UNION_API_DIR}/union-api/Union/Memory.cpp")
 target_sources(union-api PRIVATE ${UNION_SOURCES})
 
-if("${CMAKE_BUILD_TYPE}" STREQUAL "Debug")
+if ("${CMAKE_BUILD_TYPE}" STREQUAL "Debug")
     target_compile_definitions(union-api PUBLIC WIN32 _DEBUG _CONSOLE _UNION_API_DLL PRIVATE _UNION_API_BUILD)
-elseif("${CMAKE_BUILD_TYPE}" STREQUAL "Release")
+elseif ("${CMAKE_BUILD_TYPE}" STREQUAL "Release")
     target_compile_definitions(union-api PUBLIC WIN32 NDEBUG _CONSOLE _UNION_API_DLL PRIVATE _UNION_API_BUILD)
-else()
+else ()
     message(FATAL_ERROR "Invalid $CMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} not in range [Debug, Release]")
-endif()
+endif ()
diff --git a/docs/docs/developer-guide/contributing/index.md b/docs/docs/developer-guide/contributing/index.md
@@ -1,13 +1,15 @@
 # Contributing
 
-We welcome contributions to the project with open arms. 
+We welcome contributions to the project with open arms.
 This document will guide you through the process of contributing to the project.
 
 ## Prerequisites
 
 * Fork the repository and setup project as described in the [Developer Guide](./index.md)
 * Familiarize yourself with the [Style Guide](../style-guide/index.md)
-* Familiarize yourself with the [Code of Conduct](https://github.com/Silver-Ore-Team/zBassMusic/blob/main/CODE_OF_CONDUCT.md) (or just be a nice guy, don't need to read it)
+* Familiarize yourself with
+  the [Code of Conduct](https://github.com/Silver-Ore-Team/zBassMusic/blob/main/CODE_OF_CONDUCT.md) (or just be a nice
+  guy, don't need to read it)
 
 ## What can I contribute?
 
@@ -23,12 +25,12 @@ You can find contact to maintainers on the [Home page](../../index.md).
 
 ## How to contribute?
 
-1. Create a new branch from the `main` branch on your fork. 
+1. Create a new branch from the `main` branch on your fork.
    We recommend naming the branch after the issue you are working on with a prefix `feature/`,
-   `bugfix/`, `docs/`, etc. For example, `bugfix/unsafe_memory_access`. 
+   `bugfix/`, `docs/`, etc. For example, `bugfix/unsafe_memory_access`.
 2. Make your changes.
 3. Test your changes.
-4. Commit your changes. 
+4. Commit your changes.
 5. Push your changes to your fork.
 6. Create a pull request to the `main` branch of the main repository from your fork.
 
@@ -37,16 +39,16 @@ You can find contact to maintainers on the [Home page](../../index.md).
 After you create a pull request, the maintainers will review your changes and provide feedback.
 You may need to make additional changes before your pull request is accepted.
 
-If you have any questions, feel free to ask them in the pull request or contact the maintainers directly. 
-In case you can't do the changes yourself, 
-let us know, and we will help you by providing guidance or doing the changes ourselves 
+If you have any questions, feel free to ask them in the pull request or contact the maintainers directly.
+In case you can't do the changes yourself,
+let us know, and we will help you by providing guidance or doing the changes ourselves
 (you will still be credited as a contributor).
 
 If we don't accept your pull request, don't be discouraged. We will provide feedback on why it was rejected.
 
 If you don't get any feedback for a long time, feel free to ping the maintainers in the pull request.
 
-If we haven't heard from you for more than 21 days, 
+If we haven't heard from you for more than 21 days,
 we may close the pull request or take it over and finish it ourselves.
 
 ## Branching & Merging Model
@@ -60,18 +62,19 @@ We use the Trunk-Based Development model for branching and Squash Merging for me
 
 This model is chosen to keep the repository clean and make it easier to maintain.
 
-In special cases, 
+In special cases,
 we may create a separate trunk for some features if they are too big or too risky to be developed in the main trunk.
-In this case the trunk will be named `trunk/FEATURE_NAME` 
+In this case the trunk will be named `trunk/FEATURE_NAME`
 and will be merged back to the main trunk after the feature is finished.
 All the rules from the Trunk-Based Development model still apply but to the feature trunk instead of the main trunk.
 
 ## License
 
 By contributing to the project, you agree to license your contributions under the project's license.
-You grant the project maintainers a non-exclusive, irrevocable, worldwide, royalty-free, sublicensable, transferable license to use, reproduce, modify, prepare derivative works of, distribute, publicly perform, publicly display, and otherwise exploit your contributions[^1].
+You grant the project maintainers a non-exclusive, irrevocable, worldwide, royalty-free, sublicensable, transferable
+license to use, reproduce, modify, prepare derivative works of, distribute, publicly perform, publicly display, and
+otherwise exploit your contributions[^1].
 
-
-[^1]: **Legal to human:** that just means you can't say "stop using my code" after you contributed it, we don't owe you, 
-    anything, and we can do whatever we want with your code. You are stil the code author, though, and we can't
-    remove your name from the list of contributors or claim that we wrote the code you contributed.
+[^1]: **Legal to human:** that just means you can't say "stop using my code" after you contributed it, we don't owe you,
+anything, and we can do whatever we want with your code. You are stil the code author, though, and we can't
+remove your name from the list of contributors or claim that we wrote the code you contributed.
diff --git a/docs/docs/developer-guide/index.md b/docs/docs/developer-guide/index.md
@@ -13,13 +13,14 @@ It explains the architecture of the system, how to build it, and how to extend i
 ## Setup Project
 
 !!! info "CMake vs IDE"
-    The setup instructions assume no IDE is used, and CMake is called from the command line. 
-    If you use Visual Studio, CLion or any other IDE, you can use the CMake integration from it. 
+The setup instructions assume no IDE is used, and CMake is called from the command line.
+If you use Visual Studio, CLion or any other IDE, you can use the CMake integration from it.
 
 ### Fork Repository
 
 Unless you are an internal contributor, you can't push directly to the repository, so you have to fork it first.
-To do it, click the "Fork" button in the top right corner of the [repository page](https://github.com/Silver-Ore-Team/zBassMusic).
+To do it, click the "Fork" button in the top right corner of
+the [repository page](https://github.com/Silver-Ore-Team/zBassMusic).
 
 ### Clone Repository
 

diff --git a/docs/docs/developer-guide/style-guide/index.md b/docs/docs/developer-guide/style-guide/index.md
@@ -5,31 +5,31 @@
 Use `.clang-format` to format your code. You can find the configuration file in the root of the repository.
 
 ??? info "Naming Rules"
-    * use `UPPERCASE` for constants, macros, and preprocessor directives
-    * use `PascalCase` for classes, structs, enums, and namespaces
-    * use `PascalCase` for methods and properties
-    * use `PascalCase` for functions
-    * use `kebabCase` for local variables
-    * prefix private fields with `m_`
-    * prefix static fields with `s_`
-    * prefix static variables with `s_`
-    * prefix global variables with `g_`
+* use `UPPERCASE` for constants, macros, and preprocessor directives
+* use `PascalCase` for classes, structs, enums, and namespaces
+* use `PascalCase` for methods and properties
+* use `PascalCase` for functions
+* use `kebabCase` for local variables
+* prefix private fields with `m_`
+* prefix static fields with `s_`
+* prefix static variables with `s_`
+* prefix global variables with `g_`
 
 ??? info "Other Rules"
-    * use `#pragma once` instead of include guards
-    * use the same namespace as the folder structure
-        * excluding `Gothic` directory which has `GOTHIC_NAMESPACE` defined (subdirectories should use new namespace)
-        * excluding `Hooks.hpp` files, which may need `GOTHIC_NAMESPACE` to implement member functions
-    * prefer single class per file
-    * use the same file name as the class name
-    * use `#pragma region` and `#pragma endregion` to group related code for bigger files
-    * don't use `using namespace` in header files
-    * can use `using namespace` in source files
-    * don't use `using namespace std` in any file
-    * avoid use `using namespace X;` where X is a namespace of vendor code
-    * can use `using namespace X;` where X is the project namespace
-
-## Design Principles 
+* use `#pragma once` instead of include guards
+* use the same namespace as the folder structure
+* excluding `Gothic` directory which has `GOTHIC_NAMESPACE` defined (subdirectories should use new namespace)
+* excluding `Hooks.hpp` files, which may need `GOTHIC_NAMESPACE` to implement member functions
+* prefer single class per file
+* use the same file name as the class name
+* use `#pragma region` and `#pragma endregion` to group related code for bigger files
+* don't use `using namespace` in header files
+* can use `using namespace` in source files
+* don't use `using namespace std` in any file
+* avoid use `using namespace X;` where X is a namespace of vendor code
+* can use `using namespace X;` where X is the project namespace
+
+## Design Principles
 
 ### Separation of Concerns
 
@@ -39,13 +39,13 @@ larger concept being the aggregate of member concepts.
 
 ### Keep It Stupid Simple (KISS)
 
-Code should be simple and easy to understand. Don't overengineer, don't over-abstract, 
+Code should be simple and easy to understand. Don't overengineer, don't over-abstract,
 don't generalize specializations that already provide everything you need.
 
 ## Memory & Pointers
 
-Pointers of objects shared between multiple consumers are created and managed by an owner. The owner shares the 
-object as a const reference or a reference if the object must be mutable. 
+Pointers of objects shared between multiple consumers are created and managed by an owner. The owner shares the
+object as a const reference or a reference if the object must be mutable.
 
 Objects may be owner-less if shared using std::shared_ptr.
 
@@ -58,7 +58,8 @@ Don't dereference a reference unless you absolutely have to.
 ### Hooks
 
 * Prefer PartialHook if you don't need to wrap the target function from both sides.
-* PartialHook: avoid subtracting esp further than the current function frame. Different callers will have different stack offsets.
+* PartialHook: avoid subtracting esp further than the current function frame. Different callers will have different
+  stack offsets.
 
 ## Would you add or change something?