[WIP] Upgrade Docusaurus + Docs rearranging

docs/architecture.md

@@ -6,7 +6,9 @@ sidebar_label: Architecture
 
 This section describes the architecture of the project.
 
-## Directory Structure
+## Structure
+
+The Bemuse project is a **monorepo**. This means every package that shapes the project lives inside the same repository, which allows for easier development process.
 
 <dl>
   <dt>bin</dt>  
@@ -19,21 +21,23 @@ This section describes the architecture of the project.
   <dt>docs</dt>  
   <dd>This documentation.</dd>
 
+  <dt>packages</dt>  
+  <dd>Contains projects closely-related to the core Bemuse project. These are published into separate npm packages.</dd>
+
   <dt>public</dt>  
-  <dd>Files that will be deployed verbatim to the server, **except for**
-  `index.html`, where the boot script will be inlined. These include
+  <dd>Files that will be deployed verbatim to the server, <strong>except for</strong>
+  <code>index.html</code>, where the boot script will be inlined. These include
   skin files.</dd>
 
-  <dt>spec</dt>  
-  <dd>Contains the unit tests. Its directory structure resembles the `src`
-  directory.</dd>
-
   <dt>src</dt>  
-  <dd>Contains the production code. Code is split into *modules* for
+  <dd>Contains the production code. Code is split into <em>modules</em> for
   different parts of the application.</dd>
 
   <dt>tasks</dt>  
   <dd>Gulp tasks to run test server, build, test the application.</dd>
+
+  <dt>website</dt>  
+  <dd>The code that powers this documentation. We use <a href="https://docusaurus.io/">Docusaurus</a> to build our documentation as a static website.</dd>
 </dl>
 
 ## Important Modules
@@ -51,14 +55,14 @@ modules.
   executed. Main modules include <code>app</code>, the game, and <code>test</code>, the unit
   tests. Upon building, the boot script will be inlined into
   <code>index.html</code>.
-    
-  **Rationale:** No one likes blank white page. We want the user to
-  see the application starting up as soon as possible, even though it
-  is simply a loading indicator. To make this *blazingly fast*, we
-  keep the compiled size of the `boot` very small, and inline that
-  compiled code directly into the HTML file. So, no round-trip HTML
-  requests\! If they can load the HTML, they *will* see the loading
-  bar.</dd>
+
+**Rationale:** No one likes blank white page. We want the user to
+see the application starting up as soon as possible, even though it
+is simply a loading indicator. To make this _blazingly fast_, we
+keep the compiled size of the `boot` very small, and inline that
+compiled code directly into the HTML file. So, no round-trip HTML
+requests\! If they can load the HTML, they _will_ see the loading
+bar.</dd>
 
   <dt>app</dt>  
   <dd>This is the main module of the game's application flow. Executing
@@ -76,25 +80,17 @@ modules.
   for judging notes, calculating score, and rendering the scene.</dd>
 </dl>
 
-## Related Projects
+## Packages
 
-Apart from the `bemuse` project, we also maintain other closely-related
-projects in a separate repository.
+We also maintain other closely-related packages. These used to live in their own repository, but we've merged them into the main Bemuse repo for easier development.
 
 <dl>
-  <dt><a href="https://github.com/bemusic/bms-js">bemusic/bms-js</a></dt>  
-  <dd>This project is a BMS parser written in JavaScript. It is written in
-    plain ES5 for maximum portability.</dd>
-
-  <dt><a href="https://github.com/bemusic/bmspec">bemusic/bmspec</a></dt>  
-  <dd>This project is an executable specification of the BMS file format.
-  It is used to make sure that bms-js can properly parse BMS file
-  format, especially the edge cases.</dd>
-
-  <dt><a href="https://github.com/bemusic/bemuse-tools">bemusic/bemuse-tools</a></dt>  
-  <dd>This repository contains the command-line tools needed to convert a BMS package
-  into a Bemuse package. Traditional BMS packages are optimized for
-  offline playing. They are distributed as a large <code>.zip</code>
-  file with <code>.wav</code>, <code>.mpg</code>, and <code>.bms</code> files.
-  This is not suitable for web consumption.</dd>
+  <dt><a href="https://github.com/bemusic/bemuse/tree/master/packages/bms">bms-js</a></dt>  
+  <dd>This package is a BMS parser written in JavaScript.</dd>
+
+  <dt><a href="https://github.com/bemusic/bemuse/tree/master/packages/bmson">bmson</a></dt>  
+  <dd>This package contains various functions useful for working with bmson files.</dd>
+
+  <dt><a href="https://github.com/bemusic/bemuse/tree/master/packages/bemuse-tools">bemuse-tools</a></dt>  
+  <dd>This package contains the command-line tools to convert a BMS package into a Bemuse package. Traditional BMS packages are optimized for offline playing. They are distributed as a large <code>.zip</code> file with <code>.wav</code>, <code>.mpg</code>, and <code>.bms</code> files.</dd>
 </dl>

