docs: setup mkdocs as a static page generator, write some articles

Silver-Ore-Team · May 23, 2024 · c508235 · c508235
1 parent e261e82
commit c508235
Show file tree

Hide file tree

Showing 37 changed files with 379 additions and 177 deletions.
diff --git a/docs/docs/configuration/index.md b/docs/docs/configuration/index.md
@@ -0,0 +1 @@
+# Configuration
diff --git a/docs/docs/developer-guide/architecture/index.md b/docs/docs/developer-guide/architecture/index.md
@@ -0,0 +1 @@
+# Architecture
diff --git a/docs/docs/developer-guide/code-style/index.md b/docs/docs/developer-guide/code-style/index.md
@@ -0,0 +1 @@
+# Code Style
diff --git a/docs/docs/developer-guide/contributing/index.md b/docs/docs/developer-guide/contributing/index.md
@@ -0,0 +1 @@
+# Contributing
diff --git a/docs/docs/developer-guide/environment/index.md b/docs/docs/developer-guide/environment/index.md
@@ -0,0 +1 @@
+# Environment
diff --git a/docs/docs/developer-guide/index.md b/docs/docs/developer-guide/index.md
@@ -0,0 +1 @@
+# Developer Guide
diff --git a/docs/docs/images/android-chrome-192x192.png b/docs/docs/images/android-chrome-192x192.png
diff --git a/docs/docs/images/android-chrome-512x512.png b/docs/docs/images/android-chrome-512x512.png
diff --git a/docs/docs/images/apple-touch-icon.png b/docs/docs/images/apple-touch-icon.png
diff --git a/docs/docs/images/favicon-16x16.png b/docs/docs/images/favicon-16x16.png
diff --git a/docs/docs/images/favicon-32x32.png b/docs/docs/images/favicon-32x32.png
diff --git a/docs/docs/images/favicon.ico b/docs/docs/images/favicon.ico
diff --git a/docs/docs/images/favicon@2x.png b/docs/docs/images/favicon@2x.png
diff --git a/docs/docs/images/logo.svg b/docs/docs/images/logo.svg
diff --git a/docs/docs/images/site.webmanifest 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"}
diff --git a/docs/docs/index.md 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).
+        
+
+<div class="grid cards" markdown>
+
+-  ::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)
+
+</div>
+
+
+## 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&#8209;api](https://gitlab.com/union-framework/union-api) &mdash;&nbsp;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.
+
+<div class="zbassmusic-contributos" markdown>
+
+![Mosaic of zBassMusic contributors](https://contrib.nn.ci/api?repo=Silver-Ore-Team/zBassMusic)
+
+</div>
+
+[^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.
diff --git a/docs/docs/javascripts/mathjax.js 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()
+  })
diff --git a/docs/docs/reference/index.md b/docs/docs/reference/index.md
@@ -0,0 +1 @@
+# Reference
diff --git a/docs/docs/roadmap/index.md 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
diff --git a/docs/docs/stylesheets/extra.css 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;
+}
diff --git a/docs/docs/user-guide/debugging/index.md b/docs/docs/user-guide/debugging/index.md
diff --git a/docs/docs/user-guide/define-music.md b/docs/docs/user-guide/define-music.md
@@ -0,0 +1 @@
+# Define Music
diff --git a/docs/docs/user-guide/getting-started/crossfading.md b/docs/docs/user-guide/getting-started/crossfading.md
@@ -0,0 +1 @@
+# Crossfading
diff --git a/docs/docs/user-guide/getting-started/index.md 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
@@ -0,0 +1 @@
+# Music Definition
diff --git a/docs/docs/user-guide/getting-started/plugin-loading.md b/docs/docs/user-guide/getting-started/plugin-loading.md
@@ -0,0 +1 @@
+# Plugin Loading
diff --git a/docs/docs/user-guide/index.md b/docs/docs/user-guide/index.md
@@ -0,0 +1 @@
+# User Guide
diff --git a/docs/docs/user-guide/scripting/custom-scheduler.md b/docs/docs/user-guide/scripting/custom-scheduler.md
@@ -0,0 +1 @@
+# Custom Scheduler
diff --git a/docs/docs/user-guide/scripting/index.md b/docs/docs/user-guide/scripting/index.md
@@ -0,0 +1 @@
+# Scripting (Daedalus)
diff --git a/docs/docs/user-guide/transition-scheduler/index.md b/docs/docs/user-guide/transition-scheduler/index.md
@@ -0,0 +1 @@
+# Transitions Scheduler
diff --git a/docs/docs/user-guide/transition-scheduler/instant.md b/docs/docs/user-guide/transition-scheduler/instant.md
@@ -0,0 +1 @@
+# Instant Transition
diff --git a/docs/docs/user-guide/transition-scheduler/on-beat.md b/docs/docs/user-guide/transition-scheduler/on-beat.md
@@ -0,0 +1 @@
+# On Beat Transition