docs/gameplay.md → docs/faq.md

@@ -1,6 +1,6 @@
 ---
-id: gameplay
-title: Gameplay
+id: faq
+title: FAQ
 ---
 
 ## How do I adjust the speed?
@@ -15,8 +15,8 @@ As a web-based game, it does not have low-level access to the audio
 driver. There are many factors that affect the audio latency in this
 game (and web-based audio applications in general):
 
-  - The browser's implementation of the Web Audio technology
-  - Your sound card driver and settings on your operating system
+* The browser's implementation of the Web Audio technology
+* Your sound card driver and settings on your operating system
 
 Bemuse has a mechanism for delay compensation. Simply open the options
 screen and enter your system’s audio+input latency. You can click on the

docs/scoring-and-judgment.md

@@ -3,95 +3,67 @@ id: scoring-and-judgment
 title: Scoring and Judgment
 ---
 
-The scoring system and judgment system in Bemuse focuses on both
-accuracy and combo.
+The scoring system and judgment system in Bemuse focuses on both accuracy and combo.
 
 ## Judgment
 
-When hitting the note, the accuracy of your button press will be judged
-according to this table:
-
-|      Name      | Maximum Offset (ms) | Accuracy Score |
-|:--------------:| -------------------:| --------------:|
-|   METICULOUS!  |                  20 |           100% |
-|     PRECISE!   |                  50 |            80% |
-|      GOOD!     |                 100 |            50% |
-|     OFFBEAT!   |                 200 |             0% |
-|     MISSED!    |                  -- |             0% |
-
-<div class="srcref admonition">
-<p class="first admonition-title">Source code reference</p>
-<ul class="last simple">
-<li>Defined at <a class="reference external" href="https://github.com/bemusic/bemuse/blob/bf96099/src/game/judgments.js#L7-14">src/game/judgments.js:7-14</a> (judgment timegate)</li>
-<li>Defined at <a class="reference external" href="https://github.com/bemusic/bemuse/blob/bf96099/src/game/judgments.js#L51-58">src/game/judgments.js:51-58</a> (judgment weight)</li>
-</ul>
-</div>
-
-## Scoring
-
-The player's score is calculated from this formula:
-
-
-<div class="math">
-  \[\begin{split}\text{score} &amp;= 500000 \times \text{accuracy}
-    + 55555 \times \text{combo bonus} \\[10pt]
-  \text{accuracy} &amp;= \frac{
-    \sum\text{accuracy score}
-  }{\sum\text{total combos}} \\[10pt]
-  \text{combo bonus} &amp;= \frac{
-    \sum_{c \in \text{combos}}{\text{combo level}(c)}
-  }{\sum_{i = 1}^{\text{total combos}}{\text{combo level}(i)}} \\[10pt]
-  \text{combo level}(c) &amp;= \begin{cases}
-    0 &amp; c = 0 \\
-    1 &amp; 1 \leq c \leq 22 \\
-    2 &amp; 23 \leq c \leq 50 \\
-    3 &amp; 51 \leq c \leq 91 \\
-    4 &amp; 92 \leq c \leq 160 \\
-    6 &amp; 161 \leq c
-  \end{cases}\end{split}\]
-</div>
-
-
-Here's how the combo level formula comes from. Let's assume, for
-simplicity, a player with 99% hit rate, regardless of difficulty. The
-probability that the player will attain \\(c\\) combos is \\(0.99^c\\).
-
-Now we have 6 combo levels. The probability that the player will attain
-that level gradually decreases. Therefore, the minimum combo is
-\\(\left\lceil\log_{0.99} p\right\rceil\\).
-
-| Combo Level | Max. Probability |  Min. Combo |
-| -----------:| ----------------:| -----------:|
-|           1 |             100% |           1 |
-|           2 |              80% |          23 |
-|           3 |              60% |          51 |
-|           4 |              40% |          92 |
-|           5 |              20% |         161 |
-
-<div class="srcref outdated admonition">
-<p class="first admonition-title">Source code reference</p>
-<ul class="last simple">
-<li class="outdated">Defined at <a class="reference external" href="https://github.com/bemusic/bemuse/blob/bf96099/src/game/state/player-stats.js#L27-29">src/game/state/player-stats.js:27-29</a> (score) [outdated: 17be8477]</li>
-<li>Defined at <a class="reference external" href="https://github.com/bemusic/bemuse/blob/bf96099/src/game/state/player-stats.js#L99-106">src/game/state/player-stats.js:99-106</a> (combo)</li>
-</ul>
-</div>
-
-# Grading
+When hitting the note, the accuracy of your button press will be judged according to this table:
+
+| Judgment   | Normal | Level5 | Level4 | Level3 | Beginner |
+| ---------- | -----: | -----: | -----: | -----: | -------: |
+| Meticulous |   20ms |   21ms |   22ms |   23ms |     24ms |
+| Precise    |   50ms |   60ms |   70ms |   80ms |    100ms |
+| Good       |  100ms |  120ms |  140ms |  160ms |    180ms |
+| Offbeat    |  200ms |  200ms |  200ms |  200ms |    200ms |
+
+The different timegates are designed to make the game easier for beginners, with a gradual increase in difficulty the harder the song gets. They are divided as follows:
+
+| Timegate | Song Level |
+| -------- | ---------: |
+| Beginner |        1-2 |
+| Level3   |          3 |
+| Level4   |          4 |
+| Level5   |          5 |
+| Normal   |         6+ |
+
+The final score is split into 2 parts:
+
+* 500000 for accuracy
+* 55555 for combo bonus
+
+Each combo has an associated score.
+
+| Combo number | Combo score |
+| -----------: | ----------: |
+|            0 |           0 |
+|         1–22 |           1 |
+|        23-50 |           2 |
+|        51-91 |           3 |
+|       92–160 |           4 |
+|        161~∞ |           5 |
+
+Combo bonus is the sum of combo score for each hit, divided by maximum possible value, times 55555.
+
+**Example:** There are 100 notes. 60 notes have been hit, I missed a note, and hit 39 other notes.
+
+* Obtained combo score = 108 for first 60 notes + 56 for 39 other notes = `164`
+* Maximum possible combo score = `237`
+* Combo bonus = `164 / 237 * 55555 = 38443`
+
+## Grading
 
 After playing the game, the grade is calculated according to this table:
 
 | Grade | Minimum Score |
-| ----- | -------------:|
-|   F   |             0 |
-|   D   |        300000 |
-|   C   |        350000 |
-|   B   |        400000 |
-|   A   |        450000 |
-|   S   |        500000 |
-
-<div class="srcref admonition">
-<p class="first admonition-title">Source code reference</p>
-<ul class="last simple">
-<li>Defined at <a class="reference external" href="https://github.com/bemusic/bemuse/blob/bf96099/src/rules/grade.js#L2-12">src/rules/grade.js:2-12</a> (grade)</li>
-</ul>
-</div>
+| ----- | ------------: |
+| F     |             0 |
+| D     |        300000 |
+| C     |        350000 |
+| B     |        400000 |
+| A     |        450000 |
+| S     |        500000 |
+
+## References
+
+* The original [pull request](https://github.com/bemusic/bemuse/pull/446) implementing the scoring system.
+* [Essay by @dtinth](https://qiita.com/dtinth/items/5b9f6b876a0a777eec50) regarding the new timegates & scoring.

website/i18n/en.json

@@ -12,8 +12,8 @@
     "BMS Support": "BMS Support",
     "colors": "Colors",
     "developer-guide": "Developer Guide",
+    "faq": "FAQ",
     "game-loop": "The Game Loop",
-    "gameplay": "Gameplay",
     "music-server": "How to Host a Music Server",
     "Music Server": "Music Server",
     "options": "Game Options and Configuration",
@@ -28,6 +28,7 @@
     "Discord": "Discord",
     "GitHub": "GitHub",
     "Users": "Users",
+    "Creators": "Creators",
     "Developers": "Developers"
   },
   "pages-strings": {

website/package.json

@@ -12,6 +12,6 @@
     "rename-version": "docusaurus-rename-version"
   },
   "devDependencies": {
-    "docusaurus": "^1.0.15"
+    "docusaurus": "^1.1.1"
   }
 }

website/pages/en/contribute.js

@@ -1,3 +1,5 @@
+/* eslint-disable no-unused-vars */
+
 /**
  * Copyright (c) 2017-present, Facebook, Inc.
  *
@@ -18,7 +20,7 @@ function docUrl (doc, language) {
   return siteConfig.baseUrl + 'docs/' + (language ? language + '/' : '') + doc
 }
 
-function pageUrl (page, language) { // eslint-disable-line
+function pageUrl (page, language) {
   return siteConfig.baseUrl + (language ? language + '/' : '') + page
 }
 
@@ -27,23 +29,26 @@ Bemuse is a free and open-source game, licensed under AGPLv3. It is developed by
 [many contributors](https://github.com/bemusic/bemuse/graphs/contributors) in their spare time,
 and your contribution helps us deliver new features and bug fixes quickly.
 
-Contributions are always welcome! Thank you for helping us make this game better!
+Thank you for helping us make this game better!
 `
 
 class Help extends React.Component {
   render () {
     const supportLinks = [
       {
-        content:
-          `Follow the [developer documentation](${docUrl('developer-guide.html')}) to get started. Don't forget to read our [coding guidelines](https://github.com/bemusic/bemuse/blob/master/CONTRIBUTING.md) as well.`,
+        content: `Follow the [developer documentation](${docUrl(
+          'developer-guide.html'
+        )}) to get started. Don't forget to read our [coding guidelines](https://github.com/bemusic/bemuse/blob/master/CONTRIBUTING.md) as well.`,
         title: 'Read the docs'
       },
       {
-        content: 'Read through our [issues thread](https://github.com/bemusic/bemuse/issues) and pick an issue. If you\'re confused, we recommend starting out with [these issues](https://github.com/bemusic/bemuse/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).',
+        content:
+          "Read through our [issues thread](https://github.com/bemusic/bemuse/issues) and pick an issue. If you're confused, we recommend starting out with [these issues](https://github.com/bemusic/bemuse/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).",
         title: 'Pick an issue'
       },
       {
-        content: "We have a [Waffle board](https://waffle.io/bemusic/bemuse) which we use to track this project's development progress.",
+        content:
+          "We have a [Waffle board](https://waffle.io/bemusic/bemuse) which we use to track this project's development progress.",
         title: 'Track progress'
       }
     ]

website/pages/en/index.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-unused-vars */
 'use strict'
 
 const React = require('react')
@@ -206,7 +207,7 @@ const FeatureTour = props => (
       image={
         <BrowserScreenshot
           alt='Screenshot'
-          src={imgUrl('screenshots/music-select.jpg')}
+          src={imgUrl('screenshots/music-server.png')}
         />
       }
       imageAlign='left'

website/sidebars.json

@@ -1,13 +1,7 @@
 {
   "docs": {
-    "Users": [
-      "user-guide",
-      "gameplay",
-      "scoring-and-judgment",
-      "music-server",
-      "bms-support",
-      "bms-extensions"
-    ],
+    "Users": ["user-guide", "scoring-and-judgment", "faq"],
+    "Creators": ["music-server", "bms-support", "bms-extensions"],
     "Developers": [
       "developer-guide",
       "architecture",